> ## 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. # CODA-mandaat aanvragen > Requests a mandate for the bank account. The bank determines the product: a CODA mandate when the bank delivers CODA to Codaclean, otherwise a CODAlight consent through a connector. Processing is **asynchronous**. The response confirms that the request was received, and contains no mandate identifier. Follow the mandate with `POST /mandates`, for example filtered on `customerId` or `iban`, with `updatedSince`. Do not repeat the request before the mandate appears there: until then, a duplicate request is not detected. When several connectors match the bank, the call returns `422 connectorSelectionRequired` with `candidates`. Call again with the chosen `connectorId`. **Required scope:** `mandates:write` ## OpenAPI ````yaml POST /customers/{customerId}/bank-accounts/{iban}/mandates/new 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/{customerId}/bank-accounts/{iban}/mandates/new: parameters: - $ref: '#/components/parameters/CustomerId' - $ref: '#/components/parameters/Iban' post: tags: - Mandates summary: Request a CODA mandate description: > Requests a mandate for the bank account. The bank determines the product: a CODA mandate when the bank delivers CODA to Codaclean, otherwise a CODAlight consent through a connector. Processing is **asynchronous**. The response confirms that the request was received, and contains no mandate identifier. Follow the mandate with `POST /mandates`, for example filtered on `customerId` or `iban`, with `updatedSince`. Do not repeat the request before the mandate appears there: until then, a duplicate request is not detected. When several connectors match the bank, the call returns `422 connectorSelectionRequired` with `candidates`. Call again with the chosen `connectorId`. **Required scope:** `mandates:write` operationId: requestBankAccountMandate requestBody: content: application/json: schema: $ref: '#/components/schemas/BankAccountMandateRequest' responses: '200': description: Mandate request received. content: application/json: schema: $ref: '#/components/schemas/Message' examples: requested: summary: Request received value: message: Mandate creation request sent '400': description: '`invalidPayload`, `unknownField` or `invalidIdentifier`.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: unknownField: summary: Field not accepted value: message: 'Unknown field(s): retrieveCodaFrom' code: unknownField fields: - retrieveCodaFrom invalidIdentifier: summary: Malformed identifier value: message: Invalid customer identifier code: invalidIdentifier '401': $ref: '#/components/responses/Unauthorized' '403': description: >- `forbiddenScope`, or `accessDenied` — confidential customer and the user is not an Administrator. 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 '404': description: '`customerNotFound`, `ibanNotFound` or `bankNotSupported`.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: ibanNotFound: summary: IBAN not linked to the customer value: message: >- IBAN BE25539580647282 is not linked to customer 675b4183d350b74dad2f46ec code: ibanNotFound customerNotFound: summary: Unknown customer value: message: Customer 000000000000000000000000 not found code: customerNotFound '409': description: >- `mandateAlreadyRequested` — a mandate request already exists for this customer and IBAN. content: application/json: schema: $ref: '#/components/schemas/Error' examples: mandateAlreadyRequested: summary: Request already exists value: message: >- Customer 6ab7bba70d0379c741b7f74c already has a mandate request for IBAN BE08068722124813 code: mandateAlreadyRequested '422': description: >- `connectorSelectionRequired` (see `candidates`) or `connectorUnavailable`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: connectorSelectionRequired: summary: 'Several connectors: choose one' value: message: Several connectors match this BIC, specify connectorId code: connectorSelectionRequired candidates: - connectorId: 12 name: Triodos (French) bicCode: TRIO BE BB available: true - connectorId: 124 name: Triodos (Nederlands) bicCode: TRIO BE BB available: true '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' components: parameters: CustomerId: name: customerId in: path required: true description: >- Customer identifier (24-character hexadecimal string), as returned in `id`. schema: type: string Iban: name: iban in: path required: true description: >- IBAN of the bank account. Spaces are removed and letters are uppercased before use. schema: type: string schemas: BankAccountMandateRequest: type: object additionalProperties: false properties: connectorId: type: integer description: > Only needed when the call returned `422 connectorSelectionRequired`: pick one of the returned `candidates`. Message: type: object description: Confirmation returned by actions that do not return a resource. required: - message properties: message: type: string 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' ConnectorCandidate: type: object properties: connectorId: type: integer name: type: string bicCode: type: string available: type: boolean 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 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. ````