POST
/
v2
/
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>",
  "type": "individual",
  "email": "john.doe@qonto.eu",
  "extra_emails": [
    "additional@email.com",
    "backup@email.com"
  ],
  "phone": {
    "country_code": "+33",
    "number": "123456789"
  },
  "e_invoicing_address": "1234567890",
  "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"
    },
    "type": "company",
    "email": "john.doe@qonto.eu",
    "extra_emails": [
      "additional@email.com",
      "backup@email.com"
    ],
    "currency": "EUR",
    "e_invoicing_address": "1234567890",
    "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.
​
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
​
type
enum<string>
required

Client type: 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
​
email
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.

​
e_invoicing_address
string

Unique identifier used to send the invoice to the client.

Example:

"1234567890"

​
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.

​
delivery_address
object

Delivery address of the client whose

​
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.

Example:

"FR"

Response

Returns the client created.

​
client
object
required