POST
/
v1
/
customers
curl --request POST \
  --url https://api.hyperline.co/v1/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Acme",
  "type": "corporate",
  "currency": "EUR",
  "country": "FR",
  "vat_number": "FR123456789",
  "vat_rate_custom": 1,
  "external_id": "<string>",
  "billing_address": {
    "name": "Acme",
    "line1": "5 rue de Paradis",
    "line2": "<string>",
    "city": "Paris",
    "zip": "75010",
    "state": "<string>",
    "country": "FR"
  },
  "invoicing_entity_id": "<string>",
  "billing_email": "billing@acme.com",
  "invoice_emails": [
    "accounting@acme.com"
  ],
  "available_payment_methods": [
    "card",
    "direct_debit"
  ],
  "payment_method_type": "card",
  "bank_account": {
    "format": "iban_bic_swift",
    "iban": "FR76XXXXXXXXXXXXXXXXXXXXXXX",
    "bic_swift": "XXXXXXXX"
  },
  "properties": "<string>",
  "language": "fr",
  "custom_properties": {}
}'
{
  "id": "cus_Typ0px2W0aiEtl",
  "name": "Acme",
  "type": "corporate",
  "status": "active",
  "currency": "EUR",
  "country": "FR",
  "vat_number": "FR123456789",
  "vat_number_valid": true,
  "vat_rate_custom": 123,
  "language": "fr",
  "external_id": "<string>",
  "properties": "<string>",
  "custom_properties": {},
  "billing_address": {
    "name": "Acme",
    "line1": "5 rue de Paradis",
    "line2": "<string>",
    "city": "Paris",
    "zip": "75010",
    "state": "<string>",
    "country": "FR"
  },
  "billing_email": "billing@acme.com",
  "invoice_emails": [
    "accounting@acme.com"
  ],
  "invoicing_entity_id": "ive_484dn4U48E",
  "available_payment_methods": [
    "card",
    "direct_debit"
  ],
  "current_payment_method_type": "card",
  "current_payment_method_id": "pm_UTclbc1US8GzCe",
  "transaction_provider_id": "<string>",
  "subscriptions": [
    {
      "id": "sub_0kIc7jrF7gV00V",
      "status": "active",
      "current_period_started_at": "2023-10-12T07:00:01.860Z",
      "current_period_ends_at": "2023-11-12T07:00:01.860Z",
      "plan_id": "plan_34hdd843hReh",
      "checkout_session_id": "che_949djdj39RJj"
    }
  ],
  "created_at": "2023-10-12T07:00:01.860Z",
  "updated_at": "2023-10-12T07:00:01.860Z",
  "deleted_at": "2023-11-07T05:31:56Z",
  "providers": {
    "stripe": "cus_Ol3QIaTstxxxxx"
  },
  "current_payment_method": {
    "id": "pm_1xMpj5bwRqN7LM",
    "type": "card",
    "last_4_digits": 2718,
    "expiration_date": "2026-11",
    "brand": "visa"
  },
  "bank_account": {
    "format": "iban_bic_swift",
    "iban": "FR76XXXXXXXXXXXXXXXXXXXXXXX",
    "bic_swift": "XXXXXXXX"
  }
}

Authorizations

Authorization
string
headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
name
string

Customer legal name.

type
enum<string>

Customer type.

  • corporate: The customer is a business entity.
  • person: The customer is a natural person.
  • automatically_created: The customer was automatically imported (e.g. from a data loader). This value cannot be used when creating/editing.
Available options:
corporate,
person
currency
string

Currency code. See ISO 4217.

country
string
deprecated

Deprecated field, please use billing_address.country.

vat_number
string

Customer tax number.

vat_rate_custom
number

Customer custom tax rate. If not defined, the rate will be automatically determined based on the customer's country, your country, and applicable legal requirements.

external_id
string

ID of the customer in your system. This helps matching your customer with the one on Hyperline.

billing_address
object

Company billing address

invoicing_entity_id
string
billing_email
string

Email to which all communications will be sent.

invoice_emails
string[]

Emails to which invoices will be sent (e.g. payer, finance team, accounting firm). If not defined, invoices will be sent to the billing_email; otherwise, they won't be sent to the billing_email.

available_payment_methods
enum<string>[]

List of payment methods you allow your customer to pay with. You customer will be able to select one of them in their portal page and those will be the default options when creating a checkout session.

Available options:
card,
direct_debit,
direct_debit_ach,
direct_debit_bacs,
transfer,
transfer_automated
payment_method_type
enum<string>

Default payment method type used to pay subscriptions and one-off invoices.

Available options:
card,
direct_debit,
direct_debit_ach,
direct_debit_bacs,
transfer,
transfer_automated,
external
bank_account
object

Custom bank account for the customer. If not defined and customer paying by bank transfer, the bank accounts configured in your account settings will be used.

properties

Key/value pairs to store any information you find useful.

language
enum<string>

Language use to translate invoices and emails

Available options:
fr,
en,
de,
it,
nl
custom_properties
object

A list of key value with the ID or the name of the custom property as the key and the custom property value as value.

Response

201 - application/json
id
string
required

Customer ID.

name
string
required

Customer legal name.

type
enum<string> | null
required

Customer type.

  • corporate: The customer is a business entity.
  • person: The customer is a natural person.
  • automatically_created: The customer was automatically imported (e.g. from a data loader). This value cannot be used when creating/editing.
Available options:
corporate,
person,
automatically_created
status
enum<string>
required

Customer status.

Available options:
active,
archived
currency
string
required

Currency code. See ISO 4217.

country
string | null
required

Two-letter country code in ISO format. See ISO 3166 Alpha 2.

vat_number
string | null
required

Customer tax number.

vat_number_valid
boolean
required

Indicates customer's tax number validity.

vat_rate_custom
number | null
required

Customer custom tax rate. If not defined, the rate will be automatically determined based on the customer's country, your country, and applicable legal requirements.

language
enum<string> | null
required

Language use to translate invoices and emails

Available options:
fr,
en,
de,
it,
nl
external_id
string | null
required

ID of the customer in your system. This helps matching your customer with the one on Hyperline.

properties
required

Key/value pairs to store any information you find useful.

custom_properties
object | null
required

A list of key value with the ID or the name of the custom property as the key and the custom property value as value.

billing_address
object
required

Company billing address

billing_email
string | null
required

Email to which all communications will be sent.

invoice_emails
string[]
required

Emails to which invoices will be sent (e.g. payer, finance team, accounting firm). If not defined, invoices will be sent to the billing_email; otherwise, they won't be sent to the billing_email.

invoicing_entity_id
string
required

ID of the invoicing entity this customer will be attached to.

available_payment_methods
enum<string>[]
required

List of payment methods you allow your customer to pay with. You customer will be able to select one of them in their portal page and those will be the default options when creating a checkout session.

Available options:
card,
direct_debit,
direct_debit_ach,
direct_debit_bacs,
transfer,
transfer_automated
current_payment_method_type
enum<string> | null
required

Default payment method type used to pay subscriptions and one-off invoices.

Available options:
card,
direct_debit,
direct_debit_ach,
direct_debit_bacs,
transfer,
transfer_automated,
external
current_payment_method_id
string | null
required

ID of the default payment method of the customer. Only applies to card and direct debit.

transaction_provider_id
string | null
required

Deprecated field, please use providers.

subscriptions
object[]
required
created_at
string
required

UTC date time string in the ISO 8601 format.

updated_at
string
required

UTC date time string in the ISO 8601 format.

deleted_at
string | null
required

UTC date time string in the ISO 8601 format.

providers
object
required

Provider/ID mapping of the customer in the related providers. Provider (key) can be gocardless, mollie, stripe, hubspot, salesforce.

current_payment_method
object | null
required

Default payment method of the customer. Only applies to card and direct debit.

bank_account
object | null
required

Custom bank account for the customer. If not defined and customer paying by bank transfer, the bank accounts configured in your account settings will be used.

Get customersGet customer