openapi: 3.0.3 info: title: Qonto version: v2 servers: - url: 'https://thirdparty.qonto.com' description: Production URL - url: 'https://thirdparty-sandbox.staging.qonto.co' description: Sandbox URL tags: - name: 'V2::Beneficiary' - name: 'V2::ExternalTransfer' - name: 'V2::Attachment' - name: 'V2::Label' - name: 'V2::Membership' - name: 'V2::Organization' - name: 'V2::Team' - name: 'V2::Transaction' - name: 'V2::InternalTransfer' - name: 'V2::Request' - name: 'V2::SupplierInvoice' - name: 'V2::ClientInvoice' - name: 'V2::CreditNote' - name: 'V2::Card' paths: '/v2/external_transfers/{id}': get: summary: Show an external transfer operationId: get_external_transfer parameters: - name: id in: path required: true schema: type: string example: 7b7a5ed6-3903-4782-889d-b4f64bd7bef9 - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: returns an external transfer content: application/json: schema: type: object required: - external_transfer properties: external_transfer: $ref: '#/components/schemas/ExternalTransfer' '404': description: returns a not found error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string source: type: object properties: parameter: type: string example: errors: - code: not_found detail: External transfer not found source: parameter: id tags: - External Transfers description: | OAuth scope: `organization.read` --- Get a single external transfer. --- ## Attributes details ##### Initiator ID ID of the membership that initiated the external transfer.
When the external transfer is initiated through the API, the initiator is the authenticated membership. ##### Debit - `debit_iban`: Can be any of the organization's bank accounts. IBAN formatted ISO 13616. - `debit_amount`: The amount that will be debited from your Qonto account. - `debit_amount_cents`: The amount that will be debited from you Qonto account in an integer format. - `debit_currency`: Must be EUR. ISO 4217 formatted. ##### Credit - `credit_amount`: The amount that the beneficiary will receive. - `credit_amount_cents`: The amount that the beneficiary will receive in an integer format. - `credit_currency`: Equals debit currency if issued in the SEPA network (only supported currencies). ISO 4217 format. Allowed value for international transfers: AUD, CAD, CHF, CNY, CZK, DKK, GBP, HKD, HRK, HUF, ILS, JPY, NOK, NZD, PLN, RON, SEK, USD ##### FX rate - `rate_applied`: Foreign exchange rate applied to your transaction, formatted with 4 digits after comma. Ex: 1,1082 #### Timestamps Each external transfer contains three timestamps: * `created_at`, UTC, the time at which the external transfer was first recorded. * `processed_at`, UTC, when the external transfer has been started to be processed by Qonto. * `completed_at`, UTC, when the external transfer is in its final state, either settled or declined. * `scheduled_date`, YYYY-MM-DD, indicates when the external transfer was scheduled to be sent by Qonto. ##### Status `status` can contain the following values * `pending`: External transfer is created and has not been processed yet. If transfer is not processed within next minute, it means either execution date may not been reached yet or we are running some compliance checks on this transfer. * `processing`: External transfer processing means account balance is debited and a transaction has been created. Processing status can last up to multiple hours until transfer is sent in the network to the beneficiary. * `canceled`: When the external transfer is canceled by a user in the interface. This is a permanent status. * `declined`: When the external transfer is declined by the screening service, fraud service or, once sent on the network, for many various reasons which are listed in [those guidelines](https://www.europeanpaymentscouncil.eu/sites/default/files/kb/file/2023-11/EPC135-18%20v5.0%20Guidance%20on%20Reason%20Codes%20for%20SCT%20R-transactions.pdf). This is a permanent status. * `settled`: When the external transfer is sent to the network, transfer is settled. This is a permanent status. security: - OAuth: - organization.read - SecretKey: [] /v2/external_transfers: get: summary: List external transfers operationId: list_external_transfers parameters: - schema: type: array items: type: string example: pending enum: - pending - processing - canceled - declined - settled default: pending in: query name: status required: false - schema: type: string example: '2019-01-10T11:47:53.123Z' in: query name: updated_at_from required: false - schema: type: string example: '2019-01-10T11:47:53.123Z' in: query name: updated_at_to required: false - schema: type: string example: '2019-01-10' in: query name: scheduled_date_from required: false - schema: type: string example: '2019-01-10' in: query name: scheduled_date_to required: false - schema: type: array items: type: string format: uuid in: query name: beneficiary_ids - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: lists external transfers content: application/json: schema: type: object properties: external_transfers: type: array items: $ref: '#/components/schemas/ExternalTransfer' meta: $ref: '#/components/schemas/Pagination' '422': description: Returns errors content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string detail: type: string source: type: object properties: pointer: type: string examples: when updated_at is invalid: value: errors: - code: invalid detail: updated_at_from is not a valid date source: properties: pointer: /external_transfer/updated_at_from tags: - External Transfers description: | OAuth scope: `organization.read` --- Retrieve a list of external transfers. --- ## Attributes details ##### Initiator ID ID of the membership that initiated the external transfer.
When the external transfer is initiated through the API, the initiator is the authenticated membership. ##### Debit - `debit_iban`: Can be any of the organization's bank accounts. IBAN formatted ISO 13616. - `debit_amount`: The amount that will be debited from your Qonto account. - `debit_amount_cents`: The amount that will be debited from you Qonto account in an integer format. - `debit_currency`: Must be EUR. ISO 4217 formatted. ##### Credit - `credit_amount`: The amount that the beneficiary will receive. - `credit_amount_cents`: The amount that the beneficiary will receive in an integer format. - `credit_currency`: Equals debit currency if issued in the SEPA network (only supported currencies). ISO 4217 format. Allowed value for international transfers: AUD, CAD, CHF, CNY, CZK, DKK, GBP, HKD, HRK, HUF, ILS, JPY, NOK, NZD, PLN, RON, SEK, USD ##### FX rate - `rate_applied`: Foreign exchange rate applied to your transaction, formatted with 4 digits after comma. Ex: 1,1082 #### Timestamps Each external transfer contains three timestamps: * `created_at`, UTC, the time at which the external transfer was first recorded. * `processed_at`, UTC, when the external transfer has been started to be processed by Qonto. * `completed_at`, UTC, when the external transfer is in its final state, either settled or declined. * `scheduled_date`, YYYY-MM-DD, indicates when the external transfer was scheduled to be sent by Qonto. ##### Status `status` can contain the following values * `pending`: External transfer is created and has not been processed yet. If transfer is not processed within next minute, it means either execution date may not been reached yet or we are running some compliance checks on this transfer. * `processing`: External transfer processing means account balance is debited and a transaction has been created. Processing status can last up to multiple hours until transfer is sent in the network to the beneficiary. * `canceled`: When the external transfer is canceled by a user in the interface. This is a permanent status. * `declined`: When the external transfer is declined by the screening service, fraud service or, once sent on the network, for many various reasons which are listed in [those guidelines](https://www.europeanpaymentscouncil.eu/sites/default/files/kb/file/2023-11/EPC135-18%20v5.0%20Guidance%20on%20Reason%20Codes%20for%20SCT%20R-transactions.pdf). This is a permanent status. * `settled`: When the external transfer is sent to the network, transfer is settled. This is a permanent status. ## Filters #### `status` External transfers can be filtered by status. The `status` query parameter accepts an array of statuses as value. The possible values are: `pending`, `processing`, `canceled`, `declined` and `settled`. For example, if you want to retrieve several External Transfers statuses, you can use the following filter: `status[]=processing&status[]=declined&status[]=settled` #### `beneficiary_ids` Allows filtering on a list of beneficiary IDs #### `updated_at` / `scheduled_date` External transfers can be filtered according to both `updated_at` and `scheduled_date` fields. This is particularly useful to retrieve only the latest external transfers in your application. Two filters are available : - **updated_at** - `updated_at_from`: Minimum value (e.g: `2019-01-10T11:47:53.123Z`) - `updated_at_to`: Maximum value - **scheduled_date** - `scheduled_date_from`: Minimum value - `scheduled_date_to`: Maximum value **Do note**: - *You can use one or the other `updated_at` filter (same for `scheduled_date`), or use them in combination if you want external transfers updated within a specific timeframe.* - *`updated_at` / `scheduled_date` filters should have a valid date time format (**ISO 8601** for instance)* ## Sorting External transfers can be sorted by a specific field and order. The `sort_by` query parameter accepts a string defining these two items with the `field:order` format. #### Field - `scheduled_date` and `updated_at` values are available. #### Order - Two values are available : `asc` (Ascending) / `desc` (Descending) - By default the order used to sort external transfers is `desc` **Do note**: You can use a combination of field and order to define how to sort external transfers: - Only field (e.g `updated_at`, order will have default value `desc`) - Only order (e.g `:asc`, field will have default value `updated_at`) - Both (e.g `updated_at:asc`) security: - OAuth: - organization.read - SecretKey: [] post: summary: Create an external transfer with trusted beneficiary operationId: create_external_transfer security: - OAuth: - payment.write parameters: - name: X-Qonto-Idempotency-Key schema: type: string required: true in: header description: This parameter is required. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. The idempotency key must be a unique string. We recommend using a UUID. - $ref: '#/components/parameters/X-Qonto-Staging-Token' requestBody: content: application/json: schema: type: object required: - external_transfer properties: external_transfer: type: object required: - beneficiary_id - debit_iban - reference - amount - currency properties: beneficiary_id: type: string format: uuid debit_iban: type: string reference: type: string note: type: string currency: type: string description: ISO 4217 scheduled_date: type: string example: '2021-07-12' amount: type: string attachment_ids: type: array items: type: string format: uuid responses: '200': description: returns an external transfer content: application/json: schema: type: object required: - external_transfer properties: external_transfer: $ref: '#/components/schemas/ExternalTransfer' '422': description: Returns errors content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string detail: type: string source: type: object properties: pointer: type: string examples: when beneficiary is not trusted: value: errors: - code: untrusted_beneficiary detail: External transfers can only be initiated to trusted beneficiaries source: properties: pointer: /external_transfer/beneficiary_id when debit_iban cannot be found: value: errors: - code: not_found detail: Bank account was not found source: properties: pointer: /external_transfer/debit_iban when reference is missing: value: errors: - code: missing_key detail: reference is missing source: pointer: /external_transfer/reference when amount is missing: value: errors: - code: missing_key detail: amount is missing source: pointer: /external_transfer/amount when currency is missing: value: errors: - code: missing_key detail: currency is missing source: pointer: /external_transfer/currency when the iban is not in SEPA: value: errors: - code: iban_not_sepa detail: Beneficiary is not in SEPA source: pointer: /external_transfer/beneficiary_id when there are not enough funds in the account: value: errors: - code: insufficient_funds detail: The account has insufficient funds source: pointer: /external_transfer/debit_iban when attachment id cannot be found: value: errors: - code: not_found detail: Attachment not found id=6cc7f2dd-ea0d-4cc2-ba30-f3e1ce0a8eb4 source: pointer: /external_transfer/attachment_ids/1 when attachment_ids exceeds max limit: value: errors: - code: above_max_size detail: attachment_ids cannot be greater than 5 source: pointer: /external_transfer/attachment_ids tags: - External Transfers description: | OAuth scope: `payment.write` --- Automated creation of a instant external transfer with no user interaction involved once the beneficiary is trusted. --- This endpoint allows you to execute transfers for a given beneficiary. The beneficiary must be trusted for the transfer to be created. The beneficiary can **only** be trusted through the [Qonto web-app](https://app.qonto.com/) (for more details, please refer to [this article](https://support-fr.qonto.com/hc/en-us/articles/23947644174993-How-can-I-mark-a-payee-as-trustworthy#h_925061f25d)). The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. The idempotency key must be a unique string. We recommend using a UUID. ## Request parameter details #### `X-Qonto-Idempotency-Key` header This is a unique string (we advise to use a `uuid`) that identifies a transfer. This is used by Qonto to prevent "double spending" by accidentaly replaying the same API call. ##### Amount and Currency * The `amount` corresponds to the amount of the transaction in the `currency` of the bank account. Amounts must be https://www.w3.org/TR/payment-request/#dfn-valid-decimal-monetary-value * The `currency` should be EUR. ##### Reference * Transfer reference that can be used to enter transfer details to further describe the transfer * Maximum `reference` length is `99` characters ##### Debit iban * `debit_iban`: IBAN of account to debit ##### Attachments You can link up to 5 attachments per transfer by passing the `attachment_ids` parameter. You can upload your attachments using our [POST /v2/attachments](https://qonto-next.stoplight.io/docs/business-api/branches/create-attachments/b3A6MzU2NjMxMzU-upload-attachment) endpoint. **Note: For SEPA transfers above 30,000 EUR at least one attachment is required** /v2/external_transfers/checkout: post: summary: Create external transfers with beneficiary data operationId: external_transfers_checkout security: - OAuth: - payment.write requestBody: content: application/json: schema: type: object required: - external_transfers - debit_iban properties: debit_iban: type: string external_transfers: type: array items: type: object required: - credit_iban - credit_account_name - credit_account_currency - reference - currency - amount properties: credit_iban: type: string credit_account_name: type: string credit_account_currency: type: string description: ISO 4217 reference: type: string note: type: string currency: type: string description: ISO 4217 scheduled_date: type: string example: '2021-07-12' amount: type: string idempotency_key: type: string format: uuid attachment_ids: type: array items: type: string format: uuid responses: '200': description: returns an array of external transfers content: application/json: schema: type: object required: - external_transfers - errors properties: external_transfers: type: array items: $ref: '#/components/schemas/ExternalTransfer' errors: type: array items: type: object required: - code properties: code: type: string detail: type: string source: type: object properties: pointer: type: string examples: only successes: value: external_transfers: - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 slug: my-slug debit_iban: string debit_amount: '12.55' debit_amount_cents: '1255' debit_currency: EUR initiator_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 beneficiary_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 credit_amount: '12.55' credit_amount_cents: '1255' credit_currency: EUR rate_applied: null payment_purpose: goods reference: my-reference note: Some note declined_reason: null status: pending scheduled_date: '2021-07-12' created_at: '2021-01-27T22:05:07.000Z' completed_at: '2021-01-27T22:05:07.000Z' processed_at: '2021-01-27T22:05:07.000Z' transaction_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: [] partial successes and errors: value: external_transfers: - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 slug: my-slug debit_iban: string debit_amount: '12.55' debit_amount_cents: '1255' debit_currency: EUR initiator_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 beneficiary_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 credit_amount: '12.55' credit_amount_cents: '1255' credit_currency: EUR rate_applied: null payment_purpose: goods reference: my-reference note: Some note declined_reason: null status: pending scheduled_date: '2021-07-12' created_at: '2021-01-27T22:05:07.000Z' completed_at: '2021-01-27T22:05:07.000Z' processed_at: '2021-01-27T22:05:07.000Z' transaction_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - code: not_found detail: Bank account was not found source: properties: pointer: /external_transfers/1/debit_iban only errors: value: external_transfers: [] errors: - code: not_found detail: Bank account was not found source: properties: pointer: /external_transfers/1/debit_iban '403': description: returns a forbidden error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: forbidden detail: User does not have sufficient permissions for this action. - code: forbidden detail: The organization’s price plan does not allow to do bulk transfer. '422': description: Returns errors content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string detail: type: string source: type: object properties: pointer: type: string examples: when debit_iban cannot be found: value: errors: - code: not_found detail: Bank account was not found source: properties: pointer: /debit_iban tags: - External Transfers description: "OAuth scope: `payment.write`\n\n\n**Accessible only using [Strong Customer Authentication](https://api-doc.qonto.com/docs/business-api/ZG9jOjI5MDg3NzA4-strong-customer-authentication)**.\n\n\n>\U0001F4A1 Example of SCA usage: [**Postman visual flow**](https://www.postman.com/qontoteam/workspace/qonto-public-api/flow/6670429eb7bd63003156bd57)\n\n---\n\n**Solo basic plans**\n\n- Create a single instant external transfer with creditor data.\n- **Solo basic** plans are not allowed to do bulk transfers. If a bulk transfer is attempted, it will fail and an error will be returned.\n\n**Rest of plans**\n\nCreate a maximum of 400 instant external transfers with creditor data.\nThis API requires user interaction both for creation and approval of the external transfers. If you are interested in machine-to-machine communication without **Strong Customer Authentication**, check our [external transfer with trusted beneficiaries](https://api-doc.qonto.com/docs/business-api/47280509cae8c-create-an-external-transfer) endpoint.\n\n---\n\nThe API supports idempotency for safely retrying requests without accidentally performing the same operation twice. The idempotency key must be a unique string. We recommend using a UUID.\n\nWhen there is a `422` error, the easiest way to identify the invalid external transfer in the list, look at the `errors[x].source.pointer`. The structure of the pointer will be the root key which will always be `external_transfers`, followed by the index of the ID in the list. For example, `/external_transfers/1/amount` indicates that the second entry in the external transfers array is unprocessable due to its amount.\n\n## Max number of transfers : 400\n\n## Attributes details\n\n##### Initiator ID\nID of the membership that initiated the external transfer.\n
When the external transfer is initiated through the API, the initiator is the authenticated membership.\n\n##### Debit\n- `debit_iban`: Can be any of the organization's bank accounts. IBAN formatted ISO 13616.\n- `debit_amount`: The amount that will be debited from your Qonto account.\n- `debit_amount_cents`: The amount that will be debited from you Qonto account in an integer format.\n- `debit_currency`: Must be EUR. ISO 4217 formatted.\n\n##### Credit\n- `credit_amount`: The amount that the creditor will receive.\n- `credit_amount_cents`: The amount that the creditor will receive in an integer format.\n- `credit_currency`: Equals debit currency if issued in the SEPA network (only supported currencies). ISO 4217 format.\n\n##### FX rate\n- `rate_applied`: Foreign exchange rate applied to your transaction, formatted with 4 digits after comma. Ex: 1,1082\n\n#### Timestamps\n\nEach external transfer contains three timestamps:\n\n* `created_at`, UTC, the time at which the external transfer was first recorded.\n* `processed_at`, UTC, when the external transfer has been started to be processed by Qonto.\n* `completed_at`, UTC, when the external transfer is in its final state, either settled or declined.\n* `scheduled_date`, YYYY-MM-DD, indicates when the external transfer was scheduled to be sent by Qonto.\n\n##### Status\n`status` can contain the following values\n\n* `pending`: External transfer is created and has not been processed yet. If transfer is not processed within next minute, it means either execution date may not been reached yet or we are running some compliance checks on this transfer.\n* `processing`: External transfer processing means account balance is debited and a transaction has been created. Processing status can last up to multiple hours until transfer is sent in the network to the beneficiary.\n* `canceled`: When the external transfer is canceled by a user in the interface. This is a permanent status.\n* `declined`: When the external transfer is declined by the screening service, fraud service or, once sent on the network, for many various reasons which are listed in [those guidelines](https://www.europeanpaymentscouncil.eu/sites/default/files/kb/file/2023-11/EPC135-18%20v5.0%20Guidance%20on%20Reason%20Codes%20for%20SCT%20R-transactions.pdf). This is a permanent status.\n* `settled`: When the external transfer is sent to the network, transfer is settled. This is a permanent status.\n\n## Request parameter details\n\n##### Idempotency_key\n\nThis is a unique string (we advise to use a `uuid`) that identifies a transfer. This is used by Qonto to prevent \"double spending\" by accidentaly replaying the same API call.\n\nThe `idempotency_key` must be the same for all the call sequence used during the SCA flow :\n\n- For each transfer, The `idempotency_key` is first set on the initial call, which will trigger the SCA flow.\n- The **same** `idempotency_key` **must** be used on the final call that includes the SCA token.\n\nThis is so because the two calls are actually related to the **same transfer**.\n\n##### Amount and Currency\n* The `amount` corresponds to the amount of the transaction in the `currency` of the bank account. Amounts must be https://www.w3.org/TR/payment-request/#dfn-valid-decimal-monetary-value\n* The `currency` should be EUR.\n\n##### Reference\n* Transfer reference that can be used to enter transfer details to further describe the transfer\n* Maximum `reference` length is `140` characters\n\n##### Debit iban\n* `debit_iban`: IBAN of account to debit\n\n##### Creditor\n* `credit_iban`: IBAN of account to credit\n* `credit_account_name`: The name of the credit account\n* `credit_account_currency`: Can be either the currency of the `debit_iban` or the currency of the creditor. Allowed values is only `EUR` at the moment.\n\n##### Attachments\nYou can link up to 5 attachments per transfer by passing the `attachment_ids` parameter. You can upload your attachments using our [POST /v2/attachments](https://qonto-next.stoplight.io/docs/business-api/branches/create-attachments/b3A6MzU2NjMxMzU-upload-attachment) endpoint. **Note: For SEPA transfers above 30,000 EUR at least one attachment is required**\n" parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' /v2/beneficiaries: get: summary: List beneficiaries operationId: list_beneficiaries parameters: - schema: type: boolean in: query name: trusted required: false - schema: type: array items: type: string example: pending enum: - pending - validated - declined default: validated in: query name: status required: false - schema: type: array items: type: string example: FR7616798000010000005663951 in: query name: iban required: false - schema: type: string example: '2019-01-10T11:47:53.123Z' in: query name: updated_at_from required: false - schema: type: string example: '2019-01-10T11:47:53.123Z' in: query name: updated_at_to required: false - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: lists beneficiaries for a given organization content: application/json: schema: type: object required: - beneficiaries - meta properties: beneficiaries: type: array items: $ref: '#/components/schemas/Beneficiary' meta: $ref: '#/components/schemas/Pagination' '422': description: Returns errors content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string detail: type: string source: type: object properties: pointer: type: string examples: when updated_at is invalid: value: errors: - code: invalid detail: updated_at_from is not a valid date source: properties: pointer: /external_transfer/updated_at_from tags: - Beneficiaries description: | OAuth scope: `organization.read` --- Retrieve a list of beneficiaries. --- ## Attributes details #### Trusted `trusted` indicates whether you can automate transfer through API to the beneficiary or not. #### Timestamps Each beneficiary contains two timestamps: * `created_at`, UTC, the time at which the beneficiary was first recorded. * `updated_at`, UTC, the time at which the beneficiary was last updated. ##### Status `status` can contain the following values * `pending`: Beneficiary is created but no Strong Customer Authentication or Transfer has ever been done on this beneficiary. * `validated`: Beneficiary is created and at least one Strong Customer Authentication or Transfer has been done to this beneficiary. * `declined`: Beneficiary is malformatted and prevent from Qonto to processing transfer. ##### Bank account Fields in the `bank_account` object will be populated depending upon the type of the account. If the type is: - Swift BIC or SEPA: `iban`, `currency` and `bic` will be present. - Swift code: `account_number`, `swift_sort_code`, `intermediary_bank_bic` and `currency` will be present. - Swift routing number: `account_number`, `routing_number`, `intermediary_bank_bic` and `currency` will be present. ## Filters #### `status` Beneficiaries can be filtered by status. The `status` query parameter accepts an array of statuses as value. The possible values are: `pending`, `validated` and `declined`. For example, if you want to retrieve several Beneficiaries statuses, you can use the following filter: `status[]=pending&status[]=validated&status[]=declined` #### `trusted` Boolean property that can filter beneficiaries by `true` or `false`. #### `iban` Beneficiaries can be filtered by IBAN. The `iban` query parameter accepts an array of IBANs as value. #### `updated_at` Beneficiaries can be filtered by the `updated_at` field. This is particularly useful to retrieve only the latest beneficiaries in your application. - **updated_at** - `updated_at_from`: Minimum value (e.g: `2019-01-10T11:47:53.123Z`) - `updated_at_to`: Maximum value **Do note**: - *`updated_at` filters should have a valid date time format (**ISO 8601** for instance)* ## Sorting Beneficiaries can be sorted by a specific field and order. The `sort_by` query parameter accepts a string defining these two items with the `field:order` format. #### Field - `updated_at` value is available. #### Order - Two values are available : `asc` (Ascending) / `desc` (Descending) - By default the order used to sort beneficiaries is `desc` **Do note**: You can use a combination of field and order to define how to sort beneficiaries: - Only field (e.g `updated_at`, order will have default value `desc`) - Only order (e.g `:asc`, field will have default value `updated_at`) - Both (e.g `updated_at:asc`) security: - OAuth: - organization.read - SecretKey: [] '/v2/beneficiaries/{id}': get: summary: Show beneficiary operationId: get_beneficiary parameters: - name: id in: path required: true schema: type: string example: e72f6e43-0f27-4415-8781-ad648a89b47f - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: returns a beneficiary content: application/json: schema: type: object properties: beneficiary: $ref: '#/components/schemas/Beneficiary' '404': description: returns a not found error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string source: type: object properties: parameter: type: string example: errors: - code: not_found detail: Beneficiary not found source: parameter: id tags: - Beneficiaries description: | OAuth scope: `organization.read` --- Get a single beneficiary. --- ## Attributes details #### Trusted `trusted` indicates whether you can automate transfer through API to the beneficiary or not. #### Timestamps Each beneficiary contains two timestamps: * `created_at`, UTC, the time at which the beneficiary was first recorded. * `updated_at`, UTC, the time at which the beneficiary was last updated. ##### Status `status` can contain the following values * `pending`: Beneficiary is created but no Strong Customer Authentication or Transfer has ever been done on this beneficiary. * `validated`: Beneficiary is created and at least one Strong Customer Authentication or Transfer has been done to this beneficiary. * `declined`: Beneficiary is malformatted and prevent from Qonto to processing transfer. ##### Bank account Fields in the `bank_account` object will be populated depending upon the type of the account. If the type is: - Swift BIC or SEPA: `iban`, `currency` and `bic` will be present. - Swift code: `account_number`, `swift_sort_code`, `intermediary_bank_bic` and `currency` will be present. - Swift routing number: `account_number`, `routing_number`, `intermediary_bank_bic` and `currency` will be present. security: - OAuth: - membership.read - SecretKey: [] /v2/beneficiaries/untrust: patch: summary: Untrust a list of beneficiaries operationId: untrust_beneficiaries security: - OAuth: - payment.write - SecretKey: [] requestBody: content: application/json: schema: type: object required: - ids properties: ids: type: array items: type: string format: uuid example: 921c60fc-df0e-4289-a864-38a438ad2366 responses: '200': description: returns the updated beneficiaries content: application/json: schema: type: object properties: beneficiaries: type: array items: $ref: '#/components/schemas/Beneficiary' '422': description: Returns errors content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string detail: type: string source: type: object properties: pointer: type: string examples: when ids is missing or empty: value: errors: - code: missing_ids detail: IDs are missing when ids is more than the max allowed: value: errors: - code: ids_limit_reached detail: Size of ids cannot exceed 400 when at least one ID in the list is not found: value: errors: - code: not_found detail: Beneficiary not found for id=9ddeab87-2602-4d89-8eac-678407498447 source: pointer: /beneficiaries/1/id tags: - Beneficiaries description: | OAuth scope: `payment.write` --- Untrust an array of beneficiaries. Max number of IDs is 400. --- When there is a `422` error, the easiest way to identify which ID in the list is the invalid one, look at the `errors[x].source.pointer`. The structure of the pointer will be the root key which will always be `beneficiaries`, followed by the index of the ID in the list. For example, if in the array of IDs `["abc", "xyz"]` the first ID cannot be found the pointer will be `/beneficiaries/0/id`. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' /v2/attachments: post: summary: Upload attachment security: - OAuth: - attachment.write - SecretKey: [] parameters: - schema: type: string format: uuid in: header name: X-Qonto-Idempotency-Key description: The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. example: 4668aec5-4e9c-4a41-b6d1-fc3c13c70dd5 - $ref: '#/components/parameters/X-Qonto-Staging-Token' requestBody: content: multipart/form-data: schema: type: object properties: file: type: string format: binary examples: example: value: file: <% multipart/form-data file data %> example: file: test_image.png application/x-www-form-urlencoded: schema: type: object properties: file: type: string example: file: foobar.png description: |- OAuth scope: `payment.write` --- You have to specify multipart form data in order to attach the file to the request. When using `curl` it will look like that: ``` curl --request POST \ --url https://thirdparty.qonto.com/v2/attachments \ -H "Content-Type: multipart/form-data" \ -H "Authorization: {Auth}" \ -F file="@path/to/a/file.jpg" ``` responses: '200': description: returns an attachment ID content: application/json: schema: type: object properties: attachment: type: object properties: id: type: string example: attachment: id: 71c32755-d0c3-4d82-9a78-774caa9d8556 '400': description: returns a bad request error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string source: type: object properties: pointer: type: string examples: when file is too big: value: errors: - code: file_too_big detail: File is too big source: pointer: /file when file is not the correct type: value: errors: - code: invalid_file_type detail: Invalid file type source: pointer: /file '403': description: returns a forbidden error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: forbidden detail: User does not have sufficient permissions for this action. tags: - Attachments description: |- OAuth scope: `attachment.write` --- Upload an attachment --- This endpoint allows you to upload an attachment to be then linked to an external transfer. Valid files are: JPEG, PNG and PDFs. The endpoint is particularly useful when you want to link an attachment to an external transfer via [POST /v2/external_transfers](https://api-doc.qonto.com/docs/business-api/b3A6MjM2NDE0OTk-create-an-external-transfer) and [POST /v2/external_transfers/checkout](https://api-doc.qonto.com/docs/business-api/b3A6MzAxODAwMDI-create-external-transfers-with-creditor-data). Inside Qonto, attachments are files uploaded onto transactions by users. Attachments typically correspond to the *invoice* or *receipt*, and are used to justify the transactions from a bookkeeping standpoint. '/v2/attachments/{id}': get: summary: Show attachment operationId: get_attachment security: - OAuth: - organization.read - SecretKey: [] parameters: - name: id in: path required: true schema: type: string example: e72f6e43-0f27-4415-8781-ad648a89b47f - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: returns an attachment content: application/json: schema: type: object properties: attachment: type: object properties: id: type: string created_at: type: string file_name: type: string file_size: type: string file_content_type: type: string url: type: string probative_attachment: type: object properties: status: type: string file_name: type: string file_content_type: type: string file_size: type: string url: type: string example: attachment: id: 71c32755-d0c3-4d82-9a78-774caa9d8556 created_at: '2021-03-23T14:21:51.000Z' file_name: Foobar file_size: '666' file_content_type: image/png url: 'https://my-s3.url.qonto.bucket.com/123456789' probative_attachment: status: unavailable file_name: statement.pdf file_content_type: application/pdf file_size: '666' url: 'https://my-s3.url.qonto.bucket.com/123456789' '401': description: returns an unauthorized error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: unauthorized detail: You must be authenticated to perform this action description: | OAuth scope: `organization.read` --- Obtain the details (e.g: download URL) for a specific attachment. --- Inside Qonto, attachments are files uploaded onto transactions by users. Attachments typically correspond to the *invoice* or *receipt*, and are used to justify the transactions from a bookkeeping standpoint. You can retrieve the IDs of those attachments inside each Transaction object, by calling [List transactions](/reference/openapi_v2.yml/paths/~1v2~1transactions/get). Probative attachment is another version of attachment, compliant with [PAdES](https://en.wikipedia.org/wiki/PAdES) standard. **Important**: for security reasons, the `url` you retrieve for each Attachment is only valid for 30 minutes. If you need to download the file after more than 30 minutes, you will need to perform another authenticated call in order to generate a new download URL. Note: if you download the file using `curl`, replace the `\u0026` references by `&` in the `url` string. tags: - Attachments parameters: - schema: type: string name: id in: path required: true /v2/labels: get: operationId: get_labels summary: List labels responses: '200': description: list labels for a given organization content: application/json: schema: type: object properties: labels: type: array items: type: object properties: id: type: string name: type: string parent_id: type: string nullable: true meta: type: object properties: current_page: type: integer next_page: type: integer nullable: true prev_page: type: integer nullable: true total_pages: type: integer total_count: type: integer per_page: type: integer example: labels: - id: 171dba70-c75f-4337-b419-377a59bc9cf3 name: Fantastic Marble Wallet parent_id: null - id: 2487a014-618f-40e3-8a1f-eb76e883efc5 name: Fantastic Bronze Computer parent_id: 171dba70-c75f-4337-b419-377a59bc9cf3 meta: current_page: 1 next_page: null prev_page: null total_pages: 1 total_count: 2 per_page: 100 tags: - Labels description: | OAuth scope: `organization.read` --- Retrieve all labels within the organization. --- The response contains the list of labels that are linked to the authenticated company. The `id` field uniquely identifies the label and is used to identify the **label_ids** of a transaction (see [List transactions](/reference/openapi_v2.yml/paths/~1v2~1transactions/get)) ### Parent A label can be linked to another in order to create lists. The parent label can be identified thanks to the `parent_id` field. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' security: - OAuth: - organization.read - SecretKey: [] '/v2/labels/{id}': get: summary: Show label security: - OAuth: - organization.read - SecretKey: [] parameters: - name: id in: path required: true schema: type: string example: 2d9663fd-1748-4ed4-a590-48066ae9e1cb - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: returns a label content: application/json: schema: type: object properties: label: type: object properties: id: type: string name: type: string parent_id: type: string example: label: id: 2d9663fd-1748-4ed4-a590-48066ae9e1cb name: Lightweight Granite Pants parent_id: 053b8439-56a6-48ac-9fad-7b2973a53ae3 tags: - Labels description: | OAuth scope: `organization.read` --- Retrieve all labels within the organization. --- The response contains the list of labels that are linked to the authenticated company. The `id` field uniquely identifies the label and is used to identify the **label_ids** of a transaction (see [List transactions](/reference/openapi_v2.yml/paths/~1v2~1transactions/get)) ### Parent A label can be linked to another in order to create lists. The parent label can be identified thanks to the `parent_id` field. /v2/memberships: get: summary: List memberships security: - OAuth: - organization.read - SecretKey: [] responses: '200': description: list memberships for a given organization content: application/json: schema: type: object properties: memberships: type: array items: type: object properties: id: type: string format: uuid example: c9f9f051-7558-451c-b310-f4b8521424aa first_name: type: string example: Quinn Jast last_name: type: string example: Miss Stan Altenwerth role: type: string enum: - owner - admin - manager - reporting - employee example: owner residence_country: type: string nullable: true example: FR birthdate: type: string example: '2022-11-27' format: date nullable: true nationality: type: string nullable: true example: FR ubo: type: boolean nullable: true birth_country: type: string nullable: true example: IT status: type: string example: active meta: $ref: '#/components/schemas/Pagination' example: memberships: - id: c9f9f051-7558-451c-b310-f4b8521424aa first_name: Quinn Jast last_name: Miss Stan Altenwerth role: owner residence_country: FR birthdate: '1987-07-12' nationality: FR ubo: true birth_country: IT meta: current_page: 1 next_page: null prev_page: null total_pages: 1 total_count: 1 per_page: 100 '401': description: returns an unauthorized error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string example: unauthorized detail: type: string example: Invalid credentials '403': description: returns a forbidden error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string example: forbidden detail: type: string example: Forbidden tags: - Memberships description: | OAuth scope: `organization.read` --- Retrieve all memberships within the organization. --- The response contains the list of memberships that are linked to the authenticated company. A member is a user who's been granted access to the Qonto account of a company. There is no limit currently to the number of memberships a company can have. The response contains the following attributes: - `id` - The membership's id. It uniquely identifies the membership - `first_name` - The first name of the membership - `last_name` - The last name of the membership - `role` - Role of the membership: `owner`, `admin`, `manager`, `reporting`, `employee` For Spain companies, the list also contains data about the UBOs (Ultimate Beneficiary Owner) of the company in addition to the fields above: - `residence_country` - Residential country of the member - `birthdate` - Date of birth of the member - `nationality` - The nationality of the member - `ubo` - The possession of the member: `true`, `false` - `birth_country` - The birth country of the member operationId: '' parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' /v2/membership: get: summary: Get details of a single membership security: - OAuth: - membership.read responses: '200': description: returns a membership. The membership returned is determined from the secret-key or OAuth2 token. content: application/json: schema: type: object properties: membership: type: object additionalProperties: false properties: id: type: string example: c9f9f051-7558-451c-b310-f4b8521424aa readOnly: true first_name: type: string example: Bruce Thomas Patrick readOnly: true last_name: type: string example: Wayne readOnly: true email: type: string example: batman@dc-comics.com readOnly: true phone_number: type: string example: '+49123456789' readOnly: true position: type: string example: Criminals threatener readOnly: true status: type: string example: active readOnly: true role: type: string example: owner locale: type: string example: de team_id: type: string example: d1f9f066-5642-462d-b421-a7d8521556bc example: membership: id: c9f9f051-7558-451c-b310-f4b8521424aa first_name: Bruce Thomas Patrick last_name: Wayne email: batman@dc-comics.com phone_number: '+49123456789' position: Criminals threatener status: active role: owner locale: de team_id: d1f9f066-5642-462d-b421-a7d8521556bc '401': description: returns an unauthorized error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: unauthorized detail: You must be authenticated to perform this action '403': description: returns a forbidden error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: forbidden detail: User does not have sufficient permissions for this action. tags: - Memberships description: |- OAuth scope: `membership.read` --- Retrieve the details of the authenticated Membership. --- The response contains the following attributes: - `id` - The membership's id - `first_name` - The first name of the membership - `last_name` - The last name of the membership - `email` - The email address of the membership - `phone_number` - The phone number of the membership - `position` - The professional position of the membership within the company (e.g.: CEO, financial manager) - `status` - Status of the membership (e.g: active) - `role` - The set of permissions of the membership within the organization's account (e.g.: owner, admin). - `locale` - The language chosen by the membership - `team_id` - The team's id that the membership belongs to operationId: '' parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' /v2/memberships/invite_employee_or_accountant: post: summary: Create and invite a new membership security: - OAuth: - membership.write requestBody: content: application/json: schema: type: object required: - membership properties: membership: type: object properties: email: type: string format: email example: client@qonto.com description: email of the person being invited to join the organization first_name: type: string example: Bruce Thomas Patrick description: first name of the person being invited to join the organization last_name: type: string example: Wayne description: last name of the person being invited to join the organization role: type: string example: employee enum: - reporting - employee description: role of the person being invited to join the organization team_id: type: string format: uuid description: unique identifier of the team the new membership is being assigned responses: '200': description: returns a created membership content: application/json: schema: type: object properties: membership: type: object properties: id: type: string format: uuid description: the membership's id first_name: type: string example: Bruce Thomas Patrick description: the first name of the membership being invited to join the organization last_name: type: string example: Wayne description: the last name of the membership being invited to join the organization email: type: string example: client@qonto.com description: the email address of the membership being invited to join the organization role: type: string example: employee enum: - reporting - employee description: the set of permissions of the membership within the organization's account locale: type: string description: the language chosen by the membership being invited to join the organization team_id: type: string format: uuid description: the team id to which the membership has been assigned '401': description: returns an unauthorized error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string example: unauthorized detail: type: string example: Invalid credentials '403': description: returns a forbidden error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string example: forbidden detail: type: string example: Forbidden '422': description: returns an unprocessable entity error content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string example: blank detail: type: string example: first_name must be filled source: type: object properties: pointer: type: string example: /first_name tags: - Memberships description: |- OAuth scope: `membership.write` --- Create a new membership and invite it to the authenticated organization. This endpoint allows to create a new member and invite them into the organization into a team which is defined in the request. Once the endpoint is called correctly, the new member is created and the user receives an invitation email. In this email, the user will receive instructions on how to activate the membership and join the authenticated organization’s Qonto account. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' /v2/organization: get: summary: Get organization and its bank accounts security: - OAuth: - organization.read - SecretKey: [] responses: '200': description: Returns the organization and its bank accounts. The organization returned is determined from the `secret_key` or the OAuth2.0 `access_token`. content: application/json: schema: type: object properties: organization: type: object properties: id: type: string x-stoplight: id: a4tzn5r281lzd description: UUID of the organization. name: type: string x-stoplight: id: js7fnxkykuhcw description: Name of the organization. slug: type: string example: elektro-tesla-gmbh-3066 description: Slug based on organization's legal name. legal_name: type: string example: Elektro Tesla GmbH description: Registered name of the organization. nullable: true locale: type: string example: de description: Default language set for the organization. legal_share_capital: type: number example: 1000 description: 'Informed share capital, expressed in euros.' legal_country: type: string example: DE description: Country of incorporation of the organization. legal_registration_date: type: string example: '2022-11-27' description: Date of incorporation of the organization. nullable: true legal_form: type: string example: GmbH description: Legal formation of the organization. legal_address: type: string example: Fritz-Arnold-Str. 18 85614 Kirchseeon GERMANY description: Address of the organization. legal_sector: type: string example: 6200Z description: Code of the organization's activity sector. nullable: true contract_signed_at: type: string example: '2022-12-01 08:57:00.123047' format: date-time description: 'Date and time, in UTC, the account was opened.' legal_number: type: string example: 12A34FC5 description: 'Unique number of registration (e.g.: SIRET in France).' bank_accounts: type: array items: type: object properties: id: type: string example: 018f71db-c635-78b5-b90a-ea05de98c2bf description: UUID of the bank account. slug: type: string description: Slug of the bank account based on the organ's slug. iban: description: Might be empty for external accounts (i.e. when `is_external_accounts == true`). type: string example: FR7616798000010000005663951 bic: type: string description: Might be empty for external accounts (i.e. when `is_external_accounts == true`). currency: type: string example: EUR description: Currency of the bank account. balance: type: number format: float description: 'Actual amount of money on the account, in euros.' balance_cents: type: integer description: 'Actual amount of money on the account, in euros.' authorized_balance: type: number format: float description: 'Amount available for payments, taking into account transactions that are being processed. [More information here](https://support.qonto.com/hc/en-us/articles/115000493249-How-is-the-balance-of-my-account-calculated-).' authorized_balance_cents: type: integer description: 'Amount available for payments, taking into account transactions that are being processed. [More information here](https://support.qonto.com/hc/en-us/articles/115000493249-How-is-the-balance-of-my-account-calculated-).' name: type: string description: Name of the bank account. updated_at: type: string description: 'Date and time, in UTC, of the last update of the bank account.' example: '2024-07-02T08:25:11.155Z' status: type: string enum: - active - closed description: Status of the bank account. main: type: boolean description: Sets to`true` if the bank account is used for billing. There is only one main account in a given organization. is_external_account: type: boolean x-stoplight: id: ctlffwlm10m1e description: 'Sets to `true` if the bank account is not a Qonto account (cf. https://support-fr.qonto.com/hc/en-us/articles/24231375285777-How-to-connect-my-external-accounts-to-my-Qonto-interface).' account_number: type: string x-stoplight: id: umtk10oh2g72w description: Might be empty for Qonto accounts (i.e. when `is_external_account == false`). nullable: true example: organization: id: cb47875a-9b12-416e-aa9a-265b9dfaeee7 slug: elektro-tesla-gmbh-3066 legal_name: Elektro Tesla GmbH legal_number: 12A34FC5 legal_sector: 6200Z legal_registration_date: '2022-11-27' legal_address: Fritz-Arnold-Str. 18 85614 Kirchseeon GERMANY legal_form: GmbH legal_country: DE legal_share_capital: 1000 locale: de contract_signed_at: '2022-12-01 08:57:00.123047' bank_accounts: - slug: super-bankaccount-5785 iban: FR7616798000010000005663951 bic: TRZOFR21XXX currency: EUR balance: 100 balance_cents: 10000 authorized_balance: 100 authorized_balance_cents: 10000 name: Main account updated_at: '2021-03-23T14:00:46.967Z' status: active main: true examples: Only Qonto bank accounts: value: organization: id: 3e29cef2-4808-421e-8c99-e83306c5e0ec name: Coopérative Boulangère Sud slug: cooperative-boulangere-sud-2161 legal_name: Coopérative Boulangère Sud locale: fr legal_share_capital: 0 legal_country: FR legal_registration_date: '2001-10-10' legal_form: SAS legal_address: 18 Rue De Navarin Chez Wework 75009 Paris FRANCE legal_sector: 6200Z contract_signed_at: '2023-07-17T16:13:41.370Z' legal_number: '81948962600039' bank_accounts: - id: 27e7e433-453c-4c32-bd3f-6802ae05940e slug: cooperative-boulangere-sud-2161-bank-account-3 iban: FR7616958000013622273207472 bic: QNTOFRP1XXX currency: EUR balance: 1 balance_cents: 100 authorized_balance: 121 authorized_balance_cents: 12100 name: Placements updated_at: '2024-07-02T08:25:11.155Z' status: active main: false is_external_account: false account_number: '' - id: 6dadba1e-a3a9-40eb-ba99-64532dbe56bc slug: cooperative-boulangere-sud-2161-bank-account-2 iban: FR7616958000012102312621849 bic: QNTOFRP1XXX currency: EUR balance: 0 balance_cents: 0 authorized_balance: 0 authorized_balance_cents: 0 name: Secondary account updated_at: '2023-10-13T15:23:31.360Z' status: closed main: false is_external_account: false account_number: '' - id: e97d6e4b-8179-47ae-88e9-3e43b230251e slug: cooperative-boulangere-sud-2161-bank-account-1 iban: FR7616958000018615533841513 bic: QNTOFRP1XXX currency: EUR balance: 41995921.54 balance_cents: 4199592154 authorized_balance: 41989694.29 authorized_balance_cents: 4198969429 name: Compte principal updated_at: '2024-08-01T10:35:09.089Z' status: active main: true is_external_account: false account_number: '' Includes external banks accounts: value: organization: id: 3e29cef2-4808-421e-8c99-e83306c5e0ec name: Coopérative Boulangère Sud slug: cooperative-boulangere-sud-2161 legal_name: 'Coopérative Boulangère Sud sandbox 2023-07-25T08:52:59Z' locale: fr legal_share_capital: 0 legal_country: FR legal_registration_date: '2001-10-10' legal_form: SAS legal_address: 18 Rue De Navarin Chez Wework 75009 Paris FRANCE legal_sector: 6200Z contract_signed_at: '2023-07-17T16:13:41.370Z' legal_number: '81948962600039' bank_accounts: - id: 27e7e433-453c-4c32-bd3f-6802ae05940e slug: cooperative-boulangere-sud-2161-bank-account-3 iban: FR7616958000013622273207472 bic: QNTOFRP1XXX currency: EUR balance: 1 balance_cents: 100 authorized_balance: 121 authorized_balance_cents: 12100 name: Placements updated_at: '2024-07-02T08:25:11.155Z' status: active main: false is_external_account: false account_number: '' - id: 6dadba1e-a3a9-40eb-ba99-64532dbe56bc slug: cooperative-boulangere-sud-2161-bank-account-2 iban: FR7616958000012102312621849 bic: QNTOFRP1XXX currency: EUR balance: 0 balance_cents: 0 authorized_balance: 0 authorized_balance_cents: 0 name: Secondary account updated_at: '2023-10-13T15:23:31.360Z' status: closed main: false is_external_account: false account_number: '' - id: e97d6e4b-8179-47ae-88e9-3e43b230251e slug: cooperative-boulangere-sud-2161-bank-account-1 iban: FR7616958000018615533841513 bic: QNTOFRP1XXX currency: EUR balance: 41995921.54 balance_cents: 4199592154 authorized_balance: 41989694.29 authorized_balance_cents: 4198969429 name: Compte principal updated_at: '2024-08-01T10:35:09.089Z' status: active main: true is_external_account: false account_number: '' - id: 0191221f-2452-735f-9144-bff2ca4fa8a4 slug: cooperative-boulangere-sud-2161-bank-account-4 iban: FR802043302626N265296869145 bic: '' currency: EUR balance: 9.02 balance_cents: 902 authorized_balance: 9.02 authorized_balance_cents: 902 name: Main Account Compte courant updated_at: '2024-08-05T10:39:13.000Z' status: active main: false is_external_account: true account_number: 0263765d-8d0e-41f0-a025-9dd2ed891507 '401': description: Returns an unauthorized error. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: unauthorized detail: You must be authenticated to perform this action tags: - Organizations description: |- OAuth scope: `organization.read` --- Retrieves the details and the list of bank accounts for the authenticated organization. --- The bank account's `id` or `iban` will be required to retrieve the list of transactions inside that bank account, using [/v2/transactions](/reference/openapi_v2.yml/paths/~1v2~1transactions/get). parameters: - schema: type: boolean default: false in: query name: include_external_accounts description: 'By default includes only Qonto accounts. Set to ''true'' if you also want to include your [connected externals account(s)](https://support-fr.qonto.com/hc/en-us/articles/24231375285777-How-to-connect-my-external-accounts-to-my-Qonto-interface).' - $ref: '#/components/parameters/X-Qonto-Staging-Token' '/v2/transactions/{id}/attachments': post: summary: Upload attachment to a transaction security: - OAuth: - attachment.write - SecretKey: [] parameters: - name: id in: path required: true schema: type: string format: uuid example: 2751a41c-c17f-43f7-bd18-04efa6cd8e30 - schema: type: string format: uuid in: header name: X-Qonto-Idempotency-Key description: The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. example: 4668aec5-4e9c-4a41-b6d1-fc3c13c70dd5 - $ref: '#/components/parameters/X-Qonto-Staging-Token' requestBody: content: multipart/form-data: schema: type: object properties: file: type: string format: binary examples: example: value: file: <% multipart/form-data file data %> example: file: test_image.png application/x-www-form-urlencoded: schema: type: object properties: file: type: string example: file: foobar.png description: |- You have to specify multipart form data in order to attach the file to the request. When using `curl` it will look like that: ``` curl --request POST \ --url https://thirdparty.qonto.com/v2/transactions/{id}/attachments \ -H "Content-Type: multipart/form-data" \ -H "Authorization: {Auth}" \ -F file="@path/to/a/file.jpg" ``` responses: '200': description: accepts the file and returns a success status code headers: {} '400': description: returns a bad request error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string source: type: object properties: pointer: type: string example: errors: - code: missing_file detail: The request is missing a file parameter source: pointer: /file '401': description: returns an unauthorized error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: unauthorized detail: You must be authenticated to perform this action '403': description: returns a forbidden error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: forbidden detail: User does not have sufficient permissions for this action. '404': description: returns a not found error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string source: type: object properties: parameter: type: string example: errors: - code: not_found detail: Transaction not found source: parameter: id tags: - Attachments in Transactions description: |- OAuth scope: `attachment.write` --- Upload an attachment to a transaction --- This endpoint allows you to upload an attachment to a transaction. Inside Qonto, attachments are files uploaded onto transactions by users. Attachments typically correspond to the *invoice* or *receipt*, and are used to justify the transactions from a bookkeeping standpoint. Probative attachment is another version of attachment, compliant with [PAdES](https://en.wikipedia.org/wiki/PAdES) standard. **Important**: for security reasons, the `url` you retrieve for each Attachment is only valid for 30 minutes. If you need to download the file after more than 30 minutes, you will need to perform another authenticated call in order to generate a new download URL. > The uploaded file will be processed in the background. This means that the created attachment will not be visible immediately. get: summary: List attachments in a transaction security: - OAuth: - organization.read - SecretKey: [] parameters: - name: id in: path required: true schema: type: string example: aab86d8a-0d4c-4749-9a49-0ada88a9c423 - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: returns a list of attachments content: application/json: schema: type: object properties: attachments: type: array items: type: object properties: id: type: string created_at: type: string file_name: type: string file_size: type: string file_content_type: type: string url: type: string probative_attachment: type: object properties: status: type: string file_name: type: string file_content_type: type: string file_size: type: string url: type: string nullable: true example: attachments: - id: 9b048e2c-d546-415b-b001-d31a6d4ae1e3 created_at: '2021-01-27T22:05:07.000Z' file_name: Foobar file_size: '666' file_content_type: image/png url: 'https://my-s3.url.qonto.bucket.com/123456789' probative_attachment: status: available file_name: statement.pdf file_content_type: application/pdf file_size: '123' url: 'https://my-s3.url.qonto.bucket.com/123456789' '401': description: returns an unauthorized error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: unauthorized detail: You must be authenticated to perform this action '404': description: returns a not found error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string source: type: object properties: parameter: type: string example: errors: - code: not_found detail: Transaction not found source: parameter: id tags: - Attachments in Transactions description: | OAuth scope: `organization.read` --- Retrieve the list of attachments within a transaction. --- Inside Qonto, attachments are files uploaded onto transactions by users. Attachments typically correspond to the *invoice* or *receipt*, and are used to justify the transactions from a bookkeeping standpoint. Probative attachment is another version of attachment, compliant with [PAdES](https://en.wikipedia.org/wiki/PAdES) standard. **Important**: for security reasons, the `url` you retrieve for each Attachment is only valid for 30 minutes. If you need to download the file after more than 30 minutes, you will need to perform another authenticated call in order to generate a new download URL. Note: if you download the file using `curl`, replace the `\u0026` references by `&` in the `url` string. delete: summary: Remove all attachments from a transaction security: - OAuth: - attachment.write - SecretKey: [] parameters: - name: id in: path required: true schema: type: string example: 2750ad5e-6c04-4096-88d8-ab43363bdb57 - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: returns a success status code '401': description: returns an unauthorized error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: unauthorized detail: You must be authenticated to perform this action '403': description: returns a forbidden error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: forbidden detail: User does not have sufficient permissions for this action. '404': description: returns a not found error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string source: type: object properties: parameter: type: string example: errors: - code: not_found detail: Transaction not found source: parameter: id tags: - Attachments in Transactions description: |- OAuth scope: `attachment.write` --- Remove all attachments from a transaction --- This endpoint allows you to remove all attachments from a transaction. Inside Qonto, attachments are files uploaded onto transactions by users. Attachments typically correspond to the *invoice* or *receipt*, and are used to justify the transactions from a bookkeeping standpoint. /v2/transactions: get: summary: List transactions security: - OAuth: - organization.read - SecretKey: [] parameters: - schema: type: string example: 018f71db-c635-78b5-b90a-ea05de98c2bf in: query name: bank_account_id description: 'The `id` of the bank account for which transactions will be retrieved. Use [/v2/organization](openapi_v2.yml/paths/~1v2~1organization/get) to get this parameter. If both `bank_account_id` and `iban` are specified, `bank_account_id` takes precedence.' allowReserved: false - schema: type: string example: FR7616798000010000005663951 in: query name: iban description: 'The IBAN of the bank account for which transactions will be retrieved. Use [/v2/organization](openapi_v2.yml/paths/~1v2~1organization/get) to get this parameter. If both `bank_account_id` and `iban` are specified, `bank_account_id` takes precedence.' - schema: type: string enum: - vat_details - labels - attachments in: query name: 'includes[]' description: 'Use this query parameter to embed the associated resources (labels, attachments and/or VAT details) of the transactions in the JSON response.' - schema: type: string example: 'status[]=completed&status[]=declined&status[]=pending' enum: - pending - declined - completed default: completed in: query name: 'status[]' description: 'Transactions can be filtered by their `status` attribute.
Possible values:
- `pending`: a transaction that is processing and has impacted the bank account''s `auth_balance` but not its `balance`;
- `declined`: a transaction that has been declined;
- `completed`: a transaction that is completed, and has impacted the bank account''s `balance`.' - schema: type: string example: '2019-01-10T11:47:53.123Z' in: query name: updated_at_from description: 'Transactions can be filtered by their `updated_at` attribute. This filter can be used in combination with the `updated_at_to` query parameter to get transactions updated within a specific timeframe. Please use a valid date time format (**ISO 8601** for instance). ' - schema: type: string example: '2019-01-10T11:47:53.123Z' in: query name: updated_at_to description: Transactions can be filtered by their `updated_at` attribute. This filter can be used in combination with the `updated_at_to` query parameter to get transactions updated within a specific timeframe. Please use a valid date time format (**ISO 8601** for instance). - schema: type: string example: '2019-01-10T11:47:53.123Z' in: query name: emitted_at_from description: Transactions can be filtered by their `emitted_at` attribute. Can be use in combination with the `emitted_at_to` query parameter to get transactions emitted within a specific timeframe. Please use a valid date time format (**ISO 8601** for instance). - schema: type: string example: '2019-01-10T11:47:53.123Z' in: query name: emitted_at_to description: Transactions can be filtered by their `emitted_at` attribute. This filter can be used in combination with the `emitted_at_from` query parameter to get transactions emitted within a specific timeframe. Please use a valid date time format (**ISO 8601** for instance). - schema: type: string example: '2019-01-10T11:47:53.123Z' in: query name: settled_at_from description: Transactions can be filtered by their `settled_at` attribute. This filter can be used in combination with the `settled_at_to` query parameter to get transactions settled within a specific timeframe. Please use a valid date time format (**ISO 8601** for instance). - schema: type: string example: '2019-01-10T11:47:53.123Z' in: query name: settled_at_to description: Transactions can be filtered by their `settled_at` attribute. This filter can be used in combination with the `settled_at_from` query parameter to get transactions settled within a specific timeframe. Please use a valid date time format (**ISO 8601** for instance). - schema: type: string enum: - credit - debit in: query name: side description: Transactions can be filtered by their `side` attribute. - schema: type: string example: 'operation_type[]=card&operation_type[]=transfer&operation_type[]=income' in: query name: 'operation_type[]' description: Transactions can be filtered by their `operation_type` attribute. - schema: type: boolean enum: - 'true' - 'false' in: query name: with_attachments description: Transactions can be filtered based on the presence of one or more attachments. - schema: type: string default: '`settled_at:desc`' in: query name: sort_by description: "Transactions can be sorted by a specific field and order (`field:order` format).
\U0001F449 Field: `updated_at`, `settled_at` or `emitted_at`
\U0001F449 Order: `asc` (Ascending) / `desc` (Descending)" - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: 'Contains the list of transactions that contributed to the given bank account''s balances (e.g., incomes, transfers, cards). All transactions visible in Qonto''s UI can be fetched, as of API V2.' content: application/json: schema: type: object properties: transactions: type: array items: $ref: '#/components/schemas/Transaction' meta: type: object properties: current_page: type: integer next_page: type: integer nullable: true prev_page: type: integer nullable: true total_pages: type: integer total_count: type: integer per_page: type: integer maximum: 100 minimum: 0 default: 100 example: transactions: - transaction_id: super-transaction-7468 amount: 0.43 amount_cents: 43 settled_balance: 111.1 settled_balance_cents: 11110 attachment_ids: [] local_amount: 0.43 local_amount_cents: 43 side: debit operation_type: transfer currency: EUR local_currency: EUR label: Ferry-Purdy settled_at: '2021-03-03T16:06:38.000Z' emitted_at: '2021-02-25T16:22:37.000Z' updated_at: '2020-12-12T19:52:10.000Z' status: completed note: Rhea Ernser reference: null vat_amount: null vat_amount_cents: null vat_rate: null initiator_id: ccdcef78-1aa1-4d44-b991-b10005a4ad1a label_ids: - 6450e541-0a6f-4153-a46e-34d98848e280 attachment_lost: false attachment_required: true card_last_digits: '1234' category: gas_station id: df346899-3595-421a-8b26-f9d9616ce496 subject_type: transfer transfer: counterparty_account_number: NL93RABO3730976796 counterparty_account_number_format: IBAN counterparty_bank_identifier: RABO counterparty_bank_identifier_format: SWIFT_BIC meta: current_page: 1 next_page: null prev_page: null total_pages: 1 total_count: 1 per_page: 100 examples: Example 1: value: transactions: - id: string transaction_id: string amount: '10,00' amount_cents: 1000 settled_balance: 0 settled_balance_cents: 0 attachment_ids: - string local_amount: '10,87' local_amount_cents: 1087 logo: small: 'https://qonto.com/customized-qonto-brand-logos/small.png' medium: 'https://qonto.com/customized-qonto-brand-logos/medium.png' side: string operation_type: string currency: string local_currency: USD label: string settled_at: string emitted_at: string updated_at: string status: string note: string reference: string vat_amount: 0 vat_amount_cents: 0 vat_rate: 10 initiator_id: string label_ids: - string attachment_lost: true attachment_required: true card_last_digits: string category: string subject_type: string bank_account_id: string is_external_transaction: true attachments: - id: string created_at: string file_name: string file_size: string file_content_type: string url: string probative_attachment: status: string labels: - id: string name: string parent_id: string vat_details: items: - amount: string amount_cents: string amount_excluding_vat: string amount_excluding_vat_cents: string rate: string transfer: counterparty_account_number: string counterparty_account_number_format: string counterparty_bank_identifier: string counterparty_bank_identifier_format: string income: counterparty_account_number: string counterparty_account_number_format: string counterparty_bank_identifier: string counterparty_bank_identifier_format: string swift_income: counterparty_account_number: string counterparty_account_number_format: string counterparty_bank_identifier: string counterparty_bank_identifier_format: string direct_debit: counterparty_account_number: string counterparty_account_number_format: string counterparty_bank_identifier: string counterparty_bank_identifier_format: string check: check_number: string check_key: string financing_installment: total_installments_number: 0 current_installment_number: 0 pagopa_payment: notice_number: string creditor_fiscal_code: string iuv: string meta: current_page: 0 next_page: null prev_page: null total_pages: 0 total_count: 0 per_page: 100 '400': description: Returns a bad request response. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string message: type: string example: errors: - code: sort_invalid message: Sort field is invalid - code: date_invalid message: The datetime in settled_at_from param isn't well formatted (ISO 8601) or year is out of range - code: status_invalid message: At least one status isn't valid '404': description: Returns a not found error. content: text/plain: schema: type: string example: ' ' '422': description: Returns errors. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string detail: type: string source: type: object properties: pointer: type: string examples: bank_account_id or iban missing: value: errors: - code: missing detail: bank_account_id or iban is missing tags: - Transactions description: "OAuth scope: `organization.read`\n\n---\n\nRetrieves all transactions for a **given bank account** identified either by its `bank_account_id` either by its `iban` (cf. [Query Parameters](https://api-doc.qonto.com/docs/business-api/2c89e53f7f645-list-transactions#Query-Parameters) \U0001F447)\n" parameters: [] '/v2/transactions/{id}': get: summary: Show transaction security: - OAuth: - organization.read - SecretKey: [] parameters: - name: id in: path required: true schema: type: string example: 7b7a5ed6-3903-4782-889d-b4f64bd7bef9 description: UUID of the transaction to retrieve. - schema: type: string enum: - vat_details - labels - attachments in: query name: 'includes[]' description: 'Use this query parameter to embed the associated resources (labels, attachments and/or VAT details) of the transactions in the JSON response.' - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: Returns a transaction. content: application/json: schema: type: object properties: transaction: $ref: '#/components/schemas/Transaction' example: transaction: transaction_id: super-transaction-6576 amount: 52.4 amount_cents: 5240 settled_balance: 111.1 settled_balance_cents: 11110 attachment_ids: [] local_amount: 52.4 local_amount_cents: 5240 side: debit operation_type: transfer currency: EUR local_currency: EUR label: Stamm and Sons settled_at: '2021-03-14T17:17:02.000Z' emitted_at: '2021-03-06T12:33:13.000Z' updated_at: '2021-03-21T21:32:03.000Z' status: completed note: Jacynthe Kuhic reference: null vat_amount: null vat_amount_cents: null vat_rate: null initiator_id: 6e5468a1-22ad-4974-bf9f-45652511d39c label_ids: - 872a75d8-b85c-467e-b8f0-091ea48ef68f attachment_lost: false attachment_required: true card_last_digits: '1234' category: gas_station id: 7b7a5ed6-3903-4782-889d-b4f64bd7bef9 attachments: - id: ea54f563-eaee-4dcb-b08e-688dc9937d23 created_at: '2021-03-18T11:52:07.000Z' file_name: Foobar file_size: '666' file_content_type: image/png url: 'https://qonto-dev.s3.eu-central-1.amazonaws.com/test/uploads/attachment/ea54f563-eaee-4dcb-b08e-688dc9937d23/%23%3CRack%3A%3ATest%3A%3AUploadedFile%3A0x00005635fc7cf8e8%3E?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAZ4DSTCECB4IXGFVF%2F20210521%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20210521T080955Z&X-Amz-Expires=1800&X-Amz-SignedHeaders=host&X-Amz-Signature=b6b8977aff8529018d15a05f3e36cc5b59e325d675b6538ff55005aa8e2eb3ed' probative_attachment: status: unavailable labels: - id: 211e69c1-f27f-4b45-a623-bec44a715ee7 name: Durable Silk Table parent_id: null subject_type: transfer transfer: counterparty_account_number: NL93RABO3730976796 counterparty_account_number_format: IBAN counterparty_bank_identifier: RABO counterparty_bank_identifier_format: SWIFT_BIC '404': description: Returns a not found error. content: text/plain: schema: type: string example: ' ' tags: - Transactions description: |- OAuth scope: `organization.read` --- Retrieves a single transaction for a given bank account. --- The response contains a single transaction that contributed to the bank account's balances (e.g., incomes, transfers, cards). All transactions visible in Qonto's UI can be fetched, as of API V2. parameters: - schema: type: string example: 7b7a5ed6-3903-4782-889d-b4f64bd7bef9 name: id in: path required: true description: UUID of the transaction. '/v2/transactions/{id}/attachments/{id}': delete: summary: Remove an attachment from a transaction security: - OAuth: - attachment.write - SecretKey: [] parameters: - name: id in: path required: true schema: type: string example: 644cf847-125e-4ec9-920d-0d09aaeb4bbc - name: id in: path required: true schema: type: string example: 38269301-a7f4-49b4-b9b4-539078fd4a43 - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: returns a success status code '401': description: returns an unauthorized error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: unauthorized detail: You must be authenticated to perform this action '403': description: returns a forbidden error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: forbidden detail: User does not have sufficient permissions for this action. '404': description: returns a not found error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string source: type: object properties: parameter: type: string example: errors: - code: not_found detail: Transaction not found source: parameter: id tags: - Attachments in Transactions description: |- OAuth scope: `attachment.write` --- Remove an attachment from a transaction --- This endpoint allows you to remove a specific attachment from a transaction. Inside Qonto, attachments are files uploaded onto transactions by users. Attachments typically correspond to the *invoice* or *receipt*, and are used to justify the transactions from a bookkeeping standpoint. /v2/internal_transfers: post: summary: Create internal transfer parameters: - name: X-Qonto-Idempotency-Key schema: type: string format: uuid required: true in: header description: The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. example: 219439cf-b519-4d62-86d0-57b6d15ebaa5 - $ref: '#/components/parameters/X-Qonto-Staging-Token' tags: - Internal Transfers description: |- OAuth scope: `internal_transfer.write` --- Instant transfers between accounts of the same organization --- This endpoint allows you to execute transfers between accounts of the same organization. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. The idempotency key must be a unique string. We recommend using a UUID. --- You can obtain details for each organization account using [Show organization](/reference/openapi_v2.yml/paths/~1v2~1organizations~1%7Bid%7D/get) --- ## Request parameter details
##### Amount and Currency * The `amount` corresponds to the amount of the transaction in the `currency` of the bank account. Amounts must be https://www.w3.org/TR/payment-request/#dfn-valid-decimal-monetary-value * The `currency` field only accepts “EUR” * More information: https://www.w3.org/TR/payment-request/#paymentcurrencyamount-dictionary
##### Reference * Transfer reference that can be used to enter transfer details to further describe the transfer * Maximum `reference` length is `99` characters
##### Side * `credit_iban`: IBAN of account to credit * `debit_iban`: IBAN of account to debit security: - OAuth: - internal_transfer.write - SecretKey: [] requestBody: content: application/json: schema: type: object properties: internal_transfer: type: object required: - debit_iban - credit_iban - reference - amount - currency properties: debit_iban: type: string credit_iban: type: string reference: type: string amount: type: string currency: type: string required: - internal_transfer example: internal_transfer: debit_iban: IT12M3609201600032486198434 credit_iban: IT13M3609201600032486198435 reference: Internal transfer amount: '12345.67' currency: EUR responses: '200': description: returns a success status code content: application/json: schema: type: object properties: internal_transfer: type: object description: '' properties: id: type: string description: Transfer ID slug: type: string description: Transfer slug status: type: string description: Transfer status (always pending) amount: type: string description: Transfer amount amount_cents: type: string description: Transfer amount in cents currency: type: string description: Transfer currency (EUR only) reference: type: string description: Transfer reference created_at: type: string description: Transfer creation time example: internal_transfer: id: 0ded2767-f44d-48b4-9e98-b8b6d9359c07 slug: yottanet-6666-1-transfer-52 status: pending amount: '12345.67' amount_cents: '1234567' currency: EUR reference: Internal transfer created_at: '2021-05-11T10:22:55.090Z' '400': description: returns a bad request error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string source: type: object properties: pointer: type: string example: errors: - code: insufficient_funds detail: Insufficient funds source: pointer: /amount '401': description: returns an unauthorized error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: unauthorized detail: You must be authenticated to perform this action '403': description: returns a forbidden error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: forbidden detail: User does not have sufficient permissions for this action. x-internal: false /v2/requests: get: summary: List requests operationId: list_requests parameters: - name: status in: query schema: type: array items: type: string enum: - pending - approved - canceled - declined - name: request_type in: query schema: type: array items: type: string enum: - transfer - multi_transfer - flash_card - virtual_card - name: created_at_from in: query schema: type: string format: date-time example: '2019-01-10T11:47:53.123Z' - name: processed_at_from in: query schema: type: string format: date-time example: '2019-01-10T11:47:53.123Z' - name: sort_by in: query schema: type: string enum: - 'created_at:asc' - 'created_at:desc' - 'processed_at:asc' - 'processed_at:desc' - 'status:asc' - 'status:desc' - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: lists requests for a given organization content: application/json: schema: type: object required: - requests - meta properties: requests: type: array items: oneOf: - $ref: '#/components/schemas/RequestFlashCard' - $ref: '#/components/schemas/RequestVirtualCard' - $ref: '#/components/schemas/RequestMultiTransfer' - $ref: '#/components/schemas/RequestTransfer' meta: $ref: '#/components/schemas/Pagination' example: meta: current_page: 1 next_page: null prev_page: null total_pages: 1 total_count: 4 per_page: 25 requests: - id: 965b8c57-72fd-4d12-8d85-56874104c81a request_type: virtual_card status: pending initiator_id: cc32875a-a590-44c7-bdc1-0680ae72b0db approver_id: null note: Library subscription declined_note: null payment_monthly_limit: '5.00' currency: EUR processed_at: null created_at: '2021-11-24T10:34:51.706Z' - id: fd6d72c0-557d-4d51-8502-d7ce86cb72ea request_type: flash_card status: canceled initiator_id: dbbb579a-f8a5-41df-8cea-09e040464366 approver_id: null note: Restaurant declined_note: null pre_expires_at: '2022-03-15T22:59:59.999Z' payment_lifespan_limit: '250.00' currency: EUR processed_at: '2021-11-24T10:33:59.965Z' created_at: '2021-11-24T10:33:23.817Z' - id: 68e38bca-064c-4b50-8343-26ce40f617af request_type: multi_transfer status: approved initiator_id: 300d309f-a7e0-4db2-af3b-003ce0a676a4 approver_id: 087a7f4f-d316-4bad-810f-84807634cb9f note: Scheduled multi transfer (for Aug 2022) declined_note: null total_transfers_amount: '25561.80' total_transfers_amount_currency: EUR total_transfers_count: 43 scheduled_date: '2022-08-15' processed_at: '2021-11-24T10:34:51.706Z' created_at: '2021-11-10T12:22:28.790Z' - id: 57d28d6f-3a22-4573-990a-c62d2f7d67f0 request_type: transfer status: declined initiator_id: dbbb579a-f8a5-41df-8cea-09e040464366 approver_id: 788571b5-1aea-4aec-bb7b-366288a4ba68 note: Provider subscription declined_note: This is not in our policy creditor_name: John Doe amount: '30.00' currency: EUR scheduled_date: '2021-10-06' recurrence: monthly last_recurrence_date: null processed_at: '2021-10-06T16:14:28.284Z' created_at: '2021-10-06T16:14:11.673Z' '422': description: Returns errors content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string detail: type: string source: type: object properties: pointer: type: string examples: when created_at_at_from is invalid: value: errors: - code: invalid detail: created_at_from is not a valid date source: properties: pointer: /created_at_from tags: - Requests description: "OAuth scope: `organization.read`\n\n_This endpoint is only accessible by organizations in a Business or Enterprise plan._\n\n---\nRetrieve all requests within an organization.\n\n---\nThe response contains the list of requests linked to the authenticated organization.\nThis allows to include request updates and treatment in any other workflows or tools\nused for the day-to-day work.\n\n---\n\n## Attributes details\n\n#### Request Type\n`request_type` is an array that can take 4 different values:\n- `flash_card`: a flash card is a non-physical card with a budget and a last day of validity.\n The card becomes inactive after the budget is totally spent or the last date of validity is past.\n- `virtual_card`: a virtual card is a non-physical card with a monthly budget.\n Card holder can spend that amount every calendar month. Above that, transactions will be refused.\n- `transfer`: a transfer of money from one Qonto account to another account.\n- `multi_transfer`: several transfers executed at the same time.\n A document can be provided to create a multi-transfer which is composed of many different transfers.\n\n#### Status\n`status` is an array that can take 4 different values:\n\n- `pending`: the request is waiting for a final status.\n- `approved`: the request has been approved by one of the authorized members.\n All admins and owners can approve a request.\n- `declined`: the request has been declined by one of the authorized members.\n All admins and owners can decline a request.\n- `canceled`: the request has been canceled by its initiator.\n\n#### Initiator ID\n`initiator_id`: ID of the membership that initiated the request. When the request is initiated through the API, the initiator is the authenticated membership.\n\n#### Approver ID\n`approver_id:` Identifier of the membership who either approved or declined the request.\nIt matches with the ID of the membership object.\n\n#### Note\n`note`: mandatory note to explain the reason of the request.\nThis is a free format note.\n\n#### Declined note\n`declined_note`: it's a free format field filled in by the membership who declined the request.\n\n#### Dates\n- `created_at`: timestamp of creation of the request.\n Example: `2019-01-10T11:47:53.123Z`.\n- `processed_at`: timestamp of when the request decision is taken.\n Either Approved or Declined by an admin. Or canceled by the requester.\n Example: `2019-01-10T11:47:53.123Z`.\n\n#### Currency\n`currency`: Must be EUR. ISO 4217 formatted.\n\n#### Flash Card\nThe following fields are only present when `request_type = \"flash_card\"`.\n\n- `pre_expires_at`: expiry date has been chosen by the requester during the request creation.\n Expires happen always at midnight.\n Example: `2023-06-17T23:59:59Z`.\n- `payment_lifespan_limit`: maximum amount to be spent with that card in total.\n This amount is in the currency of `currency`.\n Example: `\"1500.00\"`.\n\n#### Virtual Card\nThe following fields are only present when `request_type = virtual_card`.\n\n- `payment_monthly_limit`: maximum amount to be spent with that card in total, per calendar month.\n This amount is in the currency of `currency`.\n Example: `\"1500.00\"`.\n\n#### Transfer\nThe following fields are only present when `request_type = transfer`.\n\n- `amount`: exact amount of the transfer to be approved.\n This amount is in the currency of `currency`.\n Example: `\"1234.56\"`.\n- `recurrence`: when it's not `null`, it means that transfer will be recreated\n on the given frequency until `last_date_recurrence`.\n Can be `null`, or `weekly` or `monthly`.\n- `last_recurrence_date`: limit date of the recurring transfer.\n No transfer happens after this date.\n Example: `2019-01-15`\n- `creditor_name`: full name of the beneficiary of the transfer. Max 140 chars long.\n- `scheduled_date`: Can be set by the requester to send the transfer later and not immediately.\n Can only be set in the future by the requester. Defaults to current date or next banking day.\n Example: `2019-01-15`.\n\n#### Multi-Transfer\nThe following fields are only present when `request_type = multi_transfer`.\n\n- `total_transfers_amount`: sum of all transfers amounts included in the multi-transfer.\n This amount is in the currency of `total_transfers_amount_currency`.\n Example: `\"1234.56\"`\n- `total_transfers_amount_currency`: Must be EUR. ISO 4217 formatted.\n Only Request in EUR are allowed. Allowed values:`EUR`.\n- `total_transfers_count`: number of transfers included in the multi-transfer.\n- `scheduled_date`: Can be set by the requester to send the transfer later and not immediately.\n Can only be set in the future by the requester. Defaults to current date or next banking day.\n Example: `2019-01-15`.\n\n## Filters\n`status`\n\nRequests can be filtered by status. The\_**`status`**\_query parameter accepts an array\nof statuses as value. Here is what statuses correspond to:\n\n- `pending`: a request still waiting for final status.\n- `approved`: a request that has been approved by approver. Final status.\n- `declined`: a request that has been declined by approver. Final status.\n- `canceled`: a request that has been canceled by requester. Final status.\n\nFor example, if you want to retrieve several requests statuses, you can use the following filter: `status[]=approved&status[]=declined&status[]=pending`\n\n**Do note**:\_*If no\_`status`\_is specified, the API will return\_all the requests.*\n
\n
\n\n`request_type`\n\nRequests can be filtered by type. The\_`request_type`\_query parameter accepts an array of\nstatuses as value. Here is what request types correspond to:\n\n- `flash_card`: a flash card is a non-physical card with a budget and a last day of validity.\n The card becomes inactive after the budget is totally spent or the last date of validity is past.\n- `virtual_card`: a virtual card is a non-physical card with a monthly budget.\n Card holder can spend that amount every calendar month. Above that, transactions will be refused.\n- `transfer`: a transfer of money from one Qonto account to another account.\n- `multi_transfer`: several transfers executed at the same time.\n A document can be provided to create a multi-transfer which is composed of many different transfers.\n\n**Do note**:\_*If no `request_type` specified, the API will return\_all the requests.*\n
\n
\n\n`processed_at_from` / `created_at_from`\n\nRequests can be filtered according to both\_`processed_at`\_and\_`created_at`\_fields.\nThis is particularly useful to retrieve only the latest updated requests in your application.\nTwo filters are available:\n\n- `processed_at_from`: minimum value (e.g:\_`2019-01-10T11:47:53.123Z`).\n- `created_at_from`: minimum value (e.g:\_`2019-01-10T11:47:53.123Z`).\n\n**Do note**: *`processed_at_from` / `created_at_from` filters should have a valid date time format (**ISO 8601**\_for instance)*\n\n## Sorting\nRequest list can be sorted by a specific field and order.\nThe\_`sort_by`\_query parameter accepts a string defining these two items with the\_`field:order`\_format.\n\n- `processed_at`: when request was processed.\n Two values are available:\_`asc`\_(ascending) /\_`desc`\_(descending)\n\n- `created_at`: when request was created.\n Two values are available:\_`asc`\_(ascending) /\_`desc`\_(descending)\n\n- `status`: reflects the information about the request status.\n Two values are available:\_`asc`\_(ascending) /\_`desc`\_(descending).\n Sorting by ascending gives a list of request with statuses in the given order: `pending`, `approved`, `declined`, `canceled`.\n\n**Do note**: *Use a combination of field and order to define how to sort the transfer list (e.g\_**`processed_at:asc`**).*\n*By default, requests are sorted by `created_at:desc`.*\n\n## Pagination\nDefault number of items per page is 25. [See Schema here](https://api-doc.qonto.com/docs/business-api/c2NoOjI3NTA2MjA3-pagination).\n" security: - OAuth: - organization.read - SecretKey: [] /v2/requests/flash_cards: post: summary: Create a flash card request tags: - Requests description: | Note: this API is still in beta. Please get in touch with our team to know more: https://getqonto.atlassian.net/servicedesk/customer/portal/5 OAuth scope: `request_cards.write` --- Create a request of flash card that should be approved by a membership with permissions to review requests. --- The response contains the created request. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' requestBody: content: application/json: schema: properties: request_flash_card: properties: note: type: string description: Description of a nature of request. Helps approver to understand the reason of this request. example: Library subscription payment_lifespan_limit: $ref: '#/components/schemas/card_payment_lifespan_limit' pre_expires_at: $ref: '#/components/schemas/card_pre_expires_at' security: - OAuth: - request_cards.write responses: '200': description: OK content: application/json: schema: type: object properties: request_flash_card: $ref: '#/components/schemas/RequestFlashCard' '400': $ref: '#/components/responses/400-Bad-request' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '422': $ref: '#/components/responses/422-Unprocessable-entity' /v2/requests/virtual_cards: post: summary: Create a virtual card request tags: - Requests description: | Note: this API is still in beta. Please get in touch with our team to know more: https://getqonto.atlassian.net/servicedesk/customer/portal/5 OAuth scope: `request_cards.write` --- Create a request of virtual card that should be approved by a membership with permissions to review requests. --- The response contains the created request. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' requestBody: content: application/json: schema: properties: request_virtual_card: properties: note: type: string description: Description of a nature of request. Helps approver to understand the reason of this request. example: Library subscription payment_monthly_limit: $ref: '#/components/schemas/card_payment_monthly_limit' security: - OAuth: - request_cards.write responses: '200': description: OK content: application/json: schema: type: object properties: request_virtual_card: $ref: '#/components/schemas/RequestVirtualCard' '400': $ref: '#/components/responses/400-Bad-request' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '422': $ref: '#/components/responses/422-Unprocessable-entity' /v2/requests/multi_transfers: post: summary: Create multi transfer request tags: - Requests description: | OAuth scope: `request_transfers.write` _This endpoint is accessible by organizations with all plans except Solo Basic._ --- Create a request of multi transfer that should be approved by a membership with permissions to review requests. --- The response contains the created request. parameters: - name: X-Qonto-Idempotency-Key in: header required: true description: The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. The idempotency key must be a unique string. We recommend using a UUID. schema: type: string - $ref: '#/components/parameters/X-Qonto-Staging-Token' requestBody: required: true content: application/json: schema: required: - request_multi_transfer properties: request_multi_transfer: type: object required: - note - transfers properties: note: type: string description: Description of a nature of request. Helps approver to understand the reason of this request. example: Salary of marketing departmenet. Please approve ASAP. transfers: type: array minItems: 1 maxItems: 400 items: type: object required: - amount - currency - credit_iban - credit_account_name - credit_account_currency - reference properties: amount: type: string description: 'Should be decimal with 2 digits after coma, ex: "1", "1.99", "1.1"' example: '2000.50' currency: type: string description: 'ISO 4217 formatted. Can be either the currency of the debit_iban or the currency of the beneficiary. Allowed values: EUR' example: EUR credit_iban: type: string description: International beneficiary Bank Account Identifier (IBAN) of creditor. Must respect ISO 13616. example: FR7630001007941234567890183 credit_account_name: type: string description: Free format for the name of the beneficiary. Limited to 140 chars. maxLength: 140 example: URSSAF credit_account_currency: type: string description: 'ISO 4217 formatted. Can be either the currency of the debit_iban or the currency of the beneficiary. Allowed values: EUR' example: EUR reference: type: string description: Reference of a transfer. Limited to 140 chars. maxLength: 140 example: Invoice 2023-01 attachment_ids: type: array items: type: string description: Array of UUID that are linked to this transfer. Attachment must be uploaded thanks to a dedicated endpoints before the transfer to be done. example: d840f1cb-6adb-48af-9f89-540dcf5ba741 scheduled_date: type: string format: date description: 'Date when all the transfers should be executed. Format: YYYY-MM-DD' example: '2023-03-06' debit_iban: type: string description: International beneficiary Bank Account Identifier (IBAN) of debitor. Must respect ISO 13616. example: FR0807277000000000000000911 security: - OAuth: - request_transfers.write responses: '200': description: Request multi transfer object content: application/json: schema: type: object required: - request_multi_transfer properties: request_multi_transfer: type: object required: - id - request_type - status - initiator_id - note - total_transfers_amount - total_transfers_amount_currency - total_transfers_count - created_at - transfers properties: id: type: string example: bb8f8d1d-5f12-486e-8f8e-90cc2af76038 request_type: type: string example: multi_transfer status: type: string example: pending initiator_id: type: string example: 6b1872e4-08e4-42ec-9c82-b441ec242a9b description: |- ID of the membership that initiated the request.
When the request is initiated through the API, the initiator is the authenticated membership. approver_id: type: string format: nullable note: type: string example: Salary of marketing departmenet. Please approve ASAP declined_note: type: string format: nullable total_transfers_amount: type: string example: '2000.50' total_transfers_amount_currency: type: string example: EUR total_transfers_count: type: integer format: int32 example: 1 scheduled_date: type: string format: date example: '2023-03-06' processed_at: type: string format: nullable created_at: type: string example: '2023-02-16T17:33:38.215Z' transfers: type: array items: type: object required: - id - credit_account_name - amount - currency - reference properties: id: type: string example: d840f1cb-6adb-48af-9f89-540dcf5ba741 credit_account_name: type: string example: URSSAF amount: type: string example: '2000.50' currency: type: string example: EUR reference: type: string example: Invoice 2023-01 example: request_multi_transfer: id: bb8f8d1d-5f12-486e-8f8e-90cc2af76038 request_type: multi_transfer status: pending initiator_id: 6b1872e4-08e4-42ec-9c82-b441ec242a9b approver_id: null note: Salary of marketing departmenet. Please approve ASAP declined_note: null total_transfers_amount: '2000.50' total_transfers_amount_currency: EUR total_transfers_count: 1 scheduled_date: '2023-03-06' processed_at: null created_at: '2023-02-16T17:33:38.215Z' transfers: - id: d840f1cb-6adb-48af-9f89-540dcf5ba741 credit_account_name: URSSAF amount: '2000.50' currency: EUR reference: Invoice 2023-01 '401': description: Unauthorized '403': description: Forbidden '422': description: Validation errors content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code - detail properties: code: type: string description: error code example: invalid_transfers detail: type: string description: Human readable error that explains error_code. example: Iban is not valid source: type: object required: - pointer properties: pointer: type: string description: Precises a field and an item in an array (if applicable) that causes an error example: /request_multi_transfer/transfers/0/credit_iban examples: when transfer's iban is not valid: value: errors: - detail: It looks like the IBAN you entered isn’t valid. Could you verify and try again? code: invalid_transfers source: pointer: /request_multi_transfer/transfers/0/iban when reference exceeds the limit: value: errors: - code: above_max_size detail: reference size cannot be greater than 140 source: pointer: /request_multi_transfer/transfers/0/reference when a required field is missing: value: errors: - code: blank detail: note must be filled source: pointer: /request_multi_transfer/note when currency is not supported: value: errors: - code: not_in_list detail: 'currency must be one of: EUR' source: pointer: /request_multi_transfer/transfers/0/currency '/v2/requests/{request_type}/{id}/approve': post: summary: Approve a request operationId: approve_request security: - OAuth: - request_review.write parameters: - in: path name: id required: true schema: type: string description: UUID of the request to be processed. - in: path name: request_type required: true schema: type: string enum: - flash_cards - virtual_cards - transfers - multi_transfers description: Type of a request to be approved. - in: header name: X-Qonto-Idempotency-Key schema: type: string format: uuid required: true description: The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. example: 219439cf-b519-4d62-86d0-57b6d15ebaa5 - $ref: '#/components/parameters/X-Qonto-Staging-Token' requestBody: required: true content: application/json: schema: type: object properties: debit_iban: type: string format: uuid example: FR7616958000019475096658493 description: 'IBAN of account to debit for transfers or multi_transfers or IBAN of the account to link to the card for flash_cards or virtual_cards. If empty, the main account will be debited or linked.' tags: - Requests description: "OAuth scope: `request_review.write`\n\n**Accessible only using [Strong Customer Authentication](https://api-doc.qonto.com/docs/business-api/ZG9jOjI5MDg3NzA4-strong-customer-authentication)**.\n\n\n>\U0001F4A1 Example of SCA usage: [**Postman visual flow**](https://www.postman.com/qontoteam/workspace/qonto-public-api/flow/6670429eb7bd63003156bd57)\n\n---\n\nThis endpoint allows you to approve a pending request. You can ge the list of all requests via [GET /v2/requests.](https://api-doc.qonto.com/docs/business-api/b3A6Mjk1ODk3MjM-list-requests)\n\nInside Qonto, requests can be listed and approved in the Requests tab.\n\nThe impacted request will change status from `status` = `pending` to `status` = `approved`.\n\n---\n\n**`request_type`**\_can take 4 different values:\n\n- **`flash_cards`**: a flash card is a non-physical card with a budget and a last day of validity. The card becomes inactive after the budget is totally spent or the last date of validity is past.\n- **`virtual_cards`**: a virtual card is a non-physical card with a monthly budget. Card holder can spend that amount every calendar month. Above that, transactions will be refused.\n- **`transfers`**: a transfer of money from one Qonto account to another account.\n- **`multi_transfers`**: several transfers executed at the same time. A document can be provided to create a multi-transfer which is composed of many different transfers." responses: '200': description: returns a success status code content: application/json: schema: type: object properties: request_transfer: type: object oneOf: - $ref: '#/components/schemas/RequestTransfer' - $ref: '#/components/schemas/RequestMultiTransfer' - $ref: '#/components/schemas/RequestFlashCard' - $ref: '#/components/schemas/RequestVirtualCard' discriminator: propertyName: request_type example: request_transfer: id: be160c90-058e-487a-b775-5b5cad3992aa request_type: transfer initiator_id: 8fdb86eb-8e49-4be8-ab60-658b680629af approver_id: null note: personal needs declined_note: null status: approved currency: EUR processed_at: null created_at: '2021-10-11T14:28:28Z' '400': description: returns a bad request error '401': description: returns an unauthorized error '403': description: returns a forbidden error '422': description: returns validation errors content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string detail: type: string source: type: object properties: pointer: type: string examples: when bank account doesn't have enough funds: value: errors: - code: insufficient_funds detail: Chosen bank account doesn't have enough funds source: properties: pointer: /bank_account_id when membership kyc is not accepted: value: errors: - code: kyc_not_accepted detail: Approver kyc is not accepted '428': description: returns SCA precondition required error content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string detail: type: string examples: when SCA approval is required on the paired device: value: errors: - code: sca_required detail: You must enable SCA to perform this action '/v2/requests/{request_type}/{id}/decline': post: summary: Decline a request operationId: decline_request security: - OAuth: - request_review.write parameters: - in: path name: id required: true schema: type: string description: UUID of the request to be processed. - in: path name: request_type required: true schema: type: string enum: - flash_cards - virtual_cards - transfers - multi_transfers description: Type of a request to be declined. - in: header name: X-Qonto-Idempotency-Key schema: type: string format: uuid required: true description: The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. example: 219439cf-b519-4d62-86d0-57b6d15ebaa5 - $ref: '#/components/parameters/X-Qonto-Staging-Token' requestBody: required: true content: application/json: schema: type: object required: - declined_note properties: declined_note: type: string format: text example: Contact your manager please tags: - Requests description: "OAuth scope: `request_review.write`\n\n---\n\nThis endpoint allows you to decline a pending request. You can get the list of all requests via [GET /v2/requests.](https://api-doc.qonto.com/docs/business-api/b3A6Mjk1ODk3MjM-list-requests)\n\nInside Qonto, requests can be listed and declined in the Requests tab.\n\nThe impacted request will change status from `status` = `pending` to `status` = `declined`.\n\n---\n\n**`request_type`**\_can take 4 different values:\n\n- **`flash_cards`**: a flash card is a non-physical card with a budget and a last day of validity. The card becomes inactive after the budget is totally spent or the last date of validity is past.\n- **`virtual_cards`**: a virtual card is a non-physical card with a monthly budget. Card holder can spend that amount every calendar month. Above that, transactions will be refused.\n- **`transfers`**: a transfer of money from one Qonto account to another account.\n- **`multi_transfers`**: several transfers executed at the same time. A document can be provided to create a multi-transfer which is composed of many different transfers.\n\n---" responses: '200': description: returns a success status code content: application/json: schema: type: object properties: request_virtual_card: type: object oneOf: - $ref: '#/components/schemas/RequestTransfer' - $ref: '#/components/schemas/RequestMultiTransfer' - $ref: '#/components/schemas/RequestFlashCard' - $ref: '#/components/schemas/RequestVirtualCard' discriminator: propertyName: request_type example: request_virtual_card: id: be160c90-058e-487a-b775-5b5cad3992aa request_type: virtual_card initiator_id: 8fdb86eb-8e49-4be8-ab60-658b680629af approver_id: null note: personal needs declined_note: Contact your manager please status: declined payment_monthly_limit: '500.00' currency: EUR processed_at: null created_at: '2021-10-11T14:28:28Z' '400': description: returns a bad request error '401': description: returns an unauthorized error '403': description: returns a forbidden error '422': description: returns validation errors content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string detail: type: string source: type: object properties: pointer: type: string examples: when membership kyc is not accepted: value: errors: - code: kyc_not_accepted detail: Approver kyc is not accepted /v2/supplier_invoices: get: summary: Get a list of supplier invoices for an organization operationId: list_supplier_invoices security: - OAuth: - supplier_invoice.read - SecretKey: [] parameters: - schema: type: string example: to_review enum: - to_review - to_pay - pending - scheduled - paid in: query name: 'filter[status]' description: status to filter on - schema: type: integer example: 1 in: query name: page - schema: type: integer example: 25 in: query name: per_page - schema: type: string example: 'name:desc' in: query name: sort_by - schema: type: string example: '2025-07-23T13:35:36Z' in: query name: 'filter[created_at_from]' description: 'RFC3339 format (e.g 2022-01-21T12:01:02Z)' - schema: type: string example: '2026-07-23T13:35:36Z' in: query name: 'filter[created_at_to]' description: 'RFC3339 format (e.g 2022-01-21T12:01:02Z)' - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: returns an array of supplier invoices content: application/json: schema: type: object required: - supplier_invoices properties: supplier_invoices: type: array items: $ref: '#/components/schemas/SupplierInvoice' meta: $ref: '#/components/schemas/Pagination' '400': description: returns errors content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: code: type: string detail: type: string source: type: object properties: parameter: type: string examples: when created_at_from is invalid: value: errors: - code: invalid_time detail: created_at_from is not a valid time. Refer to the documentation for the right format. source: parameter: 'filter[created_at_from]' when created_at_to is invalid: value: errors: - code: invalid_time detail: created_at_to is not a valid time. Refer to the documentation for the right format. source: parameter: 'filter[created_at_to]' when created_at_from is in the future: value: errors: - code: invalid_datetime_range detail: created_at_from must be in the past. source: parameter: 'filter[created_at_from]' '403': description: returns a forbidden error content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: forbidden detail: User does not have sufficient permissions for this action tags: - Supplier Invoices description: | OAuth scope: `supplier_invoice.read` --- **Price plans**: this endpoint is available for all Qonto price plans except Solo basic. List all supplier invoices for an organization --- ## Attributes details ### Initiator `initiator_id` is the member who uploaded the invoice. #### Statuses `status` contains four possible values: - **to_review**: When first uploaded, the invoice lands in this state for review. - **to_pay**: Deprecated: This status will no longer be assigned to **new** supplier-invoices. Any invoices already in the `to_pay` status can be marked as paid or be scheduled for transfer. - **pending**: The invoice is waiting for approval or declining by one of the authorized members (only accessible by organizations in a Business or Enterprise plan). - **scheduled**: The invoice is scheduled to be paid. This status is managed by Qonto as it tracks the updates of the transfer. - **paid**: The invoice is paid. ### Filters #### `status` Supplier invoices can be filter by available status. ### `created_at_from` and `created_at_to` Supplier invoices can be filtered by created date time interval using `created_at_from` and `created_at_to` where: - created_at_from represents the min date. - created_at_to represents the max date. Note that if the created_at_from and created_at_to are not specified in the query parameters, the response will contain all the invoices of that particular organization. ### Sorting Supplier invoices can be sorted by a specific field and order. The `sort_by` query parameter accepts a string defining these two items with the field:order format. #### Field `created_at`, `file_name`, `supplier_name`, `payment_date`, `due_date`, `scheduled_date` and `total_amount` values are available. By default the field used to sort invoices is `created_at:desc` for the `To Review` section and `payment_date:asc` for the `To Pay` and `Processed` `payment_date:desc` #### Order Two values are available : asc (Ascending) / desc (Descending) By default the order used to sort supplier invoices is `desc` ### Pagination Default number of items per page is 1, 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). /v2/supplier_invoices/bulk: post: summary: Create supplier invoices with attachments operationId: bulk_create_supplier_invoices security: - OAuth: - supplier_invoice.write - SecretKey: [] requestBody: content: multipart/form-data: schema: type: object properties: supplier_invoices: type: array items: type: object properties: file: type: string format: binary idempotency_key: type: string required: - file - idempotency_key meta: type: string format: json required: - supplier_invoices examples: example: value: supplier_invoices: - file: path/to/file1.pdf idempotency_key: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 meta: '{"integration_type": "amazon", "connector": "grover"}' description: |- OAuth scope: `supplier_invoice.write` --- You have to specify multipart form data in order to attach the file to the request. When using `curl` it will look like that: ``` curl --location --request POST "http://thirdparty.qonto.com/supplier_invoices/bulk" \ --form "supplier_invoices[][file]=@"/path/to/file1.png"" \ --form "supplier_invoices[][idempotency_key]="4d5418bb-bd0d-4df4-865c-c07afab8bb48"" \ --form "supplier_invoices[][file]=@"/path/to/file2.png"" \ --form "supplier_invoices[][idempotency_key]="4d5418bb-bd0d-4df4-865c-c07afab8bb49"" --form "meta='{\"integration_type\":\"dropbox\",\"connector\":\"grover\"}'" ``` ##### Idempotency_key This is a unique string (we advise to use a `uuid`) that identifies an invoice. This is used by Qonto to prevent performing the same operation twice. responses: '200': description: returns supplier invoices result (there could be failures) content: application/json: schema: type: object required: - supplier_invoices - errors properties: supplier_invoices: type: array items: $ref: '#/components/schemas/SupplierInvoice' errors: type: array items: type: object properties: code: type: string detail: type: string examples: when there are only successes: value: supplier_invoices: - id: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 organization_id: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 file_name: invoice 101/2022.pdf invoice_number: QONTO-JAN-2022 supplier_name: McDonald's description: This is an invoice for Ronald! total_amount: value: '22.10' currency: EUR due_date: '2022-03-01' payment_date: '2022-03-01' scheduled_date: '2022-03-01' status: to_review iban: FR1420041010050500013M02606 initiator_id: 89fq18bb-bd0d-4df4-865c-c07afab882a source_type: email created_at: '2022-03-04T17:58:30+02:00' updated_at: '2022-03-04T17:58:30+02:00' attachment_id: 08c66e1f-dded-4823-8fa3-29bed4d5e873 analyzed_at: '2022-03-04T17:58:30+02:00' deleted_at: '' request_transfer: null meta: {} errors: [] when there is a mix of successes and errors: value: supplier_invoices: - id: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 organization_id: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 file_name: invoice 101/2022.pdf invoice_number: QONTO-JAN-2022 supplier_name: McDonald's description: This is an invoice for Ronald! total_amount: value: '22.10' currency: EUR due_date: '2022-03-01' payment_date: '2022-03-01' scheduled_date: '2022-03-01' status: to_review iban: FR1420041010050500013M02606 initiator_id: 89fq18bb-bd0d-4df4-865c-c07afab882a source_type: email created_at: '2022-03-04T17:58:30+02:00' updated_at: '2022-03-04T17:58:30+02:00' attachment_id: 08c66e1f-dded-4823-8fa3-29bed4d5e873 analyzed_at: '2022-03-04T17:58:30+02:00' deleted_at: '' request_transfer: null errors: - code: invalid detail: File is too large or wrong content type source: - pointer: /supplier_invoices/idempotency_key/abc-xyz/file when there are only errors: value: supplier_invoices: [] errors: - code: invalid detail: File is too large or wrong content type source: - pointer: /supplier_invoices/idempotency_key/abc-xyz/file - code: internal_server_error details: Processing file has failed source: - pointer: /supplier_invoices/idempotency_key/abc-xyz '400': description: returns errors content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: code: type: string detail: type: string examples: when request exists the limit: value: errors: - code: bad_request detail: Request is too large when number of files is reached: value: errors: - code: limit_reached detail: Limit of 5 invoices reached source: pointer: /supplier_invoices when idempotency_key is missing for at least one file: value: errors: - code: required detail: Idempotency key is required source: pointer: /idempotency_key when file is missing for at least one idempotency_key: value: errors: - code: required detail: File is required source: pointer: /file '403': description: returns a forbidden error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: forbidden detail: User does not have sufficient permissions for this action due to pricing plan tags: - Supplier Invoices description: | OAuth scope: `supplier_invoice.write` --- **Price plans**: this endpoint is available for all Qonto price plans. Bulk create supplier invoices with attachments --- This endpoint will always return a 200 regardless if there are any errors. Clients must ensure to check the `errors` property in order to confirm if all operations were successful. A 400 will be returned if whole request fails. Total size of the request cannot exceed 15MB. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' /v2/client_invoices: get: summary: List client invoices operationId: list_client_invoices security: - OAuth: - client_invoices.read - SecretKey: [] parameters: - schema: type: string example: unpaid enum: - draft - unpaid - paid - canceled in: query name: 'filter[status]' - schema: type: string format: date-time example: '2022-02-01T12:01:02Z' in: query name: 'filter[created_at_from]' - schema: type: string format: date-time example: '2022-23-04T16:23:00Z' in: query name: 'filter[created_at_to]' - schema: type: integer example: 1 in: query name: page - schema: type: integer example: 25 in: query name: per_page - schema: type: string example: 'created_at:desc' in: query name: sort_by - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: Returns an array of client invoices. content: application/json: schema: type: object required: - client_invoices properties: client_invoices: type: array items: $ref: '#/components/schemas/ClientInvoice' meta: $ref: '#/components/schemas/Pagination' examples: {} '400': $ref: '#/components/responses/400-Bad-request' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' tags: - Client Invoices description: | OAuth scope: `client_invoices.read` --- Retrieves all client invoices for the authenticated organization. --- ## Filtering - Invoices can be filtered by `status`. Note that the status can contain four possible values: - `draft` the invoice was created but not validated. The invoice still needs to be validated to be paid. - `unpaid` the invoice was created and validated. The invoice is ready to be paid. - `canceled` the invoice was created but canceled by the initiator.The invoice it is not ready to be paid. - `paid` the invoice was created, forwarded to the client, and successfully paid. - Note that if the status is not specified in the query parameters, the response will contain invoices with all four mentioned statuses. - Invoices can be filtered by created date time interval using `created_at_from` and `created_at_to` where: - `created_at_from` represents the min date - `created_at_to` represents the max date - Note that if the `created_at_from` and `created_at_to` are not specified in the query parameters, the response will contain all the invoices of that particular organization. ## Sorting - Invoices can be sorted by `created_at` - Two values are available: `asc` (Ascending) / `desc` (Descending) - By default, the order used to sort `created_at` is `desc` ## Pagination - The default number of items per page is 1, 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). post: summary: Create a client invoice operationId: create_client_invoice tags: - Client Invoices security: - OAuth: - client_invoice.write - SecretKey: [] description: |- OAuth scope: `client_invoice.write` --- Creates a single client invoice for the authenticated organization. See further details below. --- **Price plans**: this endpoint is available for all Qonto price plans. --- The required request attributes are outlined inside Schemas / ClientInvoiceCreatePayload. The response contains the attributes of the client invoice entered in the request, along with additional fields that are computed by Qonto, including the associated invoice id. --- When creating an invoice, note that the invoice "inherits" the currency of the provided client. If the `currency` is not set for that client, you will receive a validation error on the `/data/attributes/currency` field. --- Italian organizations must have e-invoicing activated on the Qonto app in order to use this endpoint. --- requestBody: content: application/json: schema: $ref: '#/components/schemas/ClientInvoiceCreatePayload' responses: '200': description: Returns the newly created client invoice. content: application/json: schema: type: object required: - client_invoice properties: client_invoice: $ref: '#/components/schemas/ClientInvoice' '400': description: Returns a bad request error. content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '401': description: Returns an unauthorized error. content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '403': description: Returns a forbidden error. content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '422': description: Returns an unprocessable entity error. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string detail: type: string source: type: object properties: pointer: type: string '500': description: Returns an internal server error. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: unknown detail: An unknown error occurred parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' '/v2/client_invoices/{id}': get: summary: Show client invoice operationId: get_client_invoice security: - OAuth: - client_invoices.read - SecretKey: [] parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: Returns the client invoice (identified by the id specified in the URL). content: application/json: schema: type: object required: - client_invoice properties: client_invoice: $ref: '#/components/schemas/ClientInvoice' examples: {} '400': $ref: '#/components/responses/400-Bad-request' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '422': $ref: '#/components/responses/422-Unprocessable-entity' tags: - Client Invoices description: |- OAuth scope: `client_invoices.read` --- Retrieves a single client invoice. x-internal: false x-stoplight: id: copd6wc7nwym8 parameters: - schema: type: string example: e3d68a1a-b23f-496a-a9a2-815089337720 format: uuid name: id in: path description: UUID of the client invoice to retrieve. required: true /v2/credit_notes: get: summary: Get a list of credit notes for an organization operationId: list_credit_notes security: - OAuth: - client_invoices.read - SecretKey: [] parameters: - schema: type: string format: date-time example: '2022-02-01T12:01:02Z' in: query name: 'filter[created_at_from]' - schema: type: string format: date-time example: '2022-23-04T16:23:00Z' in: query name: 'filter[created_at_to]' - schema: type: integer example: 1 in: query name: page - schema: type: integer example: 25 in: query name: per_page - schema: type: string example: 'created_at:desc' in: query name: sort_by - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: returns an array of credit notes content: application/json: schema: type: object required: - credit_notes properties: credit_notes: type: array items: $ref: '#/components/schemas/CreditNote' meta: $ref: '#/components/schemas/Pagination' '403': description: returns a forbidden error content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: forbidden detail: User does not have sufficient permissions for this action '422': description: returns an unprocessable entity error content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string detail: type: string source: type: object properties: pointer: type: string '500': description: returns an internal server error content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: unknown detail: An unknown error occurred tags: - Credit Notes description: | OAuth scope: `client_invoices.read` --- Retrieve all credit notes within a particular Organization. --- The response contains the list of the credit notes and all the related data and attachments. --- ## Attributes details ### Credit Note - `total_amount` and `total_amount_cents` represent the credit note’s total amount - `vat_amount` and `vat_amount_cents` represent the credit note VAT amount - `currency` represents the credit note’s currency - `contact_email` represents the e-mail address of the credit note’s initiator - `credit_note_url` represents the URL credit note through which the credit note can be previewed in the web browser - `number` represents the credit note’s number - `terms_and_conditions` represents the T&C data added by the credit note’s initiator - `header` represents the header text added by the credit note’s initiator - `footer` represents the footer text added by the credit note’s initiator - `invoice_id` represents the invoice id the credit note is linked to - `attachment_id` represents an attachment UUID corresponding to that particular credit note. You can obtain details and get the credit note by using [Get attachment](https://api-doc.qonto.com/docs/business-api/345dace7b485b-show-attachment) - `reason` represents the reason for credit note ### Items - `total_amount` and `total_amount_cents` represent the amount for that specific item - `total_vat` and `total_vat_cents` represent the VAT amount that is applicable for that specific item - `title` represents the item’s title - `description` represents the item’s description - `quantity` represents the item’s quantity - `unit_price` and `unit_price_cents` represent the amount of the price per unit. Note that an item can contain multiple units. The number of units is defined via `quantity`. - `vat_rate` represents the VAT rate applicable for that particular item ### Client - `type` describes the client type. Possible values - company or individual - `email` represents the e-mail address of the client - `address` represents the address of the client - `city` represents the city of the client - `zip_code` represents the zip code of the client - `country_code` represents the country code of the client - `name` represents the name of the client. Note that this attribute will be returned only if the client is `a company` - `first_name` represents the first name of the client. Note that this attribute will be returned only if the client is `an individual` - `last_name` represents the last name of the client. Note that this attribute will be returned only if the client is `an individual` - `tax_identification_number` represents the TAX Identification number of the client - `vat_number` represents the VAT number of the client - `billing_address` 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`). - `delivery_address` 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`). ### Organization - `id` represents the unique identifier of organization - `legal_name` represents the organization's legal name at the time the document was issued - `legal_number` represents the organization's legal number at the time the document was issued - `legal_country` represents the organization's legal country at the time the document was issued - `address_line_1` represents the first line of the organization's address at the time the document was issued - `address_line_2` represents the second line of the organization's address at the time the document was issued - `address_zipcode` represents the organization's zip code at the time the document was issued - `address_city` represents the organization's city at the time the document was issued - `address_country` represents the country of the organization's address at the time the document was issued - `company_leadership` represents the organization's leadership at the time the document was issued - `district_court` represents the organization's district court at the time the document was issued - `commercial_register_number` is available for French and German organizations and is optional. For French organizations, it represents RCS number (numéro Registre du Commerce et des Sociétés) of an incorporated business. For example: RCS A 123 123 123. For German organizations, it represents the organization's commercial register number (handelsregisternummer). For example: HRB 123455 B. - `vat_number` represents the organization's VAT number at the time the document was issued - `tax_number` represents the organization's tax number at the time the document was issued - `legal_capital_share` represents the capital share of an incorporated business. It is optional and is only for French organizations. It is by default in EUR. - `transaction_type` represents the type of transaction performed in the invoice. It is optional and is only for French organizations. Allowed values: `goods`, `services`, `goods_and_services` - `vat_payment_condition` represents the business’ VAT elected payment condition (whether TVA is paid on receipt or on invoice emission). There are two allowed values: receipt and compensated_for_sales. receipt stands for “sur les encaissements” in French, and compensated_for_sales stands for “sur les débits” in French. It is optional and is only for French organizations. Allowed values: `receipt`, `compensated_for_sales` ### Timestamps - `created_at` represents the date the credit note was created. Note that this is a machine date. - `issue_date` represents the date the initiator mentioned that the credit note was created. - `invoice_issue_date` represents the invoice_id’s issue date ## Filtering - Credit notes can be filtered by created date time interval using `created_at_from` and `created_at_to` where: - `created_at_from` represents the min date - `created_at_to` represents the max date - Note that if the `created_at_from` and `created_at_to` are not specified in the query parameters, the response will contain all the credit notes of that particular organization. ## Sorting - Credit notes can be sorted by `created_at` - Two values are available: `asc` (Ascending) / `desc` (Descending) - By default, the order used to sort `created_at` is `desc` ## Pagination - The default number of items per page is 1, 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). '/v2/credit_notes/{id}': get: summary: Get details of credit note for an organization operationId: get_credit_note security: - OAuth: - client_invoices.read - SecretKey: [] parameters: - name: id in: path description: ID of the credit note required: true schema: type: string format: uuid - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: Credit note info content: application/json: schema: type: object required: - credit_note properties: credit_note: $ref: '#/components/schemas/CreditNote' '400': description: returns a bad request error content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: bad request detail: invalid json '404': description: returns a not found error content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: not found detail: credit note not found '422': description: returns an unprocessable entity error content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string detail: type: string source: type: object properties: pointer: type: string '500': description: returns an internal server error content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: code: type: string detail: type: string example: errors: - code: unknown detail: An unknown error occurred tags: - Credit Notes description: | OAuth scope: `client_invoices.read` --- Retrieve details about a credit note within a particular Organization. --- The response contains the details of a credit note and all the related data and attachments. --- ## Attributes details ### Credit Note - `total_amount` and `total_amount_cents` represent the credit note’s total amount - `vat_amount` and `vat_amount_cents` represent the credit note VAT amount - `currency` represents the credit note’s currency - `contact_email` represents the e-mail address of the credit note’s initiator - `credit_note_url` represents the URL credit note through which the credit note can be previewed in the web browser - `number` represents the credit note’s number - `terms_and_conditions` represents the T&C data added by the credit note’s initiator - `header` represents the header text added by the credit note’s initiator - `footer` represents the footer text added by the credit note’s initiator - `invoice_id` represents the invoice id the credit note is linked to - `attachment_id` represents an attachment UUID corresponding to that particular credit note. You can obtain details and get the credit note by using [Get attachment](https://api-doc.qonto.com/docs/business-api/345dace7b485b-show-attachment) - `reason` represents the reason for credit note ### Items - `total_amount` and `total_amount_cents` represent the amount for that specific item - `total_vat` and `total_vat_cents` represent the VAT amount that is applicable for that specific item - `title` represents the item’s title - `description` represents the item’s description - `quantity` represents the item’s quantity - `unit_price` and `unit_price_cents` represent the amount of the price per unit. Note that an item can contain multiple units. The number of units is defined via `quantity`. - `vat_rate` represents the VAT rate applicable for that particular item ### Client - `type` describes the client type. Possible values - company or individual - `email` represents the e-mail address of the client - `address` represents the address of the client - `city` represents the city of the client - `zip_code` represents the zip code of the client - `country_code` represents the country code of the client - `name` represents the name of the client. Note that this attribute will be returned only if the client is `a company` - `first_name` represents the first name of the client. Note that this attribute will be returned only if the client is `an individual` - `last_name` represents the last name of the client. Note that this attribute will be returned only if the client is `an individual` - `tax_identification_number` represents the TAX Identification number of the client - `vat_number` represents the VAT number of the client - `billing_address` 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`). - `delivery_address` 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`). ### Organization - `id` represents the unique identifier of organization - `legal_name` represents the organization's legal name at the time the document was issued - `legal_number` represents the organization's legal number at the time the document was issued - `legal_country` represents the organization's legal country at the time the document was issued - `address_line_1` represents the first line of the organization's address at the time the document was issued - `address_line_2` represents the second line of the organization's address at the time the document was issued - `address_zipcode` represents the organization's zip code at the time the document was issued - `address_city` represents the organization's city at the time the document was issued - `address_country` represents the country of the organization's address at the time the document was issued - `company_leadership` represents the organization's leadership at the time the document was issued - `district_court` represents the organization's district court at the time the document was issued - `commercial_register_number` is available for French and German organizations and is optional. For French organizations, it represents RCS number (numéro Registre du Commerce et des Sociétés) of an incorporated business. For example: RCS A 123 123 123. For German organizations, it represents the organization's commercial register number (handelsregisternummer). For example: HRB 123455 B. - `vat_number` represents the organization's VAT number at the time the document was issued - `tax_number` represents the organization's tax number at the time the document was issued - `legal_capital_share` represents the capital share of an incorporated business. It is optional and is only for French organizations. It is by default in EUR. - `transaction_type` represents the type of transaction performed in the invoice. It is optional and is only for French organizations. Allowed values: `goods`, `services`, `goods_and_services` - `vat_payment_condition` represents the business’ VAT elected payment condition (whether TVA is paid on receipt or on invoice emission). There are two allowed values: receipt and compensated_for_sales. receipt stands for “sur les encaissements” in French, and compensated_for_sales stands for “sur les débits” in French. It is optional and is only for French organizations. Allowed values: `receipt`, `compensated_for_sales` ### Timestamps - `created_at` represents the date the credit note was created. Note that this is a machine date. - `issue_date` represents the date the initiator mentioned that the credit note was created. - `invoice_issue_date` represents the invoice_id’s issue date '/v2/clients/{id}': get: summary: Get client's details security: - OAuth: - client.read - SecretKey: [] parameters: - name: id in: path description: ID of the client required: true schema: type: string format: uuid - $ref: '#/components/parameters/X-Qonto-Staging-Token' tags: - Clients description: |- OAuth scope: `client.read` --- Get information about a client that constitutes the addressee of client invoices for a particular organization by client id. See further details below. --- Price plans: this endpoint is available for all Qonto price plans --- The response contains the attributes of the client entered in the request, along with additional fields that are computed by Qonto, including the associated client id. responses: '200': description: Retrieve details about a client content: application/json: schema: type: object required: - client properties: client: $ref: '#/components/schemas/Client' '400': description: Bad request error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '401': description: Unauthorized error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '403': description: Forbidden error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '422': description: Unprocessable content Error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' /v2/clients: get: summary: Get a list of clients security: - OAuth: - client.read - SecretKey: [] parameters: - name: filter description: | Attributes to filter by. in: query schema: type: object enum: - 'filter[tax_identification_number]' - 'filter[vat_number]' - 'filter[email]' - 'filter[name]' style: deepObject explode: true - name: page schema: type: integer example: 25 in: query - name: per_page schema: type: integer example: 25 in: query - name: sort_by schema: type: string example: 'created_at:desc' enum: - 'created_at:asc' - 'created_at:desc' - 'name:asc' - 'name:desc' in: query - $ref: '#/components/parameters/X-Qonto-Staging-Token' tags: - Clients description: |- 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). responses: '200': description: 'A list of clients, paginated' content: application/json: schema: type: object properties: clients: type: array items: $ref: '#/components/schemas/Client' meta: $ref: '#/components/schemas/Pagination' '400': description: Bad request error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '401': description: Unauthorized error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '403': description: Forbidden error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '422': description: Unprocessable content Error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' post: summary: Create a client security: - OAuth: - client.write - SecretKey: [] tags: - Clients description: | 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. > 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. requestBody: content: application/json: schema: $ref: '#/components/schemas/ClientCreatePayload' required: true responses: '200': description: The created client content: application/json: schema: type: object required: - client properties: client: $ref: '#/components/schemas/Client' '400': description: Bad request error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '401': description: Unauthorized error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '403': description: Forbidden error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '422': description: Unprocessable content Error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' /v2/teams: get: summary: List teams in an organization security: - OAuth: - team.read parameters: - schema: type: integer example: 1 in: query name: page - schema: type: integer example: 25 in: query name: per_page - $ref: '#/components/parameters/X-Qonto-Staging-Token' responses: '200': description: the response contains a list of all teams in the authenticated organization. content: application/json: schema: type: object properties: teams: type: array items: type: object properties: id: type: string format: uuid description: unique identifier of each team in the organization name: type: string example: super team description: name of each team in the organization meta: $ref: '#/components/schemas/Pagination' '401': description: returns an unauthorized error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string example: unauthorized detail: type: string example: Invalid credentials '403': description: returns a forbidden error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string example: forbidden detail: type: string example: Forbidden tags: - Teams description: |- OAuth scope: `team.read` --- Get a list with all teams within the authenticated organization --- A successful response will give a list with the attributes id and name of each team in the organization: ## Pagination - The default number of items per page is 1, 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). post: summary: Create a new team security: - OAuth: - team.write requestBody: content: application/json: schema: type: object required: - name properties: name: type: string description: name for the new team being created responses: '201': description: returns created team content: application/json: schema: type: object properties: team: type: object properties: id: type: string format: uuid description: unique identifier of the newly created team name: type: string example: super team description: name of the newly created team '401': description: returns an unauthorized error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string example: unauthorized detail: type: string example: Invalid credentials '403': description: returns a forbidden error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string example: forbidden detail: type: string example: Forbidden '422': description: returns an unprocessable entity error content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object required: - code properties: code: type: string example: invalid_string_size_range detail: type: string example: name length must be within 2 - 100 source: type: object properties: pointer: type: string example: /name tags: - Teams description: |- OAuth scope: `team.write` --- Create a new team in the authenticated organization. --- A successful response will give name and id of the newly created team. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' '/v2/statements/{id}': parameters: - schema: type: string example: 08544790-6305-4a85-8487-e035290bcee8 name: id in: path required: true description: Unique identifier of the statement. get: summary: Show statement responses: '200': description: Returns the statement. content: application/json: schema: type: object properties: statement: $ref: '#/components/schemas/Statement' examples: Example 1: value: statement: id: 08544790-6305-4a85-8487-e035290bcee8 bank_account_id: 9f4af770-344b-42c1-a592-6a2adf82a6d3 period: 08-2024 file: file_name: string file_content_type: application/pdf file_size: '16966' file_url: string '404': description: Returns a not found error. content: application/json: schema: type: object properties: errors: type: array x-stoplight: id: upg3lxzrivbka items: x-stoplight: id: 0jcm4m2po4s0n type: object properties: code: type: string x-stoplight: id: s3cn18k1bwirt example: not_found detail: type: string x-stoplight: id: 9rh6xucyp625m example: statement not found source: type: object x-stoplight: id: qx5cgux53dka6 properties: parameter: type: string x-stoplight: id: s3o2yamhjprsr example: id examples: Example 1: value: errors: - code: not_found detail: statement not found source: parameter: id operationId: get_statement x-stoplight: id: qcqb719o8naof description: | OAuth scope: `organization.read` --- Retrieves a single statement. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' tags: - Statements x-internal: false security: - OAuth: - organization.read - SecretKey: [] /v2/statements: get: summary: List statements tags: - Statements responses: '200': description: Returns the list of statements of the authentified organization. content: application/json: schema: type: object properties: statements: x-stoplight: id: z4t1gvwzljito type: array items: $ref: '#/components/schemas/Statement' meta: $ref: '#/components/schemas/Pagination' '422': description: Returns errors. content: application/json: schema: type: object properties: errors: x-stoplight: id: 709wra8cmlcze type: array items: x-stoplight: id: l45i940g8phaj type: object properties: code: type: string x-stoplight: id: hy5vwd00yon05 detail: type: string x-stoplight: id: vb5d5c4dccfwq source: type: object x-stoplight: id: 1rttt2192q1xl properties: pointer: type: string x-stoplight: id: qo246qf1jpj7w examples: Example 1: value: errors: - code: invalid_filters_params detail: cannot filter by both ibans and bank_account_ids source: pointer: / operationId: get_statements x-stoplight: id: uq4c3e2ml7q7g description: | OAuth scope: `organization.read` --- Retrieves the list of statements for the authenticated organization. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' - schema: type: array example: 'bank_account_ids[]=3591c988-8a98-4592-9665-0d9a55a5bf34&bank_account_ids[]=b71ec2ad-bd18-4a02-be4c-ba7b5e8d621f' in: query name: 'bank_account_ids[]' description: Statements can be filtered by their `bank_account_id`.
⚠️ `ibans` and `bank_account_ids` are mutually exclusive and cannot be used together. - schema: type: array example: 'ibans[]=IT56O3609201600026403832768&ibans[]=IT31U3609201600955642496269' in: query name: 'ibans[]' description: Statements can be filtered by their `iban`.
⚠️ `ibans` and `bank_account_ids` are mutually exclusive and cannot be used together. - schema: type: string example: 01-2023 in: query name: period_from description: 'Statements can be filtered by their `period`. This filter is the beginning of the desired statement period (included). ' - schema: type: string example: 12-2023 in: query name: period_to description: 'Statements can be filtered by their `period`. This filter is the end of the desired statement period (included). ' - schema: type: integer default: 1 example: 2 in: query name: page description: 'cf. https://api-doc.qonto.com/docs/business-api/05ccf93502e54-pagination' - schema: type: integer maximum: 100 default: 100 example: 20 in: query name: per_page description: 'cf. https://api-doc.qonto.com/docs/business-api/05ccf93502e54-pagination' - schema: type: string example: 'period:asc' default: 'period:desc' in: query name: sort_by description: 'Statements can be sorted by their `period` in 2 possible directions: `asc` (Ascending) / `desc` (Descending).' x-internal: false security: - OAuth: - organization.read - SecretKey: [] /v2/insurance_contracts: post: summary: Create a new insurance contract x-internal: false security: - OAuth: - insurance_contract.write tags: - Insurance Contracts description: |- OAuth scope: `insurance_contract.write` --- This endpoint allows you to create a new insurance contract for the authenticated organization. It supports various types of insurance contracts, and includes critical information, such as the policy provider, pricing, and current status. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' requestBody: description: Insurance contract to create required: true content: application/json: schema: $ref: '#/components/schemas/InsuranceContractCreatePayload' responses: '201': description: Returns an insurance contract content: application/json: schema: $ref: '#/components/schemas/InsuranceContract' '400': description: Returns a bad request error content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Returns an unauthorized error content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: Returns a forbidden error content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '/v2/insurance_contracts/{id}': get: summary: Get insurance contract x-internal: false security: - OAuth: - insurance_contract.read tags: - Insurance Contracts description: |- OAuth scope: `insurance_contract.read` --- This endpoint allows you to retrieve a insurance contract by its ID. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' - name: id in: path required: true schema: type: string description: UUID of the insurance contract responses: '200': description: Returns insurance contract content: application/json: schema: $ref: '#/components/schemas/InsuranceContractWithDocuments' '400': description: Returns a bad request error content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Returns an unauthorized error content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: Returns a forbidden error content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: Returns a not found error content: application/json: schema: $ref: '#/components/schemas/NotFoundError' patch: summary: Update an insurance contract x-internal: false security: - OAuth: - insurance_contract.write tags: - Insurance Contracts description: |- OAuth scope: `insurance_contract.write` --- This endpoint allows you to update an existing insurance contract by its ID. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' - name: id in: path required: true schema: type: string description: UUID of the insurance contract to update requestBody: description: JSON payload containing fields to update required: true content: application/json: schema: $ref: '#/components/schemas/InsuranceContractUpdatePayload' responses: '200': description: Returns insurance contract updated content: application/json: schema: $ref: '#/components/schemas/InsuranceContract' '400': description: Returns a bad request error content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Returns an unauthorized error content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: Returns a forbidden error content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: Returns a not found error content: application/json: schema: $ref: '#/components/schemas/NotFoundError' '/v2/insurance_contracts/{id}/attachments': post: summary: Upload a PDF document for a specific insurance contract x-internal: false security: - OAuth: - insurance_contract.write tags: - Insurance Contracts description: |- OAuth scope: `insurance_contract.write` --- This endpoint allows you to upload a PDF file representing a document for a specific insurance contract. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' - name: id in: path required: true schema: type: string description: UUID of the insurance you are uploading the document for - name: X-Qonto-Idempotency-Key in: header required: true schema: type: string description: A unique key to ensure that the same request is not processed multiple times requestBody: description: PDF file representing the document required: true content: multipart/form-data: schema: type: object required: - file - name - type properties: file: type: string format: binary description: The PDF file to upload name: type: string format: string example: Contract Axa description: the name of the file type: type: string format: string example: contract description: 'type of the file, for example - contract, statement' responses: '201': description: Attachment created successfully content: application/json: schema: type: object properties: id: type: string format: uuid description: ID of the newly created attachment example: 123e4567-e89b-12d3-a456-426614174000 name: type: string format: string example: Contract Axa description: the name of the file type: type: string format: string example: contract description: type of the file '400': description: Returns a bad request error content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Returns an unauthorized error content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: Returns a forbidden error content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: Returns a not found error content: application/json: schema: $ref: '#/components/schemas/NotFoundError' '/v2/insurance_contracts/{id}/attachments/{attachment_id}': delete: summary: Delete uploaded document x-internal: false security: - OAuth: - insurance_contract.write tags: - Insurance Contracts description: |- OAuth scope: `insurance_contract.write` --- This endpoint allows you to delete a previously uploaded document from a insurance contract. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' - name: id in: path required: true schema: type: string description: UUID of the insurance you are uploading the document for - name: attachment_id in: path required: true schema: type: string description: UUID of the attachment you are deleting responses: '204': description: Attachment deleted successfully '400': description: Returns a bad request error content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Returns an unauthorized error content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: Returns a forbidden error content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: Returns a not found error content: application/json: schema: $ref: '#/components/schemas/NotFoundError' /v2/cards: get: summary: List cards x-internal: false security: - OAuth: - card.read tags: - Cards description: |- Note: this API is still in beta. Please get in touch with our team to know more: https://getqonto.atlassian.net/servicedesk/customer/portal/5 OAuth scope: `card.read` --- This endpoint allows you to retrieve the list of cards that can be viewed by the currently-authenticated membership. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' - schema: type: string in: query name: query description: |- Text search can be performed on the following fields: - memberships.first_name - memberships.last_name - cards.id - cards.nickname - cards.last_digits - cards.status - cards.pre_expires_at - cards.exp_year - cards.exp_month - schema: type: integer default: 1 example: 2 in: query name: page description: 'cf. https://api-doc.qonto.com/docs/business-api/05ccf93502e54-pagination' - schema: type: integer maximum: 100 default: 100 example: 20 in: query name: per_page description: 'cf. https://api-doc.qonto.com/docs/business-api/05ccf93502e54-pagination' - schema: type: string example: 'status:asc' default: 'status:asc' in: query name: sort_by description: 'Cards can be sorted by attributes (`status`, `nickname`, `last_activity_at`, `created_at`) in 2 possible directions: `asc` (Ascending) / `desc` (Descending).' - schema: type: array items: $ref: '#/components/schemas/card_holder_id' in: query name: 'holder_ids[]' description: Cards can be filtered by cardholder membership ID. - schema: type: array items: $ref: '#/components/schemas/card_status' in: query name: 'statuses[]' description: 'Cards can be filtered by statuses. Multiple statuses can be specified (e.g. `statuses[]=pending&statuses[]=live`).' - schema: type: array items: $ref: '#/components/schemas/card_bank_account_id' in: query name: 'bank_account_ids[]' description: 'Cards can be filtered by bank account ID. Multiple bank accounts can be specified (e.g. `bank_account_ids[]=id1&bank_account_ids[]=id2`).' - schema: type: array items: $ref: '#/components/schemas/card_level' in: query name: 'card_levels[]' description: 'Cards can be filtered by card level. Multiple card levels can be specified (e.g. `card_levels[]=virtual&card_levels[]=flash`).' - schema: type: array items: $ref: '#/components/schemas/card_id' in: query name: 'ids[]' description: 'Cards can be filtered by card ID. Multiple card IDs can be specified (e.g. `ids[]=id1&ids[]=id2`).' responses: '200': description: OK content: application/json: schema: type: object properties: meta: $ref: '#/components/schemas/Pagination' cards: type: array items: $ref: '#/components/schemas/CardPayload' '400': description: Invalid payload content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' post: summary: Create a new card x-internal: false security: - OAuth: - card.write tags: - Cards description: |- Note: this API is still in beta. Please get in touch with our team to know more: https://getqonto.atlassian.net/servicedesk/customer/portal/5 OAuth scope: `card.write` --- This endpoint allows you to create a new card. parameters: - name: X-Qonto-Idempotency-Key schema: type: string required: true in: header description: This parameter is required. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. The idempotency key must be a unique string. We recommend using a UUID. - $ref: '#/components/parameters/X-Qonto-Staging-Token' requestBody: content: application/json: schema: oneOf: - $ref: '#/components/schemas/CreatePhysicalCard' - $ref: '#/components/schemas/CreateVirtualCard' - $ref: '#/components/schemas/CreateFlashCard' - $ref: '#/components/schemas/CreateAdvertisingCard' responses: '200': description: OK content: application/json: schema: type: object properties: card: $ref: '#/components/schemas/CardPayload' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' examples: 'when organisation is not on Team price plan and category_tags param is provided with non-empty value. Empty means `[]`.': description: 'when organisation is not on Team price plan and category_tags param is provided with non-empty value. Empty means `[]`.' value: message: Forbidden when user's role is not authorized to create a card: description: when user's role is not authorized to create a card value: message: Forbidden when try to create an online advertising card on a price plan that doesn't support it: description: when try to create an online advertising card on a price plan that doesn't support it value: message: Forbidden '422': description: | Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityError' examples: when category_tags and active_days are missing: description: When category_tags and active_days are missing value: errors: - code: parameter_missing detail: 'param is missing or the value is empty: card' source: pointer: /card when wrong category_tags are provided: description: When wrong category_tags are provided value: errors: - code: invalid detail: is invalid source: pointer: /data/attributes/category_tags when too many category_tags are provided: description: When too many category_tags are provided value: errors: - code: invalid detail: is invalid source: pointer: /data/attributes/category_tags 'when set category_tags non-empty values on flash card. Empty means `[]`.': description: 'when set category_tags non-empty values on flash card. Empty means `[]`.' value: errors: - code: present detail: must be blank source: pointer: /data/attributes/category_tags when membership is revoked: description: when membership is revoked value: errors: - code: invalid_card_holder_status detail: cannot create a card for a revoked membership when the card holder has exceeded the hourly card creation limit: description: when the card holder has exceeded the hourly card creation limit value: errors: - code: too_many_digital_cards_for_holder_recently detail: Card holder has created too many digital cards recently message: too many digital cards for holder recently when the holder has reached the maximum number of digital cards allowed: description: when the holder has reached the maximum number of digital cards allowed value: errors: - code: too_many_digital_cards_for_holder detail: Card holder has created too many digital cards message: too many digital cards for holder '/v2/cards/{id}/data_view': get: summary: Retrieve card data view URL x-internal: false security: - OAuth: - card.read tags: - Cards description: |- Note: this API is still in beta. Please get in touch with our team to know more: https://getqonto.atlassian.net/servicedesk/customer/portal/5 OAuth scope: `card.read` --- This endpoint allows you to retrieve the URL to be displayed in an iframe to view the card preview with its details. Note that HTML encoding is applied to the URL, replacing &, <, and > with \u0026, \u003c, and \u003e respectively. We recommend the following size of the iframe: * Height - 460px * Width - 504px This size will ensure the most optimum UX within the iframe for both the card view and SCA experience. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' - name: Accept-Language description: 'Language to be used to display the preview. Languages supported: en, it, es, de, fr, pt' in: header required: true schema: type: string - name: id in: path required: true schema: $ref: '#/components/schemas/card_id' responses: '200': description: OK content: application/json: schema: type: object properties: iframe_url: type: string '400': description: Invalid payload content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '/v2/cards/{id}/lost': put: tags: - Cards summary: Report a physical card as lost. x-internal: false security: - OAuth: - card.write description: |- Note: this API is still in beta. Please get in touch with our team to know more: https://getqonto.atlassian.net/servicedesk/customer/portal/5 OAuth scope: `card.write` --- This endpoint allows you to report a physical card as lost, permanently blocking its usage. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' - name: id in: path required: true schema: $ref: '#/components/schemas/card_id' responses: '200': description: Returns the card reported as lost. content: application/json: schema: type: object properties: card: $ref: '#/components/schemas/CardPayload' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityError' '/v2/cards/{id}/stolen': put: tags: - Cards summary: Report a physical card as stolen. x-internal: false security: - OAuth: - card.write description: |- Note: this API is still in beta. Please get in touch with our team to know more: https://getqonto.atlassian.net/servicedesk/customer/portal/5 OAuth scope: `card.write` --- This endpoint allows you to report a physical card as stolen, permanently blocking its usage. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' - name: id in: path required: true schema: $ref: '#/components/schemas/card_id' responses: '200': description: Returns the card reported as stolen. content: application/json: schema: type: object properties: card: $ref: '#/components/schemas/CardPayload' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityError' '/v2/cards/{id}/discard': put: tags: - Cards summary: Discard a virtual card. x-internal: false security: - OAuth: - card.write description: |- Note: this API is still in beta. Please get in touch with our team to know more: https://getqonto.atlassian.net/servicedesk/customer/portal/5 OAuth scope: `card.write` --- This endpoint allows you to discard a virtual card, permanently blocking its usage. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' - name: id in: path required: true schema: $ref: '#/components/schemas/card_id' responses: '200': description: Returns the discarded card. content: application/json: schema: type: object properties: card: $ref: '#/components/schemas/CardPayload' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityError' '/v2/cards/{id}/lock': put: tags: - Cards summary: Lock a card. x-internal: false security: - OAuth: - card.write description: |- Note: this API is still in beta. Please get in touch with our team to know more: https://getqonto.atlassian.net/servicedesk/customer/portal/5 OAuth scope: `card.write` --- This endpoint allows you to put a temporary suspension on the card that can be reversed at any time by the user. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' - name: id in: path required: true schema: $ref: '#/components/schemas/card_id' responses: '200': description: Returns the locked card. content: application/json: schema: type: object properties: card: $ref: '#/components/schemas/CardPayload' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityError' '/v2/cards/{id}/unlock': put: tags: - Cards summary: Unlock a card. x-internal: false security: - OAuth: - card.write description: |- Note: this API is still in beta. Please get in touch with our team to know more: https://getqonto.atlassian.net/servicedesk/customer/portal/5 OAuth scope: `card.write` --- This endpoint allows you to remove a temporary suspension from the card. Only admins and owners of an organization have the permissions to unlock a card. parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' - name: id in: path required: true schema: $ref: '#/components/schemas/card_id' responses: '200': description: Returns the unlocked card. content: application/json: schema: type: object properties: card: $ref: '#/components/schemas/CardPayload' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityError' components: securitySchemes: OAuth: type: oauth2 flows: authorizationCode: authorizationUrl: 'https://oauth.qonto.com/oauth2/auth' tokenUrl: 'https://oauth.qonto.com/oauth2/token' refreshUrl: 'https://oauth.qonto.com/oauth2/token' scopes: organization.read: Allows for generic reads membership.read: Allows read of data related to membership membership.write: Allows creation of data related to memberships attachment.write: Allows to write data related to attachments internal_transfer.write: Allows execution of internal transfers payment.write: Allows write of data related to external payments supplier_invoice.write: Allows write of data related to supplier invoices supplier_invoice.read: Allows read of data related to supplier invoices client_invoices.read: Allows read of data related to client invoices client_invoice.write: Allows creation of data related to client invoices client.read: Allows read of data related to clients client.write: Allows creation of data related to clients request_review.write: Allows creation of data related transfer requests request_review.read: Allows reading of data related to transfer requests team.read: Allows reading of data related to teams team.write: Allows creation of data related to teams request_transfers.write: Allows transfer requests to be made insurance_contract.read: Allows read of insurance contract data insurance_contract.write: 'Allows creation, update and deletion of insurance contract or its attachments' card.read: Allows read of data related to cards card.write: Allows creation/update of data related to cards description: '' SecretKey: name: Authorization type: apiKey in: header description: |- When using the API, authentify Qonto accounts using your slug and secret key in the request. You can find and manage your secret key from the Qonto web application Settings > Integrations. Authentication to the API is performed via HTTP using the Authorization header. ``` Authorization: {organization-slug}:{secret-key} ``` schemas: Pagination: type: object properties: current_page: type: integer example: 2 next_page: type: integer nullable: true example: null prev_page: type: integer nullable: true example: 1 total_pages: type: integer example: 2 total_count: type: integer example: 150 per_page: type: integer example: 100 card_active_days: type: array items: type: integer enum: - 1 - 2 - 3 - 4 - 5 - 6 - 7 description: 'Days card is active i.e. [1-7]. ISO8601: starts on Monday with 1.' example: - 1 - 3 - 5 card_address: type: object description: Address used for the delivery of the card if not shipping to the business address properties: contact_name: type: string nullable: true first_line: type: string second_line: type: string third_line: type: string zipcode: type: string city: type: string country: type: string example: contact_name: null first_line: 751 Metz Falls second_line: '835' third_line: Apt. 734 zipcode: 13563-3709 city: Reinholdchester country: KI card_atm_daily_limit: type: integer minimum: 10 maximum: 3000 description: 'Total of withdrawal limit per day. (unit: euro)' example: 1000 card_atm_daily_limit_option: type: boolean description: Flag indicating whether the total amount per day limit should be applied to atm withdrawals example: true card_atm_daily_spent: type: number description: 'Total of ATM spend today (unit: euro).' example: 0 card_atm_monthly_limit: type: integer description: 'Total of ATM limit per month (unit: euro).' minimum: 10 maximum: 3000 example: 1000 card_atm_monthly_spent: type: number description: 'Total of ATM spend on the current month (unit: euro).' example: 1000 card_atm_option: type: boolean description: Flag indicating whether the card could withdraw money on an ATM. example: true card_bank_account_id: type: string format: uuid description: The id of the bank account to which the card is attached card_categories: type: array description: | By default it's empty array - []. If it's empty array - [] means that category restrictions are turned off and all the categories are allowed. Can be set to not empty only for organizations with price plan starting from Team. List of allowed category tags: - transport - restaurant_and_bar - food_and_grocery - it_and_electronics - utility - tax - legal_and_accounting - atm - office_supply - hardware_and_equipment - finance items: type: string example: - transport - restaurant_and_bar - food_and_grocery card_design: type: string description: 'The visuals for the card are specified according to the card level. For example, "standard.recycled.plastic.2023" is available only for the standard design level, while "plus.recycled.plastic.lilac.2023" is available only for the plus design level. You can determine the design available for a specific card level by looking at the prefix of the card design.' example: plus.black.2023 enum: - standard.recycled.plastic.2023 - plus.recycled.plastic.silver.2023 - plus.recycled.plastic.black.2023 - plus.recycled.plastic.lilac.2023 - metal.graphite.black.2019 - metal.mineral.gray.2024 - metal.sand.gold.2024 - virtual.default.2017 - flash.default.2021 - advertising.default.2023 card_discard_on: type: string nullable: true format: '^[0-9]{4,}-[0-9]{2}-[0-9]{2}$' description: Datetime at which the card will be discarded after being upsold. (upsold_at + 30 days) example: '2022-11-31' card_embossed_name: type: string nullable: true description: String representing the name printed on the physical card object. example: DOLORES KOULECHOV card_exp_month: type: string format: number nullable: true description: 'The expiration month. [1-12]' example: '3' card_exp_year: type: string format: number nullable: true description: The expiration year. example: '2024' card_foreign_option: type: boolean description: Flag indicating whether the card could make a payment outside of France. example: true card_had_operation: type: boolean description: Flag indicating whether the card has had any operations. Operations means any attempt at usage of the card. example: false card_had_pin_operation: type: boolean description: |- Flag indicating whether the card is PIN activated through a PIN operation or not. PIN operations means any attempt to use the card that requires its PIN code. example: false card_holder_id: type: string format: uuid description: The membership identifier of the card holder. card_id: type: string format: uuid description: Unique card identifier card_last_activity_at: type: string format: date-time description: |- The datetime of the last activity happened with this card. By activity we mean any attempt to use the cards, successful or not. Creating a transaction or not. Does not include any updates to settings or options. card_last_digits: type: string nullable: true format: ^\d\d\d\d$ description: The last 4 numbers of the card. example: '7662' card_mask_pan: type: string nullable: true description: String representing the masked PAN of card. example: 511768******7662 card_level: type: string description: |- Level of the card. A level defines a set of card capabilities and pricing. Standard, plus and metal are physical cards. See our Qonto cards: https://qonto.com/en/payment-methods/card. enum: - standard - plus - metal - virtual - flash - advertising example: standard card_nfc_option: type: boolean description: Flag indicating whether the card could make a payment with NFC mode (contactless). example: true card_nickname: nullable: false type: string description: Display name for the card. maxLength: 40 minLength: 1 example: "\U0001F4B3 for \U0001F357" card_online_option: type: boolean description: |- Flag indicating whether the card could make an online payment. Online payment are not related to any mastercard registered Point of Sale or terminal of payment. example: true card_organization_id: type: string format: uuid description: The ID of the organization the card belongs to. card_payment_daily_limit: type: integer minimum: 0 maximum: 60000 description: Total of payment limit per day. example: 1000 card_payment_daily_limit_option: type: boolean description: Flag indicating whether the total amount per day limit should be applied to payments example: true card_payment_daily_spent: type: number description: 'Total amount spent on the current day (unit: euro).' example: 1000 card_payment_lifespan_limit: type: integer description: 'Total of payment limit until card expires (unit: euro). Applicable only for Flash cards.' minimum: 5 maximum: 20000 default: 100 card_payment_lifespan_spent: type: number description: 'Total amount spent on the card since its creation (unit: euro).' example: 42 card_payment_monthly_limit: type: integer description: 'Total of payment limit by month (unit: euro).' minimum: 0 maximum: 200000 example: 1000 card_payment_monthly_spent: type: number description: 'Total of payment spend on the current month (unit: euro).' example: 1000 card_payment_transaction_limit: type: integer description: Total of payment limit per transaction. example: 1000 card_payment_transaction_limit_option: type: boolean description: Flag indicating whether the total amount per transaction limit should be applied to payments example: true card_pin_set: type: boolean description: Whether the pin code for the card is set or not. example: true card_pre_expires_at: type: string nullable: true description: Flash card will be valid until this date. format: date-time card_renewed: type: boolean description: Flag indicating whether the expiring card has been renewed e.i. if renewal card has been created then the expiring card's renewed field becomes true example: false card_renewal: type: boolean description: Flag indicating whether the card is a renewal card example: false card_reordered: type: boolean description: Describes if the card has been reordered and there is a new card instead. example: false default: false card_ship_to_business: type: boolean description: 'Whether the card is shipped to the business location, which is the organisation address as registered in Qonto.' example: false card_shipped_at: type: string format: date-time description: |- For physical cards only, Datetime at which the card was shipped to its holder. Depending on the carrier (local or international), delivery can take from 2 to 5 business days to complete the reception of the card. nullable: true example: null card_status: type: string enum: - pending - live - paused - stolen - lost - pin_blocked - discarded - expired - shipped_lost - onhold - order_canceled - pre_expired - abusive description: |- Status of the card. Pending: the card is awaiting PIN to be set or issuing to complete. Live: the card is active and can be used. Paused: the card is paused and cannot be used until un-paused. Stolen: the card has been reported as stolen and cannot be used. Lost: the card has been reported as lost and cannot be used. Pin_blocked: the card has been blocked due to too many wrong PIN attempts. It can still be used for card-not-present transactions. Discarded: the card has been discarded and cannot be used. Expired: the card has expired and cannot be used. Shipped_lost: the card has been lost during shipping and cannot be used. Onhold: the card issuing is on hold due to missing KYC/KYB validation and cannot be used. Order_canceled: the card order has been canceled. Pre_expired: the flash card has reached the end of its validity and cannot be used. Abusive: the card has been reported as abusive and cannot be used. example: pending card_type: type: string description: |- Type of the card. Currently only `debit` cards are supported. It has an impact on when the money is debited but also in the acceptance on the merchant side. enum: - debit - prepaid example: debit card_type_of_print: type: string nullable: true description: |- Specifies how the card information is presented on the physical card. This property is exclusively available for `plus` cards; other card levels must omit the value. example: embossed enum: - print - embossed card_upsell: type: boolean description: Flag indicating whether the card is an upsell child card example: false card_upsold: type: boolean description: Flag indicating whether the card has been upsold example: false CreatePhysicalCard: title: CreatePhysicalCard type: object properties: card: type: object properties: ship_to_business: $ref: '#/components/schemas/card_ship_to_business' atm_option: allOf: - $ref: '#/components/schemas/card_atm_option' - default: true nfc_option: allOf: - $ref: '#/components/schemas/card_nfc_option' - default: false foreign_option: allOf: - $ref: '#/components/schemas/card_foreign_option' - default: true online_option: allOf: - $ref: '#/components/schemas/card_online_option' - default: true atm_monthly_limit: allOf: - $ref: '#/components/schemas/card_atm_monthly_limit' - description: 'Total of ATM limit per month (unit: euro). If atm_option is false, this can be omitted' atm_daily_limit_option: allOf: - $ref: '#/components/schemas/card_atm_daily_limit_option' - description: 'Flag indicating whether the total amount per day limit should be applied to atm withdrawals. If atm_option is false, this can be omitted' atm_daily_limit: allOf: - $ref: '#/components/schemas/card_atm_daily_limit' - description: 'Total of withdrawal limit per day. If atm_option and atm_daily_limit_option are false, this can be omitted' payment_monthly_limit: $ref: '#/components/schemas/card_payment_monthly_limit' payment_daily_limit_option: $ref: '#/components/schemas/card_payment_daily_limit_option' payment_daily_limit: $ref: '#/components/schemas/card_payment_daily_limit' payment_transaction_limit_option: $ref: '#/components/schemas/card_payment_transaction_limit_option' payment_transaction_limit: $ref: '#/components/schemas/card_payment_transaction_limit' active_days: $ref: '#/components/schemas/card_active_days' holder_id: $ref: '#/components/schemas/card_holder_id' organization_id: $ref: '#/components/schemas/card_organization_id' bank_account_id: $ref: '#/components/schemas/card_bank_account_id' address: $ref: '#/components/schemas/card_address' card_level: type: string enum: - standard - plus - metal categories: $ref: '#/components/schemas/card_categories' card_design: $ref: '#/components/schemas/card_design' type_of_print: $ref: '#/components/schemas/card_type_of_print' required: - ship_to_business - payment_monthly_limit - atm_monthly_limit - atm_daily_limit_option - atm_daily_limit - card_level - holder_id - organization_id - bank_account_id CreateVirtualCard: title: CreateVirtualCard type: object properties: card: type: object properties: payment_monthly_limit: $ref: '#/components/schemas/card_payment_monthly_limit' payment_daily_limit: $ref: '#/components/schemas/card_payment_daily_limit' payment_daily_limit_option: $ref: '#/components/schemas/card_payment_daily_limit_option' payment_transaction_limit: $ref: '#/components/schemas/card_payment_transaction_limit' payment_transaction_limit_option: $ref: '#/components/schemas/card_payment_transaction_limit_option' active_days: $ref: '#/components/schemas/card_active_days' holder_id: $ref: '#/components/schemas/card_holder_id' organization_id: $ref: '#/components/schemas/card_organization_id' bank_account_id: $ref: '#/components/schemas/card_bank_account_id' card_level: type: string default: virtual categories: $ref: '#/components/schemas/card_categories' required: - payment_monthly_limit - card_level - holder_id - organization_id - bank_account_id CreateAdvertisingCard: title: CreateAdvertisingCard type: object properties: card: type: object properties: payment_monthly_limit: $ref: '#/components/schemas/card_payment_monthly_limit' payment_daily_limit: $ref: '#/components/schemas/card_payment_daily_limit' payment_daily_limit_option: $ref: '#/components/schemas/card_payment_daily_limit_option' holder_id: $ref: '#/components/schemas/card_holder_id' organization_id: $ref: '#/components/schemas/card_organization_id' bank_account_id: $ref: '#/components/schemas/card_bank_account_id' card_level: type: string default: advertising required: - card_level - holder_id - organization_id - bank_account_id CreateFlashCard: title: CreateFlashCard type: object properties: card: type: object properties: payment_lifespan_limit: $ref: '#/components/schemas/card_payment_lifespan_limit' pre_expires_at: $ref: '#/components/schemas/card_pre_expires_at' holder_id: $ref: '#/components/schemas/card_holder_id' organization_id: $ref: '#/components/schemas/card_organization_id' bank_account_id: $ref: '#/components/schemas/card_bank_account_id' card_level: type: string default: flash required: - payment_lifespan_limit - pre_expires_at - card_level - holder_id - organization_id - bank_account_id CardPayload: description: A representation of a card type: object properties: id: $ref: '#/components/schemas/card_id' nickname: $ref: '#/components/schemas/card_nickname' embossed_name: $ref: '#/components/schemas/card_embossed_name' status: $ref: '#/components/schemas/card_status' pin_set: $ref: '#/components/schemas/card_pin_set' mask_pan: $ref: '#/components/schemas/card_mask_pan' exp_month: $ref: '#/components/schemas/card_exp_month' exp_year: $ref: '#/components/schemas/card_exp_year' last_activity_at: $ref: '#/components/schemas/card_last_activity_at' last_digits: $ref: '#/components/schemas/card_last_digits' ship_to_business: $ref: '#/components/schemas/card_ship_to_business' atm_option: $ref: '#/components/schemas/card_atm_option' nfc_option: $ref: '#/components/schemas/card_nfc_option' online_option: $ref: '#/components/schemas/card_online_option' foreign_option: $ref: '#/components/schemas/card_foreign_option' atm_monthly_limit: $ref: '#/components/schemas/card_atm_monthly_limit' atm_monthly_spent: $ref: '#/components/schemas/card_atm_monthly_spent' atm_daily_limit: $ref: '#/components/schemas/card_atm_daily_limit' atm_daily_spent: $ref: '#/components/schemas/card_atm_daily_spent' atm_daily_limit_option: $ref: '#/components/schemas/card_atm_daily_limit_option' payment_monthly_limit: $ref: '#/components/schemas/card_payment_monthly_limit' payment_monthly_spent: $ref: '#/components/schemas/card_payment_monthly_spent' payment_daily_limit: $ref: '#/components/schemas/card_payment_daily_limit' payment_daily_spent: $ref: '#/components/schemas/card_payment_daily_spent' payment_daily_limit_option: $ref: '#/components/schemas/card_payment_daily_limit_option' payment_transaction_limit: $ref: '#/components/schemas/card_payment_transaction_limit' payment_transaction_limit_option: $ref: '#/components/schemas/card_payment_transaction_limit_option' active_days: $ref: '#/components/schemas/card_active_days' holder_id: $ref: '#/components/schemas/card_holder_id' bank_account_id: $ref: '#/components/schemas/card_bank_account_id' organization_id: $ref: '#/components/schemas/card_organization_id' updated_at: type: string format: date-time description: Datetime at which the object was last updated. created_at: type: string format: date-time description: Datetime at which the object was created. shipped_at: $ref: '#/components/schemas/card_shipped_at' card_type: $ref: '#/components/schemas/card_type' card_level: $ref: '#/components/schemas/card_level' payment_lifespan_limit: $ref: '#/components/schemas/card_payment_lifespan_limit' payment_lifespan_spent: $ref: '#/components/schemas/card_payment_lifespan_spent' pre_expires_at: $ref: '#/components/schemas/card_pre_expires_at' categories: $ref: '#/components/schemas/card_categories' renewed: $ref: '#/components/schemas/card_renewed' renewal: $ref: '#/components/schemas/card_renewal' parent_card_summary: allOf: - $ref: '#/components/schemas/CardSummary' - description: Summary of this card's parent (the card which this card is a renewal of) had_operation: $ref: '#/components/schemas/card_had_operation' had_pin_operation: $ref: '#/components/schemas/card_had_pin_operation' card_design: $ref: '#/components/schemas/card_design' type_of_print: $ref: '#/components/schemas/card_type_of_print' upsold: $ref: '#/components/schemas/card_upsold' upsell: $ref: '#/components/schemas/card_upsell' discard_on: $ref: '#/components/schemas/card_discard_on' reordered: $ref: '#/components/schemas/card_reordered' CardSummary: type: object description: 'Summary of a card, containing only static immutable information' properties: id: $ref: '#/components/schemas/card_id' last_digits: $ref: '#/components/schemas/card_last_digits' SupplierInvoice: type: object required: - id - status - organization_id - source_type - attachment_id - updated_at - created_at - file_name properties: id: type: string format: uuid example: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 organization_id: type: string format: uuid example: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 file_name: type: string example: my-invoice.pdf invoice_number: type: string example: QONTO-JAN-2022 supplier_name: type: string example: McDonald's description: type: string example: This is an invoice for Ronald! total_amount: type: object properties: value: type: string example: '22.10' currency: type: string example: EUR issue_date: type: string example: '2022-02-01' due_date: type: string example: '2022-03-01' payment_date: type: string example: '2022-03-01' scheduled_date: type: string example: '2022-03-01' status: type: string example: to_review enum: - to_review - to_pay - pending - scheduled - paid iban: type: string example: FR1420041010050500013M02606 initiator_id: type: string format: uuid source_type: type: string example: email enum: - email - manual_upload created_at: type: string example: '2022-03-04T17:58:30+02:00' updated_at: type: string example: '2022-03-04T17:58:30+02:00' attachment_id: type: string format: uuid analyzed_at: type: string example: '2022-03-04T17:58:30+02:00' request_transfer: type: object properties: id: type: string format: uuid example: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 initiator_id: type: string format: uuid example: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 meta: type: object properties: integration_type: type: string example: amazon connector: type: string example: grover ClientInvoice: type: object x-examples: {} required: - id - organization_id - number - purchase_order - status - invoice_url - contact_email - terms_and_conditions - discount_conditions - late_payment_penalties - legal_fixed_compensation - header - footer - currency - total_amount - total_amount_cents - vat_amount - vat_amount_cents - issue_date - due_date - performance_date - created_at - finalized_at - paid_at - stamp_duty_amount - items - client - payment_methods - credit_notes_ids - organization properties: id: type: string format: uuid example: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 organization_id: type: string format: uuid example: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 attachment_id: type: string format: uuid example: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 description: |- Attachment UUID corresponding to that particular invoice.
When creating the invoice (by calling the [POST /v2/client_invoices](https://api-doc.qonto.com/docs/business-api/740572a1dd6f7-create-a-client-invoice) endpoint), the attachment is generated **asynchronously**; which means that you have to wait ~10s and then call the [GET /v2/client_invoices/{id}](https://api-doc.qonto.com/docs/business-api/copd6wc7nwym8-show-client-invoice) endpoint to get the `attachment_id`.
This attribute enables you to get the invoice file by using the [GET /v2/attachments/{id}](https://api-doc.qonto.com/docs/business-api/345dace7b485b-show-attachment) endpoint. number: type: string example: INV001 purchase_order: type: string description: Purchase order data added by the invoice’s initiator. status: type: string enum: - draft - unpaid - paid - canceled example: paid invoice_url: type: string format: uri example: 'https://pay.qonto.com/invoices/00000000-0000-0000-0000-000000000000' description: 'URL of the invoice public page, accessible without authentication for 180 days after issuance, provided the invoice has not been canceled.' contact_email: type: string format: email example: contact@qonto.com description: E-mail address of the invoice’s initiator. terms_and_conditions: type: string example: This is an example. description: The T&C data added by the invoice’s initiator. discount_conditions: type: string maximum: 50000 example: Pas d’escompte accordé pour paiement anticipé. description: Any discount for advance payment of the invoice. It is optional and is only for French organizations. nullable: true late_payment_penalties: type: string maximum: 50000 example: 'En cas de non-paiement à la date d''échéance, des pénalités calculées à trois fois le taux d’intérêt légal seront appliquées.' description: Late payment penalties applied in case of non-payment invoice. It is optional and is only for French organizations. nullable: true legal_fixed_compensation: type: string maximum: 50000 example: Tout retard de paiement entraînera une indemnité forfaitaire pour frais de recouvrement de 40€. description: The legal fixed compensation applied in case late payment of the invoice. It is optional and is only for French organizations. nullable: true header: type: string example: This is an example. description: The header text added by the credit note’s initiator. footer: type: string example: This is an example. description: The footer text added by the credit note’s initiator. currency: type: string example: EUR total_amount: type: object x-stoplight: id: r2tav38fcapix description: Total amount that needs to be paid by the client. properties: value: type: string x-stoplight: id: wqw5wy2vby8h4 example: '12.52' currency: type: string x-stoplight: id: gr89ztsxe2l6d example: EUR total_amount_cents: type: integer example: 1252 description: Total amount in cents that needs to be paid by the client. vat_amount: type: object description: VAT amount that is applicable to the invoice. properties: value: type: string example: '0.51' currency: type: string example: EUR vat_amount_cents: type: integer example: 51 description: VAT amount in cents that is applicable to the invoice. issue_date: type: string format: date example: '2022-03-01' description: Date the initiator mentioned that the invoice was created. due_date: type: string format: date example: '2022-03-01' description: Payment’s deadline added by the initiator. performance_date: type: string format: date example: '2022-03-01' description: Date the initiator mentioned that the contents of the invoice were performed. created_at: type: string format: date-time example: '2022-03-04T17:58:30+02:00' description: Date the invoice was created. Note that this is a machine date. finalized_at: type: string format: date-time example: '2022-03-04T17:58:30+02:00' description: Date the invoice was transitioned from `Draft` to `Unpaid` status. paid_at: type: string format: date-time example: '2022-03-04T17:58:30+02:00' description: Date on which the invoice was paid. stamp_duty_amount: type: string minLength: 4 maxLength: 15 example: '1.00' items: type: array items: $ref: '#/components/schemas/DocumentItem' client: $ref: '#/components/schemas/EmbeddedClient' payment_methods: type: array items: type: object properties: beneficiary_name: type: string example: John Doe description: Name of the beneficiary that will receive the invoice's payment. bic: type: string example: ABCDEFG1XXX description: Beneficiary’s International Bank Account Number. iban: type: string example: FR1420041010050500013M02606 description: Beneficiary account's Bank Identifier. type: type: string enum: - transfer example: transfer description: Invoice's payment method. credit_notes_ids: type: array description: 'If any credit notes are linked to the invoice, this represents the id of those credit notes.' items: type: string format: uuid readOnly: true organization: $ref: '#/components/schemas/EmbeddedInvoiceOrganization' einvoicing_status: type: string enum: - pending - submitted - declined - approved - not_delivered - submission_failed welfare_fund: type: object properties: type: type: string enum: - TC01 - TC02 - TC03 - TC04 - TC05 - TC06 - TC07 - TC08 - TC09 - TC10 - TC11 - TC12 - TC13 - TC14 - TC15 - TC16 - TC17 - TC18 - TC19 - TC20 - TC21 - TC22 example: TC01 rate: type: string minLength: 4 maxLength: 6 example: '0.0001' withholding_tax: type: object description: |- - Only applicable for Italian organizations and Spanish freelancers. - Object which relates to an amount of tax paid by the client, rather than the supplier, for specific cases. - This amount is a percentage deducted from the total amount of the invoice after VAT application. - The `rate` field specifies the percentage of tax and `amount` field specifies the total amount of the tax. properties: reason: type: string enum: - RF01 - RF02 - RF03 - RF04 - RF05 - RF06 example: RF01 rate: type: string minLength: 4 maxLength: 6 example: '0.01' payment_reason: type: string example: L1 minLength: 1 maxLength: 2 amount: type: string example: '1.00' payment_reporting: type: object properties: conditions: type: string enum: - TP01 - TP02 - TP03 example: TP01 method: type: string enum: - MP01 - MP02 - MP03 - MP04 - MP05 - MP06 - MP07 - MP08 - MP09 - MP10 - MP11 - MP12 - MP13 - MP14 - MP15 - MP16 - MP17 - MP18 - MP19 - MP20 - MP21 - MP22 example: MP01 ClientInvoiceCreatePayload: type: object properties: client_id: type: string format: uuid issue_date: type: string format: date example: '2022-03-01' performance_date: type: string format: date description: represents the date the initiator has issued or shared the invoice as legally viable. The format should be `YYYY-MM-DD` due_date: type: string format: date description: represents the invoice’s payment deadline that is added by the initiator. The format should be `YYYY-MM-DD` status: type: string enum: - draft - unpaid description: 'represents the status of the invoice. If not filled, `unpaid` will be automatically attributed to the invoice.' number: type: string example: INV-2023-001 maxLength: 40 description: represents the invoice’s number. purchase_order: type: string maxLength: 40 description: represents the purchase order data added by the invoice’s initiator. terms_and_conditions: type: string maxLength: 525 description: represents additional notes added by the invoice’s initiator. header: type: string example: This is an example. footer: type: string example: This is an example. currency: type: string description: 'represents the invoice’s currency for the total amount of the invoice. Currently, only value allowed is EUR. Trigram following ISO 4217' example: EUR payment_methods: type: object description: contains payment method details for the invoice. properties: iban: type: string description: 'represents the beneficiary’s International Bank Account Number (IBAN). The format must follow ISO 13616, and should be a valid IBAN (must start with two letters, followed by 25 digits). The IBAN must be associated to a Qonto account.' required: - iban settings: $ref: '#/components/schemas/InvoiceSettingsOverride' items: type: array items: $ref: '#/components/schemas/DocumentItemPayload' report_einvoicing: type: boolean description: |- - For Italian organizations only - Non-Italian organizations should not include this attribute in the request. - Italian organizations must have e-invoicing activated to use this endpoint, no matter the value of the flag. - By default for an Italian organization that has e-invoicing activated on the Qonto app, if this field is not filled, this attribute is set to true and the invoice is automatically sent to Italian exchange system (Sistema di Interscambio, or SdI) as an XML e-invoice. If set to `false`, the invoice will not be sent to SdI. - Use the `GET` v2/client_invoices to retrieve its e-invoicing status under the attribute `einvoicing_status`. payment_reporting: description: |- - For Italian organizations only - Non-Italian organizations should not include this attribute in the request. - Object which relates to payment methods and conditions of the invoice. type: object properties: conditions: description: represents the payment conditions on the invoice. type: string enum: - TP01 - TP02 - TP03 example: TP01 method: description: represents the payment method of the invoice. type: string enum: - MP01 - MP02 - MP03 - MP04 - MP05 - MP06 - MP07 - MP08 - MP09 - MP10 - MP11 - MP12 - MP13 - MP14 - MP15 - MP16 - MP17 - MP18 - MP19 - MP20 - MP21 - MP22 example: MP01 required: - conditions - method welfare_fund: description: |- - For Italian organizations only - Non-Italian organizations should not include this attribute in the request. - Object which relates to pension contributions added to the total amount to pay, applicable in some cases. - This amount is a percentage added to the total amount of the invoice pre-taxes. type: object properties: type: type: string enum: - TC01 - TC02 - TC03 - TC04 - TC05 - TC06 - TC07 - TC08 - TC09 - TC10 - TC11 - TC12 - TC13 - TC14 - TC15 - TC16 - TC17 - TC18 - TC19 - TC20 - TC21 - TC22 example: TC01 description: represents the welfare fund type. rate: type: string minLength: 4 maxLength: 6 example: '0.0001' description: 'represents the welfare fund rate applicable for the invoice. Written in decimals, separated by a period “.” For example, for a rate of 1%, input is 0.01, and for a rate of 10%, input is 0.1' required: - rate - type withholding_tax: description: |- - Only for Italian organizations and Spanish freelancers - Other organizations should not include this attribute in the request. - Object which relates to an amount of tax paid by the client, rather than the supplier, for specific cases. - This amount is a percentage deducted from the total amount of the invoice after VAT application. - ES freelancers need to only fill the withholding_tax `rate` field with their IRPF. type: object properties: reason: description: represents the reason the withholding tax. type: string enum: - RF01 - RF02 - RF03 - RF04 - RF05 - RF06 example: RF01 rate: type: string minLength: 4 maxLength: 6 example: '0.01' description: 'represents the withholding tax rate applicable for the invoice. Written in decimals, separated by a period “.” For example, for a rate of 1%, input is 0.01 and for a rate of 10%, input is 0.1' payment_reason: type: string example: L1 minLength: 1 maxLength: 2 description: represents the payment reason the withholding tax. required: - rate - reason - payment_reason stamp_duty_amount: type: string minLength: 4 maxLength: 15 example: '1.00' description: |- - For Italian organizations only - Non-Italian organizations should not include this attribute in the request. - Represents an amount (2.00 EUR) applicable on invoices where VAT is excluded and the invoice has a value exceeding 77.47 EUR. required: - client_id - issue_date - due_date - number - currency - items - payment_methods CreditNote: type: object properties: id: type: string format: uuid example: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 invoice_id: type: string format: uuid example: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 attachment_id: type: string format: uuid example: 4d5418bb-bd0d-4df4-865c-c07afab8bb48 issue_date: type: string format: date example: '2022-03-01' invoice_issue_date: type: string format: date example: '2022-03-02' number: type: string example: INV001 terms_and_conditions: type: string example: This is an example. header: type: string example: This is an example. footer: type: string example: This is an example. vat_amount: type: object properties: value: type: string example: '0.51' currency: type: string example: EUR vat_amount_cents: type: integer example: 51 total_amount: type: object properties: value: type: string example: '12.52' currency: type: string example: EUR total_amount_cents: type: integer example: 1252 currency: type: string example: EUR created_at: type: string format: date-time example: '2022-03-04T17:58:30+02:00' finalized_at: type: string format: date-time example: '2022-03-04T17:58:30+02:00' contact_email: type: string format: email example: contact@qonto.com invoice_url: type: string format: uri example: 'https://pay.qonto.com/invoices/00000000-0000-0000-0000-000000000000' description: 'represents the URL of the invoice public page, accessible without authentication for 180 days after issuance, provided the invoice has not been canceled.' einvoicing_status: type: string enum: - pending - submitted - declined - approved - not_delivered - submission_failed welfare_fund: type: object properties: type: type: string enum: - TC01 - TC02 - TC03 - TC04 - TC05 - TC06 - TC07 - TC08 - TC09 - TC10 - TC11 - TC12 - TC13 - TC14 - TC15 - TC16 - TC17 - TC18 - TC19 - TC20 - TC21 - TC22 example: TC01 rate: type: string minLength: 4 maxLength: 6 example: '0.0001' withholding_tax: description: |- - Only applicable for Italian organizations and Spanish freelancers. - Object which relates to an amount of tax paid by the client, rather than the supplier, for specific cases. - This amount is a percentage deducted from the total amount of the invoice after VAT application. - The `rate` field specifies the percentage of tax and `amount` field specifies the total amount of the tax. type: object properties: reason: type: string enum: - RF01 - RF02 - RF03 - RF04 - RF05 - RF06 example: RF01 rate: type: string minLength: 4 maxLength: 6 example: '0.01' payment_reason: type: string minLength: 1 maxLength: 2 amount: type: string example: '1.00' stamp_duty_amount: type: string minLength: 4 maxLength: 15 example: '1.00' items: type: array items: $ref: '#/components/schemas/DocumentItem' client: $ref: '#/components/schemas/EmbeddedClient' EmbeddedClient: type: object description: Client that needs to pay the invoice. properties: id: type: string format: uuid example: 33v418bb-bd0d-4df4-865c-c07afab8bb48 name: type: string example: McDonald's description: Note that this attribute will be returned only if the client is a `company`. first_name: type: string example: Jane description: Note that this attribute will be returned only if the client is an `individual` or a `freelancer`. last_name: type: string example: Doe description: Note that this attribute will be returned only if the client is an `individual` or a `freelancer`. type: type: string enum: - individual - company - freelancer example: individual email: type: string format: email example: client@qonto.com vat_number: type: string example: FR32123456789 tax_identification_number: type: string example: '123456789' address: type: string example: 1 place de l’Opéra city: type: string example: Paris zip_code: type: string example: '75009' province_code: type: string description: Province code of the client. It is required only for Italian organizations country_code: type: string example: fr recipient_code: type: string description: 'Recipient code, so that the client can receive the e-invoice in his SdI portal.' locale: type: string example: fr billing_address: description: 'Billing address of the client, which will be reflected on the invoice. Stores the same data as the root-level fields address fields (`address`, `city`, `zip_code`, `province_code`, `country_code`).' allOf: - $ref: '#/components/schemas/ClientBillingAddress' type: object delivery_address: allOf: - $ref: '#/components/schemas/ClientDeliveryAddress' description: 'Delivery address of the client. Stores the same data as the root-level fields address fields (`address`, `city`, `zip_code`, `province_code`, `country_code`).' type: object ExternalTransfer: type: object required: - id - slug - debit_iban - debit_amount - debit_amount_cents - debit_currency - beneficiary_id - initiator_id - credit_amount - credit_amount_cents - credit_currency - reference - status - scheduled_date - created_at properties: id: type: string format: uuid slug: type: string debit_iban: type: string description: ISO 13616 debit_amount: type: string example: '12.55' debit_amount_cents: type: string example: '1255' debit_currency: type: string example: EUR description: ISO 4217 beneficiary_id: type: string format: uuid initiator_id: type: string format: uuid description: |- ID of the membership that initiated the external transfer.
When the external transfer is initiated through the API, the initiator is the authenticated membership. credit_amount: type: string credit_amount_cents: type: string credit_currency: type: string description: ISO 4217 rate_applied: type: string payment_purpose: type: string example: goods description: Compulsory for all swift networks reference: type: string note: type: string description: 140 characters max declined_reason: type: string example: beneficiary_bic_invalid description: |- Populated only when transfer **status** is declined. Possible values: `beneficiary_bic_invalid` `beneficiary_iban_invalid` `beneficiary_status` `beneficiary_network_rules_error` `organisation_compliance_reasons` `debit_account_insufficient_funds` `qonto_processing_failed` status: example: pending type: string description: |- Possible values: `pending` `processing` `canceled` `declined` `settled` scheduled_date: type: string example: '2021-07-12' created_at: type: string example: '2021-01-27T22:05:07.000Z' completed_at: type: string example: '2021-01-27T22:05:07.000Z' processed_at: type: string example: '2021-01-27T22:05:07.000Z' transaction_id: type: string format: uuid EmbeddedInvoiceOrganization: type: object description: Information of the organization at the time the document was issued. properties: id: type: string format: uuid legal_name: type: string legal_number: type: string legal_country: type: string address_line_1: type: string address_line_2: type: string address_zipcode: type: string address_city: type: string address_country: type: string company_leadership: type: string example: Jan Mueller district_court: type: string example: Munich commercial_register_number: type: string example: HRB12345B description: |- Is available for French and German organizations and is optional. - For French organizations, it represents RCS number (numéro Registre du Commerce et des Sociétés) of an incorporated business. For example: RCS A 123 123 123. - For German organizations, it represents the organization's commercial register number (handelsregisternummer). For example: HRB 123455 B. vat_number: type: string example: FR123456789 tax_number: type: string example: 123/123/1234 legal_capital_share: type: object description: Capital share of an incorporated business. It is optional and is only for French organizations. properties: value: minLength: 0 maxLength: 12 type: string example: '10000.00' currency: $ref: '#/components/schemas/Currency' transaction_type: type: string enum: - goods - services - goods_and_services example: goods description: Type of transaction performed in the invoice. It is optional and is only for French organizations. vat_payment_condition: type: string enum: - on_receipts - compensated_for_sales - exempt example: on_receipts description: |- Business’ VAT elected payment condition (whether TVA is paid on receipt or on invoice emission). There are two allowed values: - `receipt` which stands for “sur les encaissements” in French; - `compensated_for_sales` which stands for “sur les débits” in French. It is optional and is only for French organizations. InvoiceSettingsOverride: description: | This collection of attributes can be optionally used to temporarily override some of the organization's properties for this one invoice. type: object properties: vat_number: type: string example: FR12345678 company_leadership: type: string example: Jan Mueller district_court: type: string example: Munich commercial_register_number: type: string example: HRB12345B tax_number: type: string example: 123/123/1234 legal_capital_share: type: object properties: value: minLength: 0 maxLength: 12 type: string example: '10000.00' currency: $ref: '#/components/schemas/Currency' transaction_type: type: string enum: - goods - services - goods_and_services example: goods vat_payment_condition: type: string enum: - on_receipts - compensated_for_sales example: on_receipts discount_conditions: type: string maximum: 50000 example: Pas d’escompte accordé pour paiement anticipé. nullable: true late_payment_penalties: type: string maximum: 50000 example: 'En cas de non-paiement à la date d''échéance, des pénalités calculées à trois fois le taux d’intérêt légal seront appliquées.' nullable: true legal_fixed_compensation: type: string maximum: 50000 example: Tout retard de paiement entraînera une indemnité forfaitaire pour frais de recouvrement de 40€. nullable: true DocumentItem: type: object properties: title: type: string example: Plastic tables description: type: string example: Plastic tables for McDonald’s restaurants quantity: type: string example: '1.5' unit: type: string example: meter unit_price: type: object description: Amount of the price per unit. Note that an item can contain multiple units. The number of units is defined via `quantity`. properties: value: type: string example: '10.0' currency: type: string example: EUR unit_price_cents: type: integer example: 1000 description: Amount in cents of the price per unit. Note that an item can contain multiple units. The number of units is defined via `quantity`. vat_rate: type: string description: VAT rate in decimal (0.1 for 10%) applicable to that particular item. example: '0.1' vat_exemption_reason: type: string description: Exemption reason enum: - N1 - N2 - N2.1 - N2.2 - N3 - N3.1 - N3.2 - N3.3 - N3.4 - N3.5 - N3.6 - N4 - N5 - N6 - N6.1 - N6.2 - N6.3 - N6.4 - N6.5 - N6.6 - N6.7 - N6.8 - N6.9 - N7 - S293B - S262.1 - S259 - S283 - S261 - S262 - S263 - S19.1 - S4.1B - S4.1A - S4 - S13B - S122 - S25 - S21 - S69 - S20 - S84.1.2 discount: type: object properties: type: type: string enum: - percentage - absolute example: percentage value: type: string example: '0.1' description: 'Discount rate or absolute amount. For percentage, the minimum value is 0.0001 (0.01%), and the maximum value is 1 (100%). For absolute value, the maximum is determined by Quantity * Unit Price.' amount: type: object properties: value: type: string example: '120' currency: type: string example: EUR total_vat: type: object description: VAT amount that is applicable to that specific item. properties: value: type: string example: '120' currency: type: string example: EUR total_vat_cents: type: integer example: 12000 description: VAT amount in cents that is applicable to that specific item. total_amount: type: object description: Amount that needs to be paid by the client for that specific item. properties: value: type: string example: '300.50' currency: type: string example: EUR total_amount_cents: type: integer example: 30050 description: Amount in cents that needs to be paid by the client for that specific item. subtotal: type: object properties: value: type: string example: '120' description: Subtotal amount for the item without VAT. Quantity * Unit_price. currency: type: string example: EUR subtotal_cents: type: integer example: 12000 description: Subtotal amount in cents for the item without VAT. DocumentItemPayload: type: object properties: title: type: string maxLength: 40 description: represents the item’s title. It is displayed as the first line of the item in bold in the invoice table. It indicates in a short sentence the product or service being sold. description: type: string maxLength: 300 description: 'represents the item’s description of the product or service being sold. It is added below the title of each item in the invoice table. Free format, with a maximum of 300 characters. Use `\n` to indicate line breaks.' quantity: type: string example: '0.5' description: 'represents the item’s quantity of the specific product or services being sold. For example, it can be in hours or in number of products. Decimals should be separated by a period “.”' unit: type: string example: meter description: | represents the item’s unit. It is an optional field and allows maximum 20 characters for non Italian organizations. - For Italian organizations, documents are generated in PDF format and in XML format (automatically sent to the Italian tax authorites). In the PDF, unit will appear with a maximum of 20 characters. In the XML file, it is truncated down to the first 10 characters. - For French organizations, documents are generated under the Factur-X format (a structured PDF file with an embedded XML). For the XML file, units that have a corresponding EN16931 code (standard followed by Factur-X format) will be indicated with its relevant code. See mapping below of possible values and their corresponding code.

Possible values and corresponding EN16931 code (pursuant to the “Annexe 7” of the B2B external specifications for French e-invoicing, BT-130, allowed units of measure)

| Unit | EN16931 code | |-------------------------|------| | unit | C62 | | hour | HUR | | day | DAY | | month | MON | | gram | GRM | | kilogram | KGM | | liter | LTR | | meter | MTR | | square_meter | MTK | | cubic_meter | MTQ | | ampere | AMP | | number_of_articles | NAR | | centimeter | CMT | | cubic_meter_per_hour | MQH | | gigajoule | GV | | gigawatt | A90 | | gigawatt_hour | GWH | | half_year | SAN | | joule | JOU | | kilojoule | KJO | | kilovar | KVR | | kilovolt_ampere_reactive_hour | K3 | | kilowatt | KWT | | kilowatt_hour | KWH | | megajoule | 3B | | megawatt | MAW | | megawatt_hour | MWH | | milligram | MGM | | milliliter | MLT | | millimeter | MMT | | minute | MIN | | pair | PR | | quarter | QAN | | second | SEC | | set | SET | | ton | TNE | | two_week | W4 | | watt_hour | WHR | | week | WEE | | year | ANN | | custom_input_text | ZZ |

unit_price: type: object properties: value: type: string description: represents price per unit of product or service sold. Decimals should be separated by a period “.” currency: type: string description: 'represents the item’s currency. Currently, only value allowed is EUR. Format supported is a trigram following ISO 4217.' required: - value - currency vat_rate: type: string example: '0.1' description: 'represents the VAT rate applicable for that particular item. Written in decimals, separated by a period “.” For example, for a VAT of 10%, input is 0.1' vat_exemption_reason: type: string enum: - N1 - N2 - N2.1 - N2.2 - N3 - N3.1 - N3.2 - N3.3 - N3.4 - N3.5 - N3.6 - N4 - N5 - N6 - N6.1 - N6.2 - N6.3 - N6.4 - N6.5 - N6.6 - N6.7 - N6.8 - N6.9 - N7 - S293B - S262.1 - S259 - S283 - S261 - S262 - S263 - S19.1 - S4.1B - S4.1A - S4 - S13B - S122 - S25 - S21 - S69 - S20 - S84.1.2 example: N1 maxLength: 4 description: 'Represents the VAT exemption reason when the item’s vat_rate is equal to 0. It is required for Italian organizations only, must be indicated for each item that has a VAT rate of 0 and the code must start with `N`. If VAT rate is not 0, this field should not be included.' discount: type: object properties: type: type: string enum: - percentage - absolute example: percentage description: represents the type of the discount for that item. value: type: string example: '0.1' description: represents the rate or the absolute amount that will be discounted required: - title - quantity - unit_price - vat_rate Client: oneOf: - $ref: '#/components/schemas/ClientCompany' - $ref: '#/components/schemas/ClientIndividual' ClientCompany: type: object properties: id: type: string format: uuid name: type: string description: represents the name of the client that needs to pay the client invoice. type: type: string enum: - company description: | 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: type: string format: email example: john.doe@qonto.eu description: 'represents the e-mail address of the client that needs to pay the invoice, which is displayed in the invoice.' vat_number: type: string description: represents the Value Added Tax number of the client (a legal entity) that needs to pay the invoice. tax_identification_number: type: string description: "represents the Tax Identification Number of the client (a physical person) that needs to pay the invoice. It corresponds to the SIREN/SIRET for \U0001F1EB\U0001F1F7 companies." address: type: string description: represents the address of the client that needs to pay the invoice. city: type: string description: represents the city of the client that needs to pay the invoice. zip_code: type: string description: represents the zip code of the client that needs to pay the invoice. province_code: type: string description: Only for italian organizations. Represents the province code of the client. country_code: type: string description: represents the country code of the client that needs to pay the invoice. billing_address: type: object description: '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`).' properties: street_address: type: string maxLength: 250 description: | represent the street address section of the billing address of the client. (eg street, number, floor, door, etc) example: 123 Main Street city: type: string maxLength: 50 example: Paris description: represents the city on the billing address of the client that needs to pay the invoice zip_code: type: string maxLength: 20 example: '75009' description: represents the zip code on the billing address of the client that needs to pay the invoice province_code: type: string maxLength: 2 description: represents the province code of the client's billing address country_code: type: string maxLength: 2 example: fr description: represents the country code on the billing address of the client that needs to pay the invoice delivery_address: type: object description: '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`).' properties: street_address: type: string maxLength: 250 description: | represent the street address section of the delivery address of the client. (eg street, number, floor, door, etc) example: 123 Main Street city: type: string maxLength: 50 example: Paris description: represents the city on the delivery address of the client that needs to pay the invoice zip_code: type: string maxLength: 20 example: '75009' description: represents the zip code on the delivery address of the client that needs to pay the invoice province_code: type: string maxLength: 2 description: represents the province code of the client's delivery address that needs to pay the invoice country_code: type: string maxLength: 2 example: fr description: represents the country code on the delivery address of the client that needs to pay the invoice recipient_code: type: string description: Only for italian clients. Represents the client’s recipient code for receiving an the e-invoice in his SdI portal. created_at: type: string description: represents the date the client was created. Note that this is a machine date. locale: type: string example: fr description: 'represents the language of the documents created on Qonto (invoices, quotes, credit notes) for this particular client.' ClientIndividual: type: object properties: id: type: string format: uuid first_name: type: string description: represents the first name of the client that needs to pay the invoice. last_name: type: string description: represents the last name of the client that needs to pay the invoice type: type: string enum: - individual - freelancer description: | 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: type: string format: email example: john.doe@qonto.eu description: 'represents the e-mail address of the client that needs to pay the invoice, which is displayed in the invoice.' vat_number: type: string description: represents the Value Added Tax number of the client (a legal entity) that needs to pay the invoice. tax_identification_number: type: string description: "represents the Tax Identification Number of the client (a physical person) that needs to pay the invoice. It corresponds to the SIREN/SIRET for \U0001F1EB\U0001F1F7 companies." address: type: string description: represents the address of the client that needs to pay the invoice. city: type: string description: represents the city of the client that needs to pay the invoice. zip_code: type: string description: represents the zip code of the client that needs to pay the invoice. province_code: type: string description: Only for italian organizations. Represents the province code of the client. country_code: type: string description: represents the country code of the client that needs to pay the invoice. billing_address: type: object description: '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`).' properties: street_address: type: string maxLength: 250 description: | represent the street address section of the billing address of the client. (eg street, number, floor, door, etc) example: 123 Main Street city: type: string maxLength: 50 example: Paris description: represents the city on the billing address of the client that needs to pay the invoice zip_code: type: string maxLength: 20 example: '75009' description: represents the zip code on the billing address of the client that needs to pay the invoice province_code: type: string maxLength: 2 description: represents the province code of the client's billing address country_code: type: string maxLength: 2 example: fr description: represents the country code on the billing address of the client that needs to pay the invoice delivery_address: type: object description: '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`).' properties: street_address: type: string maxLength: 250 description: | represent the street address section of the delivery address of the client. (eg street, number, floor, door, etc) example: 123 Main Street city: type: string maxLength: 50 example: Paris description: represents the city on the delivery address of the client that needs to pay the invoice zip_code: type: string maxLength: 20 example: '75009' description: represents the zip code on the delivery address of the client that needs to pay the invoice province_code: type: string maxLength: 2 description: represents the province code of the client's delivery address that needs to pay the invoice country_code: type: string maxLength: 2 example: fr description: represents the country code on the delivery address of the client that needs to pay the invoice recipient_code: type: string description: Only for italian clients. Represents the client’s recipient code for receiving an the e-invoice in his SdI portal. created_at: type: string description: represents the date the client was created. Note that this is a machine date. locale: type: string example: fr description: 'represents the language of the documents created on Qonto (invoices, quotes, credit notes) for this particular client.' ClientIndividualCreatePayload: type: object required: - first_name - last_name - type properties: name: type: string maxLength: 250 description: represents the name of the client that needs to pay the client invoice. It is required if type is `company` first_name: type: string maxLength: 60 description: represents the first name of the client that needs to pay the invoice. It is required if type is `individual` or `freelancer` last_name: type: string maxLength: 60 description: represents the last name of the client that needs to pay the invoice. It is required if type is individual or freelancer. type: type: string enum: - individual - company - freelancer description: '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: type: string format: email example: john.doe@qonto.eu description: 'represents the e-mail address of the client that needs to pay the invoice, which is displayed in the invoice.' vat_number: type: string maxLength: 20 description: represents the Value Added Tax number of the client (a legal entity) that needs to pay the invoice. tax_identification_number: type: string maxLength: 30 description: "represents the Tax Identification Number of the client (a physical person) that needs to pay the invoice. It corresponds to the SIREN/SIRET for \U0001F1EB\U0001F1F7 companies." address: type: string maxLength: 250 description: represents the address of the client that needs to pay the invoice. city: type: string maxLength: 50 description: represents the city of the client that needs to pay the invoice. zip_code: type: string maxLength: 20 description: '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: type: string minLength: 2 maxLength: 2 description: |- 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: type: string minLength: 2 maxLength: 2 example: FR description: represents the country code of the client that needs to pay the invoice as a root-level field (ISO 3166 format). billing_address: description: 'represents the 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.' allOf: - $ref: '#/components/schemas/ClientBillingAddress' type: object delivery_address: description: represents the delivery address of the client whose allOf: - $ref: '#/components/schemas/ClientDeliveryAddress' type: object recipient_code: type: string description: 'only for Italian clients. Represents the client’s recipient code, so that the client can receive the e-invoice in his SDI portal.' currency: type: string description: 'represents the client’s currency, supported format is ISO 4217. Required when creating an invoice with this client.' example: EUR locale: type: string description: | 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. example: FR ClientCompanyCreatePayload: type: object required: - name - type properties: name: type: string maxLength: 250 description: represents the name of the client that needs to pay the client invoice. It is required if type is `company` first_name: type: string maxLength: 60 description: represents the first name of the client that needs to pay the invoice. It is required if type is `individual` or `freelancer` last_name: type: string maxLength: 60 description: represents the last name of the client that needs to pay the invoice. It is required if type is individual or freelancer. type: type: string enum: - company description: '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: type: string format: email example: john.doe@qonto.eu description: 'represents the e-mail address of the client that needs to pay the invoice, which is displayed in the invoice.' vat_number: type: string maxLength: 20 description: represents the Value Added Tax number of the client (a legal entity) that needs to pay the invoice. tax_identification_number: type: string maxLength: 30 description: "represents the Tax Identification Number of the client (a physical person) that needs to pay the invoice. It corresponds to the SIREN/SIRET for \U0001F1EB\U0001F1F7 companies." address: type: string maxLength: 250 description: represents the address of the client that needs to pay the invoice. city: type: string maxLength: 50 description: represents the city of the client that needs to pay the invoice. zip_code: type: string maxLength: 20 description: '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: type: string minLength: 2 maxLength: 2 description: |- 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: type: string minLength: 2 maxLength: 2 example: FR description: represents the country code of the client as a root-level field (ISO 3166 format) billing_address: description: 'represents the 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.' allOf: - $ref: '#/components/schemas/ClientBillingAddress' type: object delivery_address: description: represents the delivery address of the client whose allOf: - $ref: '#/components/schemas/ClientDeliveryAddress' type: object recipient_code: type: string description: 'only for Italian clients. Represents the client’s recipient code, so that the client can receive the e-invoice in his SDI portal.' currency: type: string description: 'represents the client’s currency, supported format is ISO 4217. Required when creating an invoice with this client.' example: EUR locale: type: string description: | 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. example: FR ClientBillingAddress: type: object description: '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.' properties: street_address: type: string maxLength: 250 description: | Street address section of the billing address of the client (eg street, number, floor, door, etc). example: 123 Main Street city: type: string maxLength: 50 example: Paris description: City on the billing address of the client zip_code: type: string maxLength: 20 example: '75009' description: Zip code on the billing address of the client province_code: type: string maxLength: 2 description: Province code of the client's billing address. It is required only for Italian organizations. country_code: type: string maxLength: 2 example: FR description: Country code on the billing address of the client (ISO 3166 format) ClientDeliveryAddress: type: object properties: street_address: type: string maxLength: 250 description: | Street address section of the delivery address of the client. (eg street, number, floor, door, etc) example: 123 Main Street city: type: string maxLength: 50 example: Paris description: City on the delivery address of the client zip_code: type: string maxLength: 20 example: '75009' description: Zip code on the delivery address of the client province_code: type: string maxLength: 2 description: Province code of the client's delivery address. It is required only for Italian organizations country_code: type: string maxLength: 2 example: FR description: Country code on the delivery address of the client (ISO 3166 format) ClientCreatePayload: oneOf: - $ref: '#/components/schemas/ClientIndividualCreatePayload' - $ref: '#/components/schemas/ClientCompanyCreatePayload' Beneficiary: type: object required: - id - name - status - trusted - created_at - updated_at properties: id: type: string format: uuid example: ce91bc4e-68d6-4ab0-bfab-4a9403f7f316 name: type: string example: Alice In Wonderland status: type: string enum: - pending - declined - validated example: validated trusted: type: boolean bank_account: type: object properties: iban: type: string bic: type: string currency: type: string account_number: type: string routing_number: type: string intermediary_bank_bic: type: string swift_sort_code: type: string created_at: type: string example: '2021-01-27T22:05:07.000Z' updated_at: type: string example: '2021-01-27T22:05:07.000Z' Currency: type: string enum: - AED - AUD - BGN - CAD - CHF - CNY - CZK - DKK - EUR - GBP - GHS - HKD - HUF - ILS - MXN - NOK - NZD - PEN - PLN - RON - RSD - SAR - SEK - SGD - TRY - USD - ZAR - ZMW example: EUR default: EUR RequestTransfer: type: object description: A transfer of money from one Qonto account to another account properties: id: type: string format: uuid description: ID of the request request_type: type: string enum: - transfer description: Type of the request status: type: string enum: - pending - approved - declined - canceled description: Status of the request initiator_id: type: string format: uuid description: |- ID of the membership that initiated the request.
When the request is initiated through the API, the initiator is the authenticated membership. approver_id: type: string format: uuid description: ID of the membership that approved the request nullable: true note: type: string description: Reason for the request declined_note: type: string description: Reason why the request was declined nullable: true creditor_name: type: string description: Name of the beneficiary amount: type: string description: 'Amount of the transfer, example "152.25"' currency: type: string description: Currency of the transfer. ISO-4217 3-characters currency code scheduled_date: type: string format: date description: 'When transfer would be executed. If request is approved after this date, it will be executed immediately' recurrence: type: string enum: - weekly - monthly description: 'Tells if transfer is recurring, null if it is not' nullable: true last_recurrence_date: type: string format: date-time description: Date of the last recurrence nullable: true processed_at: type: string format: date-time description: 'When request was approved, canceled or declined' nullable: true created_at: type: string format: date-time description: When request was created RequestMultiTransfer: type: object description: Several transfers executed at the same time. Several format can be provided to create a bulk transfer which is composed of many different transfers properties: id: type: string format: uuid description: ID of the request request_type: type: string enum: - multi_transfer description: Type of the request status: type: string enum: - pending - approved - declined - canceled description: Status of the request initiator_id: type: string format: uuid description: |- ID of the membership that initiated the request.
When the request is initiated through the API, the initiator is the authenticated membership. approver_id: type: string format: uuid description: ID of the membership that approved the request nullable: true note: type: string description: Reason for the request declined_note: type: string description: Reason why the request was declined nullable: true total_transfers_amount: type: string description: 'Total amount of the transfers, example "2152.25"' total_transfers_amount_currency: type: string description: Currency of the transfers. ISO-4217 3-characters currency code total_transfers_count: type: integer minimum: 1 description: Number of transfers scheduled_date: type: string format: date description: 'When transfers would be executed. If request is approved after this date, they will be executed immediately' processed_at: type: string format: date-time description: 'When request was approved, canceled or declined' nullable: true created_at: type: string format: date-time description: When request was created RequestFlashCard: type: object description: A virtual card with a budget and a last day of validity. The card becomes inactive after the budget is totally spent or the last date of validity is past properties: id: type: string format: uuid description: ID of the request request_type: type: string enum: - flash_card description: Type of the request status: type: string enum: - pending - approved - declined - canceled description: Status of the request initiator_id: type: string format: uuid description: |- ID of the membership that initiated the request.
When the request is initiated through the API, the initiator is the authenticated membership. approver_id: type: string format: uuid description: ID of the membership that approved the request nullable: true note: type: string description: Reason for the request declined_note: type: string description: Reason why the request was declined nullable: true pre_expires_at: type: string format: date-time description: When the flash card expires payment_lifespan_limit: type: string description: Total of payment limit until card expires currency: type: string description: Currency of the card and its limits. ISO-4217 3-characters currency code processed_at: type: string format: date-time description: 'When request was approved, canceled or declined' nullable: true created_at: type: string format: date-time description: When request was created Error: oneOf: - $ref: '#/components/schemas/BadRequestError' - $ref: '#/components/schemas/UnauthorizedError' - $ref: '#/components/schemas/ForbiddenError' - $ref: '#/components/schemas/NotFoundError' type: object RequestVirtualCard: type: object description: 'A virtual card with a monthly budget. Card holder can spend that amount every calendar month. Above that, transactions will be refused' properties: id: type: string format: uuid description: ID of the request request_type: type: string enum: - virtual_card description: Type of the request status: type: string enum: - pending - approved - declined - canceled description: Status of the request initiator_id: type: string format: uuid description: |- ID of the membership that initiated the request.
When the request is initiated through the API, the initiator is the authenticated membership. approver_id: type: string format: uuid description: ID of the membership that approved the request nullable: true note: type: string description: Reason for the request declined_note: type: string description: Reason why the request was declined nullable: true payment_monthly_limit: type: string description: Total of payment limit by month currency: type: string description: Currency of the card and its limits. ISO-4217 3-characters currency code processed_at: type: string format: date-time description: 'When request was approved, canceled or declined' nullable: true created_at: type: string format: date-time description: When request was created UnauthorizedError: type: object x-examples: Invalid credentials: code: unauthorized detail: Invalid credentials required: - code - detail properties: code: type: string description: Error code. detail: type: string description: Human readable error that explains error `code`. BadRequestError: type: object x-examples: Authorization field missing: code: bad_request detail: Authorization field missing required: - code - detail properties: code: type: string description: Error code. detail: type: string description: Human readable error that explains error `code`. source: type: object properties: pointer: type: string description: The field and the item in an array (if applicable) that causes the error. ForbiddenError: type: object x-examples: Insufficient permissions: code: forbidden detail: User does not have sufficient permissions for this action. required: - code - detail properties: code: type: string description: Error code. detail: type: string description: Human readable error that explains error `code`. NotFoundError: type: object x-examples: Object not found: code: not_found detail: Object not found source: parameter: id required: - code - detail properties: code: type: string description: Error code. detail: type: string description: Human readable error that explains error `code`. source: type: object properties: parameter: type: string description: The parameter that causes the error. Transaction: type: object x-examples: Transaction from a Qonto bank account: id: 01910d82-014a-7783-b40c-41021851726e transaction_id: cooperative-boulangere-sud-2161-1-transaction-1910d8-20148 amount: 1425.6 amount_cents: 142560 settled_balance: 41995921.54 settled_balance_cents: 4199592154 attachment_ids: [] logo: small: 'https://qonto.com/customized-qonto-brand-logos/small.png' medium: 'https://qonto.com/customized-qonto-brand-logos/medium.png' local_amount: 1425.6 local_amount_cents: 142560 side: debit operation_type: qonto_fee currency: EUR local_currency: EUR label: Qonto settled_at: '2024-08-01T10:35:09.027Z' emitted_at: '2024-08-01T10:35:07.526Z' updated_at: '2024-08-01T10:35:09.512Z' status: completed note: null reference: null vat_amount: 237.6 vat_amount_cents: 23760 vat_rate: 20 initiator_id: null label_ids: [] attachment_lost: false attachment_required: true card_last_digits: null category: subscription subject_type: BillingTransfer bank_account_id: e97d6e4b-8179-47ae-88e9-3e43b230251e is_external_transaction: false Transaction from an external account.: id: 0191221f-258b-7bac-b83e-235fe00ff591 transaction_id: cooperative-boulangere-sud-2161-4-transaction-191221-f2535 amount: 11.99 amount_cents: 1199 settled_balance: null settled_balance_cents: null attachment_ids: [] logo: small: 'https://qonto.com/customized-qonto-brand-logos/small.png' medium: 'https://qonto.com/customized-qonto-brand-logos/medium.png' local_amount: 11.99 local_amount_cents: 1199 side: debit operation_type: other currency: EUR local_currency: EUR label: Arcade Software Inc. clean_counterparty_name: Arcade Software settled_at: '2024-06-25T00:00:00.000Z' emitted_at: '2024-06-25T00:00:00.000Z' updated_at: '2024-08-05T10:39:12.181Z' status: completed note: null reference: null vat_amount: null vat_amount_cents: null vat_rate: null initiator_id: null label_ids: [] attachment_lost: false attachment_required: true card_last_digits: null category: other_expense subject_type: Other bank_account_id: 0191221f-2452-735f-9144-bff2ca4fa8a4 is_external_transaction: true properties: id: type: string description: UUID of the transaction. transaction_id: type: string amount: type: number format: float description: Amount of the transaction in the currency of the bank account. example: '10,00' amount_cents: type: integer description: Amount of the transaction in the currency of the bank account. example: 1000 settled_balance: type: number nullable: true settled_balance_cents: type: integer default: 0 nullable: true attachment_ids: type: array description: 'Array of UUIDs, corresponding to the attachments (up to 5) uploaded on the transaction. You can obtain details for each attachment using [Get attachment](/reference/openapi_v2.yml/paths/~1v2~1attachments~1%7Bid%7D/get).' items: type: string nullable: true logo: type: object description: Object containing URLs to small and medium-sized logos associated with the transaction. properties: small: x-stoplight: id: 4xsjk3ldusyox type: string medium: type: string x-stoplight: id: bhxohlyhos6is local_amount: type: number format: float description: Amount of the transaction in the **foreign currency** (if any). example: '10,87' local_amount_cents: type: integer example: 1087 description: Amount of the transaction in the **foreign currency** (if any). side: type: string description: |- - `credit`: incoming transaction - `debit`: outgoing transaction operation_type: type: string description: |- - `income`: an incoming transfer - `transfer`: an outgoing transfer - `card`: a card payment - `direct_debit`: a SEPA Direct Debit (payments collected from you by other businesses) - `direct_debit_collection`: a SEPA Direct Debit Collection (payments collected from other businesses by you) - `direct_debit_hold`: a hold for a Direct Debit Collection, or its release - `qonto_fee`: a Qonto fee (subscription, atm withdrawal, fx card...) - `cheque`: a Check cashed on the account - `recall`: recall of an incoming transfer (by the emitter beneficiary or bank) - `swift_income`: a SWIFT incoming transfer - `pay_later`: a transaction related to financing - `financing_installment`: a transaction related to an installment of a financed transfer - `other`: an external transaction for which the type of transaction is unknown currency: type: string description: | `euros` is the only bank account currency supported by Qonto. local_currency: type: string example: USD label: type: string description: Name of the counterparty of the transaction. clean_counterparty_name: type: string description: Simplified and standardized version of the counterparty's name. settled_at: type: string description: |- Date and time, in UTC, at which the transaction was finally committed to the account, and got set to a `completed` status.
Do note: the `settled_at` value can be `null`, for transaction which aren't `completed` (i.e. `pending`, `reversed` and `declined`). nullable: true emitted_at: type: string description: 'Date and time, in UTC, at which the transaction was first authorized and recorded on the bank account.' updated_at: type: string description: 'Date and time, in UTC, at which the transaction object was last updated (any state change will trigger a bump of this timestamp).' status: type: string note: type: string nullable: true reference: type: string nullable: true vat_amount: type: number format: float description: Amount aggregate for all the VAT. nullable: true vat_amount_cents: type: integer description: Amount aggregate for all the VAT. nullable: true vat_rate: type: number format: float example: 10 description: 'Rate selected or detected. The value can be `-1` for uncategorized rate (e.g in France any value which is not in `0`, `2.1`, `5.5`, `10`, `20`) or for transactions with multiple VAT.' nullable: true initiator_id: type: string nullable: true label_ids: type: array description: '`id` of the custom label that user can add on a transaction for categorization purposes. These labels are accessible using the [Show Label endpoint](https://api-doc.qonto.com/docs/business-api/b3A6ODQxOTQyMg-show-label).' items: type: string nullable: true attachment_lost: type: boolean description: Sets to `true` if the attachment of the transaction was marked as lost. attachment_required: type: boolean description: Sets to `true` if the attachment of the transaction was marked as required. card_last_digits: type: string nullable: true category: type: string description: |- Possible values:
`restaurant_and_bar` `food_and_grocery` `transport` `gas_station` `hotel_and_lodging` `it_and_electronics` `hardware_and_equipment` `office_supply` `office_rental` `utility` `insurance` `logistics` `online_service` `legal_and_accounting` `finance` `tax` `salary` `marketing` `manufacturing` `atm` `other_service` `other_expense` `treasury_and_interco` `sales` `other_income` `refund` `fees` `subscription` `voucher` `fallback` `pending` subject_type: type: string description: | Identifies the type of transaction and maps to the nested additional fields with specific transaction data. Not to confuse with the attribute `operation_type` (explained above) which is a more specific categorisation of a transaction. Values: - `Card`: a card payment - `Transfer`: an outgoing transfer - `Income`: an incoming transfer - `DirectDebit`: a SEPA Direct Debit (payments collected from you by other businesses) - `DirectDebitCollection`: a SEPA Direct Debit Collection (payments collected from other businesses by you) - `DirectDebitHold`: a hold for a Direct Debit Collection, or its release - `WalletToWallet`: a transfer between two Qonto accounts - `Check`: a Check cashed on the account - `SwiftIncome`: a SWIFT incoming transfer - `PagopaPayment`: for electronic payments to central and local public administration entities - `F24Payment`: regulatory report in Italy that is used to pay taxes and social security to state entities - `BillingTransfer`: a transfer related to the billing of a Qonto account - `FinancingIncome`: financing for a transfer - `FinancingInstallment`: a repayment of the financing - `Other`: an external transaction for which the type of transaction is unknown For the subject types `DirectDebit`, `DirectDebitCollection`, `DirectDebitHold`, `Income`, `SwiftIncome`, `Transfer`, `Check`, `PagopaPayment` and `FinancingInstallment`, you will find a nested object (e.g. `direct_debit`) with additional fields. bank_account_id: type: string is_external_transaction: type: boolean description: 'Sets to `true` for transactions related to external bank accounts (cf. https://support-fr.qonto.com/hc/en-us/articles/24231375285777-How-to-connect-my-external-accounts-to-my-Qonto-interface).' attachments: type: array description: 'Use the following parameter to include `attachments` in the response: `includes[]=attachments`.' nullable: true items: x-stoplight: id: xxvtj4z2idcjs type: object properties: id: type: string x-stoplight: id: jfbvpqicts9dp description: UUID of the attachment. created_at: type: string x-stoplight: id: meqsutk4kqh4u file_name: type: string x-stoplight: id: 6u14eifg9dwl0 file_size: type: string x-stoplight: id: 0c6wag3117ht8 file_content_type: type: string x-stoplight: id: ty2fnzkdvpkfo url: type: string x-stoplight: id: 0hcvw24df1yp3 probative_attachment: type: object x-stoplight: id: rijldvngy2qsk properties: status: type: string x-stoplight: id: olfxj9xyo0ka3 labels: type: array x-stoplight: id: bofm6kwiz80cq description: 'Use the following parameter to include `labels` in the response: `includes[]=labels`.' items: x-stoplight: id: hp0fg35eqq4fl type: object properties: id: type: string x-stoplight: id: fndk5lisse4oy description: UUID of the label. name: type: string x-stoplight: id: 6v95c59lj4aav parent_id: type: string x-stoplight: id: 0gojuselmz6oo vat_details: type: object x-stoplight: id: vnjdok0qy09o7 description: 'Use the following parameter to include `vat_details` in the response: `includes[]=vat_details`.' properties: items: type: array x-stoplight: id: 3jfyuknrb9rhz description: One item for each specific VAT line. items: x-stoplight: id: iz5w649za9pb4 type: object properties: amount: type: string x-stoplight: id: rfctqzwb2tvcv amount_cents: type: string x-stoplight: id: z4f10m5u3kpsf amount_excluding_vat: type: string x-stoplight: id: vefzz00j0v2w6 amount_excluding_vat_cents: type: string x-stoplight: id: mobhizrsc5ikg rate: type: string x-stoplight: id: jwi92sinjm4wi description: 'Rate selected or detected. The value can be `-1` for uncategorized rate (e.g in France any value which is not in `0, 2.1, 5.5, 10, 20`).' transfer: type: object nullable: true properties: counterparty_account_number: type: string description: | Account number of the transaction’s counterparty. Might be empty for external transaction (i.e. when `is_external_transaction == true`). counterparty_account_number_format: type: string description: |- Account number format of the transaction’s counterparty. Possible values are: - `IBAN`; - Empty for external transaction (i.e. when `is_external_transaction == true`) **without IBAN**. counterparty_bank_identifier: type: string description: Bank identifier of the transaction’s counterparty. Might be empty for external transaction (i.e. when `is_external_transaction == true`). counterparty_bank_identifier_format: type: string description: |- Bank identifier format of the transaction’s counterparty. Possible values are: - `SWIFT_BIC`; - Empty for external transaction (i.e. when `is_external_transaction == true`) **without BIC**. income: type: object nullable: true properties: counterparty_account_number: type: string description: Account number of the transaction’s counterparty. Might be empty for external transaction (i.e. when `is_external_transaction == true`). counterparty_account_number_format: type: string description: |- Account number format of the transaction’s counterparty. Possible values are: - `IBAN`; - Empty for external transaction (i.e. when `is_external_transaction == true`) **without IBAN**. counterparty_bank_identifier: type: string description: Bank identifier of the transaction’s counterparty. Might be empty for external transaction (i.e. when `is_external_transaction == true`). counterparty_bank_identifier_format: type: string description: |- Bank identifier format of the transaction’s counterparty. Possible values are: - `SWIFT_BIC`; - Empty for external transaction (i.e. when `is_external_transaction == true`) **without BIC**. swift_income: type: object nullable: true properties: counterparty_account_number: type: string description: Account number of the transaction’s counterparty. Might be empty for external transaction (i.e. when `is_external_transaction == true`). counterparty_account_number_format: type: string description: |- Account number format of the transaction’s counterparty. Possible values are: - `unstructured`; - Might be empty for external transaction (i.e. when `is_external_transaction == true`). counterparty_bank_identifier: type: string description: Bank identifier of the transaction’s counterparty. Might be empty for external transaction (i.e. when `is_external_transaction == true`). counterparty_bank_identifier_format: type: string description: |- Bank identifier format of the transaction’s counterparty. Possible values are: - `sort_code`; - Might be empty for external transaction (i.e. when `is_external_transaction == true`). direct_debit: type: object nullable: true properties: counterparty_account_number: type: string description: Account number of the transaction’s counterparty. Might be empty for external transaction (i.e. when `is_external_transaction == true`). counterparty_account_number_format: type: string description: | Account number format of the transaction’s counterparty. Possible values are: - `IBAN`; - Empty for external transaction (i.e. when `is_external_transaction == true`) **without IBAN**. counterparty_bank_identifier: type: string description: Bank identifier of the transaction’s counterparty. Might be empty for external transaction (i.e. when `is_external_transaction == true`). counterparty_bank_identifier_format: type: string description: |- Bank identifier format of the transaction’s counterparty. Possible values are: - `SWIFT_BIC`; - Empty for external transaction (i.e. when `is_external_transaction == true`) **without BIC**. check: type: object nullable: true properties: check_number: type: string check_key: type: string financing_installment: type: object nullable: true properties: total_installments_number: type: integer description: Installment of the current transaction. current_installment_number: type: integer description: Total number of installments. pagopa_payment: type: object nullable: true properties: notice_number: type: string description: 'Code in the PagoPA Payment Advice that identifies the payment notice, to be used for payments with PagoPA (i.e. codice_avviso).' creditor_fiscal_code: type: string description: 'Code in the PagoPA Payment Notice that identifies the creditor institution, to be used for PagoPA payments (i.e. codice_ent)' iuv: type: string description: Unique Payment Identifier (UPI) is the code that uniquely identifies exclusively a requested payment. direct_debit_collection: type: object nullable: true properties: counterparty_account_number: type: string description: Account number of the transaction’s counterparty. counterparty_account_number_format: type: string description: Account number format of the transaction’s counterparty. counterparty_bank_identifier: type: string description: Bank identifier of the transaction’s counterparty. counterparty_bank_identifier_format: type: string description: Bank identifier format of the transaction’s counterparty. direct_debit_hold: type: object nullable: true properties: guarding_rate: type: string Statement: type: object x-examples: Example 1: id: d52c7176-3ab8-4607-92a3-a1a488397b91 bank_account_id: 1430043d-0227-4fdd-a970-45afd165676f period: 05-2024 file: file_name: Foobar file_size: '666' file_content_type: image/png file_url: 'https://my-s3.url.qonto.bucket.com/123456789' required: - id - bank_account_id - period - file properties: id: type: string description: Unique identifier of the statement. example: 08544790-6305-4a85-8487-e035290bcee8 bank_account_id: type: string x-stoplight: id: kmqtiqbwbzl5k example: 9f4af770-344b-42c1-a592-6a2adf82a6d3 description: Unique identifier of the bank account associated to the statement. period: type: string description: Month of the statement with the `MM-YYYY` format. example: 08-2024 file: type: object required: - file_name - file_content_type - file_size - file_url properties: file_name: type: string description: Name of the statement file file_content_type: type: string description: Type of the statement file example: application/pdf file_size: type: string description: Size of the statement file example: '16966' file_url: type: string description: Link to downlaod the statement file. **The url expires after 30 minutes**. InsuranceContractPartnerData: type: object description: Insurance contract data provided by Partner properties: name: type: string description: Name of the insurance contract signed by the customer example: ProLiability Plan 2024 contract_id: type: string description: ID of the contract created by partner example: '12345' origin: type: string description: Insurance contract origin enum: - insurance_hub - qonto_other - stello example: insurance_hub provider_slug: type: string description: Identifier representing insurance provider example: axa type: type: string description: Defined category of insurance taken by the customer example: business_liability status: type: string description: Insurance contract status enum: - active - pending_payment - pending_others - action_required - expired - archived example: active troubleshooting_url: type: string description: Link for troubleshooting when contract status is not active example: 'https://patner.com/troubleshoot' service_url: type: string description: Static link for customer to access their insurance management portal example: 'https://partner.com/service' expiration_date: type: string format: date description: Date when the contract terminates unless it is renewed example: '2025-12-31' start_date: type: string description: Date when the insurance contract becomes active and coverage begins example: '2024-12-31' renew_date: type: string description: Date when the policy is scheduled for renewal example: '2025-12-31' payment_frequency: type: string description: Payment frequency enum: - month - quarter - annual example: month price: type: object description: Price of the insurance properties: value: type: string example: '99.99' currency: type: string example: EUR InsuranceContractCreatePayload: type: object required: - insurance_contract properties: insurance_contract: allOf: - $ref: '#/components/schemas/InsuranceContractPartnerData' required: - name - contract_id - origin - provider_slug - type - status - start_date - payment_frequency - price InsuranceContract: type: object required: - insurance_contract properties: insurance_contract: allOf: - type: object properties: id: type: string description: UUID of the insurance contract example: 888e4567-e89b-12d3-a456-426614174123 - $ref: '#/components/schemas/InsuranceContractPartnerData' InsuranceContractWithDocuments: type: object required: - insurance_contract properties: insurance_contract: allOf: - type: object properties: id: type: string description: UUID of the insurance contract example: 888e4567-e89b-12d3-a456-426614174123 - $ref: '#/components/schemas/InsuranceContractPartnerData' - type: object properties: documents: type: array description: Insurance document(s) attached to the contract items: type: object properties: id: type: string format: uuid description: UUID of the attachment example: 123e4567-e89b-12d3-a456-426614174000 name: type: string example: Contract Axa description: The name of the file type: type: string example: contract description: Type of the file InsuranceContractUpdatePayload: type: object required: - insurance_contract properties: insurance_contract: allOf: - $ref: '#/components/schemas/InsuranceContractPartnerData' UnprocessableEntityError: type: object x-stoplight: id: 467728c911962 x-examples: Missing attribute: code: missing_key detail: attribute is missing source: pointer: /external_transfer/atrribute required: - code - detail properties: status: type: string x-stoplight: id: pu86dvuefs112 code: type: string description: Error code. detail: type: string description: Human readable error that explains error `code`. message: type: string x-stoplight: id: iy38mftd2hy1j source: type: object properties: pointer: type: string x-stoplight: id: opugvzqqyfsrx description: The attribute and the item in an array (if applicable) that causes the error. parameters: X-Qonto-Staging-Token: name: X-Qonto-Staging-Token in: header schema: type: string description: 'Required only for Sandbox API requests; to get one, please submit the following form: https://getqonto.atlassian.net/servicedesk/customer/portal/5/group/47/create/143. ' responses: 400-Bad-request: description: Returns a bad request error. content: application/json: schema: type: object properties: errors: type: array x-stoplight: id: tg6joa8xbwn3j items: type: object $ref: '#/components/schemas/BadRequestError' examples: Authorization field missing: value: errors: - code: bad_request detail: Authorization field missing 401-Unauthorized: description: Returns an unauthorized error. content: application/json: schema: type: object x-examples: Example 1: errors: - code: unauthorized detail: Invalid credentials properties: errors: type: array items: type: object $ref: '#/components/schemas/UnauthorizedError' examples: Invalid credentials: value: errors: - code: unauthorized detail: Invalid credentials 403-Forbidden: description: Returns a forbidden error. content: application/json: schema: type: object x-examples: Example 1: errors: - code: forbidden detail: User does not have sufficient permissions for this action. properties: errors: type: array items: type: object $ref: '#/components/schemas/ForbiddenError' examples: Insufficient permissions: value: errors: - code: forbidden detail: User does not have sufficient permissions for this action. 404-Not-found: description: Returns a not found error. content: application/json: schema: type: object x-examples: Example 1: errors: - code: not_found detail: client invoice not found source: parameter: id properties: errors: type: array items: type: object $ref: '#/components/schemas/NotFoundError' examples: Client invoice not found: value: errors: - code: not_found detail: Client invoice not found source: parameter: id 422-Unprocessable-entity: description: Returns an unprocessable entity error. content: application/json: schema: type: object x-examples: Example 1: errors: - code: missing_key detail: reference is missing source: pointer: /external_transfer/reference properties: errors: type: array items: type: object $ref: '#/components/schemas/UnprocessableEntityError' examples: Invalid id: value: errors: - status: '422' code: invalid detail: invoice_id is missing or invalid message: invoice_id is missing or invalid security: - OAuth: - organization.read - membership.read - membership.write - attachment.write - internal_transfer.write - payment.write - supplier_invoice.write - supplier_invoice.read - client_invoices.read - client_invoice.write - client.read - client.write - request_review.write - request_review.read - team.read - team.write - request_transfers.write - insurance_contract.read - insurance_contract.write - card.read - card.write - SecretKey: []