Create a client

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 string 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 string 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 string 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:

"[email protected]"

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 array length: 100

Maximum string length: 250

Example:

["[email protected]", "[email protected]"]

phone

object

Client's phone country code and number.

Show child attributes

phone.country_code

string

Country code of the client's phone number.

Example:

"+33"

phone.number

string

Phone number of the client.

Example:

"123456789"

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 string length: 20

tax_identification_number

string

Tax Identification Number (TIN) of the client. Format varies by country:

France: SIREN (9 digits) or SIRET (14 digits)
Italy: Codice Fiscale (11 digits for companies, 16 alphanumeric for individuals)
Spain: NIF/CIF (9 characters)
Germany: Steuernummer

Note: A client can be created without this field, but invoice creation may fail if the field is missing or invalid based on these rules. If you receive a validation error related to tax_identification_number when creating an invoice, update the client first and then retry creating the invoice.

Maximum string length: 20

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 string 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 string 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 string 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

billing_address.street_address

string

Street address section of the billing address of the client (eg street, number, floor, door, etc).

Maximum string length: 250

Example:

"123 Main Street"

billing_address.city

string

City on the billing address of the client

Maximum string length: 50

Example:

"Paris"

billing_address.zip_code

string

Zip code on the billing address of the client

Maximum string length: 20

Example:

"75009"

billing_address.province_code

string

Province code of the client's billing address. It is required only for Italian organizations.

Maximum string length: 2

billing_address.country_code

string

Country code on the billing address of the client (ISO 3166 format)

Maximum string length: 2

Example:

"FR"

delivery_address

object

Delivery address of the client whose

Show child attributes

delivery_address.street_address

string

Street address section of the delivery address of the client. (eg street, number, floor, door, etc)

Maximum string length: 250

Example:

"123 Main Street"

delivery_address.city

string

City on the delivery address of the client

Maximum string length: 50

Example:

"Paris"

delivery_address.zip_code

string

Zip code on the delivery address of the client

Maximum string length: 20

Example:

"75009"

delivery_address.province_code

string

Province code of the client's delivery address. It is required only for Italian organizations

Maximum string length: 2

delivery_address.country_code

string

Country code on the delivery address of the client (ISO 3166 format)

Maximum string length: 2

Example:

"FR"

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 in ISO 4217 format (alpha-3). Required when creating a client invoice and will be used as the invoice currency.

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

client.id

string<uuid>

client.name

string

Name of the client that needs to pay the client invoice.

Example:

"John Doe"

client.first_name

string

First name of the client that needs to pay the invoice.

Example:

"John"

client.last_name

string

Last name of the client that needs to pay the invoice.

Example:

"Doe"

client.phone_number

string

deprecated

Phone number of the client that needs to pay the invoice. Deprecated, use phone instead.

Example:

"+33123456789"

client.phone

object

Phone country code and number of the client that needs to pay the invoice.

Show child attributes

client.phone.country_code

string

Country code of the client's phone number.

Example:

"+33"

client.phone.number

string

Phone number of the client.

Example:

"123456789"

client.kind

enum<string>

Describes the client type. individual represents a physical person (a consumer) whereas company or freelancer represent a legal entity. Usually a freelancer is a legal entity with the name of a person.

Available options:

company,

individual,

freelancer

client.type

enum<string>

deprecated

Available options:

company,

individual,

freelancer

client.email

string<email>

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

Example:

"[email protected]"

client.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 array length: 100

Maximum string length: 250

Example:

["[email protected]", "[email protected]"]

client.currency

string

Client’s currency in ISO 4217 format (alpha-3). Required when creating a client invoice and will be used as the invoice currency.

Example:

"EUR"

client.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"

client.vat_number

string

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

client.tax_identification_number

string

Tax Identification Number (TIN) of the client. Format varies by country:

France: SIREN (9 digits) or SIRET (14 digits)
Italy: Codice Fiscale (11 digits for companies, 16 alphanumeric for individuals)
Spain: NIF/CIF (9 characters)
Germany: Steuernummer

client.address

string

Address of the client that needs to pay the invoice.

client.city

string

City of the client that needs to pay the invoice.

client.zip_code

string

Zip code of the client that needs to pay the invoice.

client.province_code

string

Only for italian organizations. Represents the province code of the client.

client.country_code

string

Country code of the client that needs to pay the invoice.

client.billing_address

object

Billing address of the client that needs to pay the invoice. Stores the same data as the root-level fields address fields (address, city, zip_code, province_code, country_code).

Show child attributes

client.billing_address.street_address

string

represent the street address section of the billing address of the client. (eg street, number, floor, door, etc)

Maximum string length: 250

Example:

"123 Main Street"

client.billing_address.city

string

City on the billing address of the client that needs to pay the invoice

Maximum string length: 50

Example:

"Paris"

client.billing_address.zip_code

string

Zip code on the billing address of the client that needs to pay the invoice

Maximum string length: 20

Example:

"75009"

client.billing_address.province_code

string

Province code of the client's billing address

Maximum string length: 2

client.billing_address.country_code

string

Country code on the billing address of the client that needs to pay the invoice

Maximum string length: 2

Example:

"fr"

client.delivery_address

object

Delivery address of the client that needs to pay the invoice. Stores the same data as the root-level fields address fields (address, city, zip_code, province_code, country_code).

Show child attributes

client.delivery_address.street_address

string

represent the street address section of the delivery address of the client. (eg street, number, floor, door, etc)

Maximum string length: 250

Example:

"123 Main Street"

client.delivery_address.city

string

City on the delivery address of the client that needs to pay the invoice

Maximum string length: 50

Example:

"Paris"

client.delivery_address.zip_code

string

Zip code on the delivery address of the client that needs to pay the invoice

Maximum string length: 20

Example:

"75009"

client.delivery_address.province_code

string

Province code of the client's delivery address that needs to pay the invoice

Maximum string length: 2

client.delivery_address.country_code

string

Country code on the delivery address of the client that needs to pay the invoice

Maximum string length: 2

Example:

"fr"

client.recipient_code

string

Only for italian clients. Represents the client’s recipient code for receiving an the e-invoice in his SdI portal.

client.created_at

string

Date the client was created. Note that this is a machine date.

client.locale

string

Language of the documents created on Qonto (invoices, quotes, credit notes) for this particular client. Note, although we accept locales of format fr-FR we ignore the region part, treating this as fr.

Example:

"fr"

Business API

Onboarding API

Create a client

Authorizations

Headers

Body

Response