---
title: "Create a client"
method: POST
path: "/v2/clients"
tags: ["Clients"]
---

# Create a client

`POST /v2/clients`

OAuth scope: `client.write`

------

Create a client that constitutes the addressee of client invoices for a particular organization. See further details below.

------

Price plans: this endpoint is available for all Qonto price plans

-----

The response contains an array the attributes of the client entered in the request, along with additional fields that are computed by Qonto, including the associated client id.

----

There is no uniqueness rule. It is strongly advised to search using the GET endpoints for a given client before creating a new client.

<!-- theme: warning -->
> When creating a client to be used for **invoicing purposes**, bear in mind the following:
> - 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.

## Headers

- `X-Qonto-Staging-Token` string

## Request body

- union
  - ClientIndividualCreatePayload
    - `name` string — represents the name of the client that needs to pay the client invoice. It is required if type is `company`
    - `first_name` string, required — represents the first name of the client that needs to pay the invoice. It is required if type is `individual` or `freelancer`
    - `last_name` string, required — represents the last name of the client that needs to pay the invoice. It is required if type is individual or freelancer.
    - `type` 'individual' | 'company' | 'freelancer', required — describes the 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.
    - `email` string, email — represents the e-mail address of the client that needs to pay the invoice, which is displayed in the invoice.
    - `vat_number` string — represents the Value Added Tax number of the client (a legal entity) that needs to pay the invoice.
    - `tax_identification_number` string — represents the Tax Identification Number of the client (a physical person) that needs to pay the invoice. It corresponds to the SIREN/SIRET for 🇫🇷 companies.
    - `address` string — represents the address of the client that needs to pay the invoice.
    - `city` string — represents the city of the client that needs to pay the invoice.
    - `zip_code` string — represents the 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.
    - `province_code` string — represents the 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
    - `country_code` string — represents the country code of the client that needs to pay the invoice as a root-level field (ISO 3166 format).
    - `billing_address` ClientBillingAddress — 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.
      - `street_address` string — Street address section of the billing address of the client (eg street, number, floor, door, etc).
      - `city` string — City on the billing address of the client
      - `zip_code` string — Zip code on the billing address of the client
      - `province_code` string — Province code of the client's billing address. It is required only for Italian organizations.
      - `country_code` string — Country code on the billing address of the client (ISO 3166 format)
    - `delivery_address` ClientDeliveryAddress
      - `street_address` string — Street address section of the delivery address of the client. (eg street, number, floor, door, etc)
      - `city` string — City on the delivery address of the client
      - `zip_code` string — Zip code on the delivery address of the client
      - `province_code` string — Province code of the client's delivery address. It is required only for Italian organizations
      - `country_code` string — Country code on the delivery address of the client (ISO 3166 format)
    - `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 — represents the client’s currency, supported format is ISO 4217. Required when creating an invoice with this client.
    - `locale` string — represents the 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.
  - ClientCompanyCreatePayload
    - `name` string, required — represents the name of the client that needs to pay the client invoice. It is required if type is `company`
    - `first_name` string — represents the first name of the client that needs to pay the invoice. It is required if type is `individual` or `freelancer`
    - `last_name` string — represents the last name of the client that needs to pay the invoice. It is required if type is individual or freelancer.
    - `type` 'company', required — describes the 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.
    - `email` string, email — represents the e-mail address of the client that needs to pay the invoice, which is displayed in the invoice.
    - `vat_number` string — represents the Value Added Tax number of the client (a legal entity) that needs to pay the invoice.
    - `tax_identification_number` string — represents the Tax Identification Number of the client (a physical person) that needs to pay the invoice. It corresponds to the SIREN/SIRET for 🇫🇷 companies.
    - `address` string — represents the address of the client that needs to pay the invoice.
    - `city` string — represents the city of the client that needs to pay the invoice.
    - `zip_code` string — represents the 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
    - `province_code` string — represents the 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
    - `country_code` string — represents the country code of the client as a root-level field (ISO 3166 format)
    - `billing_address` ClientBillingAddress — 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.
      - `street_address` string — Street address section of the billing address of the client (eg street, number, floor, door, etc).
      - `city` string — City on the billing address of the client
      - `zip_code` string — Zip code on the billing address of the client
      - `province_code` string — Province code of the client's billing address. It is required only for Italian organizations.
      - `country_code` string — Country code on the billing address of the client (ISO 3166 format)
    - `delivery_address` ClientDeliveryAddress
      - `street_address` string — Street address section of the delivery address of the client. (eg street, number, floor, door, etc)
      - `city` string — City on the delivery address of the client
      - `zip_code` string — Zip code on the delivery address of the client
      - `province_code` string — Province code of the client's delivery address. It is required only for Italian organizations
      - `country_code` string — Country code on the delivery address of the client (ISO 3166 format)
    - `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 — represents the client’s currency, supported format is ISO 4217. Required when creating an invoice with this client.
    - `locale` string — represents the 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.

## Response `200`

The created client

- object
  - `client` union, required
    - ClientCompany
      - `id` string, uuid
      - `name` string — represents the name of the client that needs to pay the client invoice.
      - `type` 'company' — 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.
      - `email` string, email — represents the e-mail address of the client that needs to pay the invoice, which is displayed in the invoice.
      - `vat_number` string — represents the Value Added Tax number of the client (a legal entity) that needs to pay the invoice.
      - `tax_identification_number` string — represents the Tax Identification Number of the client (a physical person) that needs to pay the invoice. It corresponds to the SIREN/SIRET for 🇫🇷 companies.
      - `address` string — represents the address of the client that needs to pay the invoice.
      - `city` string — represents the city of the client that needs to pay the invoice.
      - `zip_code` string — represents the zip code of the client that needs to pay the invoice.
      - `province_code` string — Only for italian organizations. Represents the province code of the client.
      - `country_code` string — represents the country code of the client that needs to pay the invoice.
      - `billing_address` object — represents the 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`).
        - `street_address` string — represent the street address section of the billing address of the client. (eg street, number, floor, door, etc)
        - `city` string — represents the city on the billing address of the client that needs to pay the invoice
        - `zip_code` string — represents the zip code on the billing address of the client that needs to pay the invoice
        - `province_code` string — represents the province code of the client's billing address
        - `country_code` string — represents the country code on the billing address of the client that needs to pay the invoice
      - `delivery_address` object — represents the 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`).
        - `street_address` string — represent the street address section of the delivery address of the client. (eg street, number, floor, door, etc)
        - `city` string — represents the city on the delivery address of the client that needs to pay the invoice
        - `zip_code` string — represents the zip code on the delivery address of the client that needs to pay the invoice
        - `province_code` string — represents the province code of the client's delivery address that needs to pay the invoice
        - `country_code` string — represents the country code on the delivery address of the client that needs to pay the invoice
      - `recipient_code` string — Only for italian clients. Represents the client’s recipient code for receiving an the e-invoice in his SdI portal.
      - `created_at` string — represents the date the client was created. Note that this is a machine date.
      - `locale` string — represents the language of the documents created on Qonto (invoices, quotes, credit notes) for this particular client.
    - ClientIndividual
      - `id` string, uuid
      - `first_name` string — represents the first name of the client that needs to pay the invoice.
      - `last_name` string — represents the last name of the client that needs to pay the invoice
      - `type` 'individual' | 'freelancer' — 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.
      - `email` string, email — represents the e-mail address of the client that needs to pay the invoice, which is displayed in the invoice.
      - `vat_number` string — represents the Value Added Tax number of the client (a legal entity) that needs to pay the invoice.
      - `tax_identification_number` string — represents the Tax Identification Number of the client (a physical person) that needs to pay the invoice. It corresponds to the SIREN/SIRET for 🇫🇷 companies.
      - `address` string — represents the address of the client that needs to pay the invoice.
      - `city` string — represents the city of the client that needs to pay the invoice.
      - `zip_code` string — represents the zip code of the client that needs to pay the invoice.
      - `province_code` string — Only for italian organizations. Represents the province code of the client.
      - `country_code` string — represents the country code of the client that needs to pay the invoice.
      - `billing_address` object — represents the 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`).
        - `street_address` string — represent the street address section of the billing address of the client. (eg street, number, floor, door, etc)
        - `city` string — represents the city on the billing address of the client that needs to pay the invoice
        - `zip_code` string — represents the zip code on the billing address of the client that needs to pay the invoice
        - `province_code` string — represents the province code of the client's billing address
        - `country_code` string — represents the country code on the billing address of the client that needs to pay the invoice
      - `delivery_address` object — represents the 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`).
        - `street_address` string — represent the street address section of the delivery address of the client. (eg street, number, floor, door, etc)
        - `city` string — represents the city on the delivery address of the client that needs to pay the invoice
        - `zip_code` string — represents the zip code on the delivery address of the client that needs to pay the invoice
        - `province_code` string — represents the province code of the client's delivery address that needs to pay the invoice
        - `country_code` string — represents the country code on the delivery address of the client that needs to pay the invoice
      - `recipient_code` string — Only for italian clients. Represents the client’s recipient code for receiving an the e-invoice in his SdI portal.
      - `created_at` string — represents the date the client was created. Note that this is a machine date.
      - `locale` string — represents the language of the documents created on Qonto (invoices, quotes, credit notes) for this particular client.

## Other responses

- `400` — Bad request error
- `401` — Unauthorized error
- `403` — Forbidden error
- `422` — Unprocessable content Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/hiit-consulting-fr/apis/qonto.md) · [All operations](https://skmtc.net/hiit-consulting-fr/apis/qonto/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hiit-consulting-fr/qonto/revisions/25208d6f9deb/schema)