--- title: "Get a list of clients" method: GET path: "/v2/clients" tags: ["Clients"] --- # Get a list of clients `GET /v2/clients` ## Request - Base URL: `https://thirdparty.qonto.com` - URL: `https://thirdparty.qonto.com/v2/clients` - Auth: one of: - OAuth 2 - Authorization code: `https://oauth.qonto.com/oauth2/auth` - Token URL: `https://oauth.qonto.com/oauth2/token` scopes: `client.read` - API key in header `Authorization` OAuth scope: `client.read` --- Get information about client(s) that constitute(s) the addressee of client invoices (or other products, such as SEPA Direct Debit) for a particular organization based on a search on attributes. See further details below. --- Price plans: this endpoint is available for all Qonto price plans. --- The response contains attributes of the client entered in the request, along with additional fields that are computed by Qonto, including the associated client id. --- ## Filtering Clients can be filtered based on their `tax_identification_number`, `vat_number`, or `email`. The response will return exact and case-insensitive match(es). Clients can also be filtered based on their `name`. The response will return exact and partial matches, case-insensitive and accent-insensitive match(es). When type is individual or freelancer, name consists of the concatenation of `first_name` & ” ” & `last_name`. The value must at least contain 2 characters minimum. ## Sorting - Clients can be sorted by `created_at`, `name` - Two values are available: `asc` (Ascending) / `desc` (Descending) - By default, the order used to sort is `name`, `asc` ## Pagination - The default number of items per page is 100, max items per page is 100. Pagination data is returned in the response : [See Schema here](https://api-doc.qonto.com/docs/business-api/c2NoOjI3NTA2MjA3-pagination). ## Query parameters - `filter` object - `page` integer - `per_page` integer - `sort_by` 'created_at:asc' | 'created_at:desc' | 'name:asc' | 'name:desc' ## Headers - `X-Qonto-Staging-Token` string ## Response `200` A list of clients, paginated - object - `clients` Client[] - union - 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. - `meta` Pagination - `current_page` integer - `next_page` integer, nullable - `prev_page` integer, nullable - `total_pages` integer - `total_count` integer - `per_page` integer ## Other responses - `400`: Bad request error - `401`: Unauthorized error - `403`: Forbidden error - `404`: Not found - `422`: Unprocessable content Error - `500`: Internal Server Error ## Changes - **2025-01-24** (v2) `25208d6f9deb`: 2 breaking - the `meta/next_page` response's property type changed from no type to `integer` for status `200` - the `meta/prev_page` response's property type changed from no type to `integer` for status `200` [Operation history](https://skmtc.dev/hiit-consulting-fr/apis/qonto/changes/v2/clients/get.md) --- [API](https://skmtc.dev/hiit-consulting-fr/apis/qonto.md) - [All operations](https://skmtc.dev/hiit-consulting-fr/apis/qonto/llms.txt) - [OpenAPI document](https://skmtc.dev/hiit-consulting-fr/apis/qonto/revisions/25208d6f9deb?raw)