Create a client

curl --request POST \
  --url https://thirdparty.qonto.com/v2/clients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "kind": "individual",
  "type": "individual",
  "email": "john.doe@qonto.eu",
  "extra_emails": [
    "additional@email.com",
    "backup@email.com"
  ],
  "phone": {
    "country_code": "+33",
    "number": "123456789"
  },
  "e_invoicing_address": "987654321",
  "vat_number": "<string>",
  "tax_identification_number": "<string>",
  "address": "<string>",
  "city": "<string>",
  "zip_code": "<string>",
  "province_code": "<string>",
  "country_code": "FR",
  "billing_address": {
    "street_address": "123 Main Street",
    "city": "Paris",
    "zip_code": "75009",
    "province_code": "<string>",
    "country_code": "FR"
  },
  "delivery_address": {
    "street_address": "123 Main Street",
    "city": "Paris",
    "zip_code": "75009",
    "province_code": "<string>",
    "country_code": "FR"
  },
  "recipient_code": "<string>",
  "currency": "EUR",
  "locale": "FR"
}'

{
  "client": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "+33123456789",
    "phone": {
      "country_code": "+33",
      "number": "123456789"
    },
    "kind": "company",
    "type": "company",
    "email": "john.doe@qonto.eu",
    "extra_emails": [
      "additional@email.com",
      "backup@email.com"
    ],
    "currency": "EUR",
    "e_invoicing_address": "987654321",
    "vat_number": "<string>",
    "tax_identification_number": "<string>",
    "address": "<string>",
    "city": "<string>",
    "zip_code": "<string>",
    "province_code": "<string>",
    "country_code": "<string>",
    "billing_address": {
      "street_address": "123 Main Street",
      "city": "Paris",
      "zip_code": "75009",
      "province_code": "<string>",
      "country_code": "fr"
    },
    "delivery_address": {
      "street_address": "123 Main Street",
      "city": "Paris",
      "zip_code": "75009",
      "province_code": "<string>",
      "country_code": "fr"
    },
    "recipient_code": "<string>",
    "created_at": "<string>",
    "locale": "fr"
  }
}

POST

clients

Create a client

curl --request POST \
  --url https://thirdparty.qonto.com/v2/clients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "kind": "individual",
  "type": "individual",
  "email": "john.doe@qonto.eu",
  "extra_emails": [
    "additional@email.com",
    "backup@email.com"
  ],
  "phone": {
    "country_code": "+33",
    "number": "123456789"
  },
  "e_invoicing_address": "987654321",
  "vat_number": "<string>",
  "tax_identification_number": "<string>",
  "address": "<string>",
  "city": "<string>",
  "zip_code": "<string>",
  "province_code": "<string>",
  "country_code": "FR",
  "billing_address": {
    "street_address": "123 Main Street",
    "city": "Paris",
    "zip_code": "75009",
    "province_code": "<string>",
    "country_code": "FR"
  },
  "delivery_address": {
    "street_address": "123 Main Street",
    "city": "Paris",
    "zip_code": "75009",
    "province_code": "<string>",
    "country_code": "FR"
  },
  "recipient_code": "<string>",
  "currency": "EUR",
  "locale": "FR"
}'

{
  "client": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "+33123456789",
    "phone": {
      "country_code": "+33",
      "number": "123456789"
    },
    "kind": "company",
    "type": "company",
    "email": "john.doe@qonto.eu",
    "extra_emails": [
      "additional@email.com",
      "backup@email.com"
    ],
    "currency": "EUR",
    "e_invoicing_address": "987654321",
    "vat_number": "<string>",
    "tax_identification_number": "<string>",
    "address": "<string>",
    "city": "<string>",
    "zip_code": "<string>",
    "province_code": "<string>",
    "country_code": "<string>",
    "billing_address": {
      "street_address": "123 Main Street",
      "city": "Paris",
      "zip_code": "75009",
      "province_code": "<string>",
      "country_code": "fr"
    },
    "delivery_address": {
      "street_address": "123 Main Street",
      "city": "Paris",
      "zip_code": "75009",
      "province_code": "<string>",
      "country_code": "fr"
    },
    "recipient_code": "<string>",
    "created_at": "<string>",
    "locale": "fr"
  }
}

Authorizations

Authorization

string

header

required

Bearer authorization header: Bearer <token>, where <token> is the access token received from the authorization server at the end of the OAuth 2.0 flow.

Headers

X-Qonto-Staging-Token

string

Required only for Sandbox API requests; to get one, please sign up to the Developer Portal.

Body

application/json

When creating a client to be used for invoicing purposes, do note:

A client can be created by only specifying a type and a name (depending on the chosen type);
However, to be able to use that client for invoicing, the following additional fields must also be provided:
- currency
- locale
- address, either as root-level fields (address, city, zip_code, province_code and country_code) or inside the billing_address field object.

Option 1
Option 2

first_name

string

required

First name of the client that needs to pay the invoice. It is required if type is individual or freelancer

Maximum length: 60

last_name

string

required

Last name of the client that needs to pay the invoice. It is required if type is individual or freelancer.

Maximum length: 60

kind

enum<string>

required

Client kind: individual represents a physical person (a consumer) whereas company represents a legal entity. For Italian organizations only, freelancer (a legal entity with the name of a person) is also accepted.

Available options:

individual,

company,

freelancer

name

string

Name of the client that needs to pay the client invoice. It is required if type is company

Maximum length: 250

type

enum<string>

deprecated

This field is identical to kind. You can choose to send either type or kind. If you end up sending both, kind will take precedence over type.

Available options:

individual,

company,

freelancer

string<email>

E-mail address of the client that needs to pay the invoice, which is displayed in the invoice.

Example:

"john.doe@qonto.eu"

extra_emails

string<email>[] | null

Additional email addresses for the client. Store additional emails that won't appear in the document but will be used as recipients when sending the document via email.

Maximum length: 100

Example:

["additional@email.com", "backup@email.com"]

phone

object

Client's phone country code and number.

Show child attributes

e_invoicing_address

string

Specifically for French organizations. A unique address in one of the formats:

siren e.g. 987654321
siren_siret e.g. 987654321_98765432100012
siren_siret_routingCode e.g. 987654321_98765432100012_00001
siren_suffix e.g. 987654321_00002

Note the address should also exist in the Annuaire to be accepted.

Example:

"987654321"

vat_number

string

Value Added Tax number of the client (a legal entity) that needs to pay the invoice.

Maximum length: 20

tax_identification_number

string

Tax Identification Number of the client (a physical person) that needs to pay the invoice. It corresponds to the SIREN/SIRET for French companies.

Maximum length: 30

address

string

deprecated

Address of the client that needs to pay the invoice.

DEPRECATED: This field is deprecated. Please use billing_address.street_address instead.

Maximum length: 250

city

string

deprecated

City of the client that needs to pay the invoice. DEPRECATED: This field is deprecated. Please use billing_address.city instead.

Maximum length: 50

zip_code

string

deprecated

Zip code of the client that needs to pay the invoice. For clients with Italy as a country, the value must be 5 characters. For other countries, the value is capped to 20 characters.

DEPRECATED: This field is deprecated. Please use billing_address.zip_code instead.

Maximum length: 20

province_code

string

deprecated

Province code of the client that needs to pay the invoice. It is required only for Italian organizations.

List of province codes: AG, AL, AN, AO, AP, AQ, AR, AT, AV, BA, BG, BI, BL, BN, BO, BR, BS, BT, BZ, CA, CB, CE, CH, CL, CN, CO, CR, CS, CT, CZ, EN, FC, FE, FG, FI, FM, FR, GE, GO, GR, IM, IS, KR, LC, LE, LI, LO, LT, LU, MB, MC, ME, MI, MN, MO, MS, MT, NA, NO, NU, OR, PA, PC, PD, PE, PG, PI, PN, PO, PR, PT, PU, PV, PZ, RA, RC, RE, RG, RI, RM, RN, RO, SA, SI, SO, SP, SR, SS, SU, SV, TA, TE, TN, TO, TP, TR, TS, TV, UD, VA, VB, VC, VE, VI, VR, VT, VV

DEPRECATED: This field is deprecated. Please use billing_address.province_code instead.

Required string length: 2

country_code

string

deprecated

Country code of the client that needs to pay the invoice as a root-level field (ISO 3166 format).

DEPRECATED: This field is deprecated. Please use billing_address.country_code instead.

Required string length: 2

Example:

"FR"

billing_address

object

Billing address of the client, which will be reflected on the invoice. Required to fill in either this object (with fields street_address, city, zip_code, province_code and country_code) or the root level fields (address, city, zip_code, province_code and country_code) when creating an invoice with this client. Send either a billing_address object filled-in or individual root-level address fields (address, city, zip_code, province_code, country_code). When both are sent, billing_address takes precedence and overwrites root-level fields.

Show child attributes

delivery_address

object

Delivery address of the client whose

Show child attributes

recipient_code

string

Only for Italian clients. Represents the client’s recipient code, so that the client can receive the e-invoice in his SDI portal.

currency

string

Client’s currency, supported format is ISO 4217. Required when creating an invoice with this client.

Example:

"EUR"

locale

string

Language of the documents created on Qonto (invoices, quotes, credit notes) for this particular client. It is possible to choose between five languages: French, English, Italian, German, and Spanish. Required when creating an invoice with this client. Note, although we accept locales of format fr-FR we ignore the region part, treating this as fr

Example:

"FR"

Response

Returns the client created.

client

object

required

Option 1
Option 2

Show child attributes

List clients Retrieve a client

⌘I

Business API

Onboarding API

Create a client

Authorizations

Headers

Body

Response