> ## Documentation Index > Fetch the complete documentation index at: https://docs.codaclean.io/llms.txt > Use this file to discover all available pages before exploring further. # Search customers > Paginated, filterable list of the customers visible to the user, sorted by name. Only customers the user can access are included: usually all the accounting firm's customers, or only some of them if the firm restricted the user in MyCodaclean. **Required scope:** `customers:read` ## OpenAPI ````yaml POST /customers openapi: 3.1.0 info: title: Codaclean API version: '1.0' description: > The Codaclean external API lets partner software (accounting tools, practice management software, sync agents) integrate with Codaclean on behalf of an accounting firm: manage its customers, request CODA and CODB mandates, and retrieve the CODA and CODB files Codaclean receives for them. servers: - url: https://api.codaclean.io/v1 description: Production - url: https://api.test.codaclean.io/v1 description: Staging security: - apiKeyAuth: [] bearerAuth: [] tags: - name: Authentication description: Obtain and refresh the ID token sent with every other call. - name: Utilities description: Connectivity check. - name: Customers description: The customers (client companies) managed by the accounting firm. - name: Bank accounts description: Bank accounts (IBANs) linked to a customer. - name: Customer payroll providers description: Payroll providers (social secretariats) linked to a customer. - name: Mandates description: CODA mandates (per bank account) and CODB mandates (per payroll provider). - name: Reference data description: Banks and payroll providers known to Codaclean. - name: CODA files description: Bank statement files in CODA format. - name: CODB files description: Payroll files in CODB format, delivered by payroll providers. paths: /customers: post: tags: - Customers summary: Search customers description: > Paginated, filterable list of the customers visible to the user, sorted by name. Only customers the user can access are included: usually all the accounting firm's customers, or only some of them if the firm restricted the user in MyCodaclean. **Required scope:** `customers:read` operationId: searchCustomers requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomerSearch' examples: all: summary: All customers value: {} page: summary: First page of one record value: limit: 1 offset: 0 byEnterpriseNumber: summary: By enterprise number value: enterpriseNumber: 0764.042.472 responses: '200': description: Matching customers. content: application/json: schema: $ref: '#/components/schemas/CustomerList' examples: all: summary: All customers value: records: - id: 675b4183d350b74dad2f46ec enterpriseNumber: 0764.042.472 name: Boulangerie Dupont SRL accountingRef: DUPONT address: street: Rue du Marché 12 street2: '' zipCode: '1000' municipality: Bruxelles country: Belgique contact: name: Marie Dupont function: CEO email: marie.dupont@example.com language: nl isConfidential: false bankAccounts: - iban: BE49001163522171 currency: EUR bic: GEBA BE BB bankName: BNP Paribas Fortis - iban: BE68001466139034 currency: EUR bic: GEBA BE BB bankName: BNP Paribas Fortis - iban: BE40751680738663 currency: EUR bic: AXAB BE 22 bankName: Crelan - iban: BE10732141110904 currency: EUR bic: CREG BE BB bankName: CBC Banque et Assurances - iban: BE79104034016533 currency: EUR bic: NICA BE BB bankName: Crelan - iban: BE21103265210903 currency: EUR bic: NICA BE BB bankName: Crelan payrollProviders: - code: sdworx nameFr: SD Worx nameNl: SD Worx - code: twinntax nameFr: TwinnTax nameNl: TwinnTax createdOn: '2024-12-12T20:03:15.277Z' updatedOn: '2026-06-30T10:30:16.368Z' - id: 675b41d6d350b74dad2f46ed enterpriseNumber: 0755.556.457 name: Garage Peeters BV accountingRef: PEETERS address: street: Kerkstraat 25 street2: '' zipCode: '1050' municipality: Bruxelles country: Belgique contact: name: Jan Peeters function: CEO email: jan.peeters@example.com language: en isConfidential: false bankAccounts: - iban: BE59732578835326 currency: EUR bic: CREG BE BB bankName: CBC Banque et Assurances - iban: BE87088425005794 currency: EUR bic: GKCC BE BB bankName: BELFIUS BANQUE - iban: BE42088136494654 currency: EUR bic: GKCC BE BB bankName: BELFIUS BANQUE payrollProviders: - code: partena_professional nameFr: Partena Professional nameNl: Partena Professional - code: twinntax nameFr: TwinnTax nameNl: TwinnTax - code: '***other***' nameFr: Autre secrétariat social (*) nameNl: Andere sociale secretariaat (*) createdOn: '2024-12-12T20:04:38.056Z' updatedOn: '2026-01-26T09:23:05.991Z' recordsTotal: 2 recordsFiltered: 2 byEnterpriseNumber: summary: By enterprise number value: records: - id: 675b4183d350b74dad2f46ec enterpriseNumber: 0764.042.472 name: Boulangerie Dupont SRL accountingRef: DUPONT address: street: Rue du Marché 12 street2: '' zipCode: '1000' municipality: Bruxelles country: Belgique contact: name: Marie Dupont function: CEO email: marie.dupont@example.com language: nl isConfidential: false bankAccounts: - iban: BE49001163522171 currency: EUR bic: GEBA BE BB bankName: BNP Paribas Fortis - iban: BE68001466139034 currency: EUR bic: GEBA BE BB bankName: BNP Paribas Fortis - iban: BE40751680738663 currency: EUR bic: AXAB BE 22 bankName: Crelan - iban: BE10732141110904 currency: EUR bic: CREG BE BB bankName: CBC Banque et Assurances - iban: BE79104034016533 currency: EUR bic: NICA BE BB bankName: Crelan - iban: BE21103265210903 currency: EUR bic: NICA BE BB bankName: Crelan payrollProviders: - code: sdworx nameFr: SD Worx nameNl: SD Worx - code: twinntax nameFr: TwinnTax nameNl: TwinnTax createdOn: '2024-12-12T20:03:15.277Z' updatedOn: '2026-06-30T10:30:16.368Z' recordsTotal: 2 recordsFiltered: 1 '400': description: >- Invalid request (`invalidPayload`, `unknownField`, `invalidIdentifier`…). content: application/json: schema: $ref: '#/components/schemas/Error' examples: unknownField: summary: Unknown filter value: message: 'Unknown field(s): name' code: unknownField fields: - name '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' components: schemas: CustomerSearch: type: object additionalProperties: false properties: q: type: string description: >- Case-insensitive search on name, enterprise number and accounting reference. enterpriseNumber: type: string description: Exact match, formatted `0123.456.789`. accountingRef: type: string description: Exact match. iban: type: string description: Exact match on an active bank account. Spaces are ignored. limit: type: integer default: 50 maximum: 200 offset: type: integer default: 0 CustomerList: type: object properties: records: type: array items: $ref: '#/components/schemas/Customer' recordsTotal: type: integer description: Number of customers visible to the user, before filters. recordsFiltered: type: integer description: Number of customers matching the filters. Error: type: object description: > Error body. `code` is a stable, machine-readable token; it is present on errors returned by the customers, mandates and reference-data endpoints. Some errors carry extra keys, such as `fields` or `candidates`. required: - message properties: message: type: string description: Human-readable description. Do not parse it. code: type: string description: | Machine-readable error code. **See also:** [Errors](/api/errors#error-codes) fields: type: array items: type: string description: >- Offending fields. Present with `unknownField` and `fieldNotUpdatable`. candidates: type: array description: Present with `connectorSelectionRequired`. items: $ref: '#/components/schemas/ConnectorCandidate' Customer: type: object description: >- Fields without a value are omitted from the response. Arrays are always present. properties: id: type: string enterpriseNumber: type: string description: Belgian enterprise number, formatted `0123.456.789`. name: type: string accountingRef: type: string address: $ref: '#/components/schemas/Address' contact: $ref: '#/components/schemas/Contact' isConfidential: type: boolean description: >- Confidential customers are only visible to users with the Administrator access level. bankAccounts: type: array description: Active bank accounts only. items: $ref: '#/components/schemas/BankAccount' payrollProviders: type: array description: Active payroll providers only. items: $ref: '#/components/schemas/CustomerPayrollProvider' createdOn: type: string format: date-time updatedOn: type: string format: date-time ConnectorCandidate: type: object properties: connectorId: type: integer name: type: string bicCode: type: string available: type: boolean Message: type: object description: Confirmation returned by actions that do not return a resource. required: - message properties: message: type: string Address: type: object additionalProperties: false properties: street: type: string street2: type: string zipCode: type: string municipality: type: string country: type: string Contact: type: object additionalProperties: false description: >- Contact person at the customer. Mandate signature requests are sent to this contact. properties: name: type: string description: Name of the person who signs the mandates. function: type: string email: type: string description: Email address the mandate signature requests are sent to. language: type: string description: >- Language of the contact: `fr`, `nl` or `en`. Used for the mandate documents and emails. BankAccount: type: object properties: iban: type: string currency: type: string description: >- Always `EUR` unless another value is stored. Output only; not accepted as input. bic: type: string description: >- Derived from the IBAN by Codaclean. Formatted with spaces, for example `GEBA BE BB`. bankName: type: string connectorId: type: integer description: >- Present when the bank account is served through a CODAlight connector. CustomerPayrollProvider: type: object properties: code: type: string description: >- Payroll provider code. `***other***` means another payroll provider, not handled by Codaclean. nameFr: type: string nameNl: type: string responses: Unauthorized: description: >- Missing, invalid or expired ID token, or user not allowed to use the API. content: application/json: schema: $ref: '#/components/schemas/Message' examples: noToken: summary: No ID token value: message: Unauthorized invalidToken: summary: Invalid or expired ID token value: message: Unauthorized Forbidden: description: >- Missing or invalid API key, missing scope (`forbiddenScope`), or access denied. content: application/json: schema: $ref: '#/components/schemas/Error' examples: noApiKey: summary: No API key value: message: Forbidden invalidApiKey: summary: Invalid API key value: message: Forbidden TooManyRequests: description: Rate limit or quota exceeded for this API key. content: application/json: schema: $ref: '#/components/schemas/Message' examples: tooManyRequests: summary: Rate limit exceeded value: message: Too Many Requests InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Error' examples: internalError: summary: Unexpected server error value: message: Internal server error securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: >- Identifies the partner software. Issued by Codaclean. Required on every call, including `POST /token`. bearerAuth: type: http scheme: bearer bearerFormat: JWT (Cognito ID token) description: >- Identifies the user and their accounting firm. Send the `idToken` returned by `POST /token` as `Authorization: Bearer `. Valid for 1 hour. ````