Interface: GetBeneficiariesResponse

beneficiaries

meta?

Properties

Qonto

Welcome to Qonto Developers

Step-by-step guide to build, test and release your integration.

Developer guidelines

Learn how to leverage Qonto Embed to supercharge your platform with embedded financial services.

Qonto Embed sample app

Partnering with Qonto

Qonto Embed

Adding payments

Card management

Guidelines

Common issues

Support portal

Introduction

Access Qonto banking, invoicing, bookkeeping & more remotely

Overview

URLs

Fast track your customers' onboarding to Qonto.

Authentication

Integrate Qonto banking features into your web application with less effort

April

March

February

January

Olinda operates the Qonto application along with its supporting infrastructure which allows professional clients to open a payment account and execute payment transactions.

Security measures

API License Agreement

Get started

Authentication to the API is performed via HTTP, using the `Authorization` header. API requests without authentication will fail.

When using the API, you can authenticate a Qonto account using its `login` and `secret key` in the request (cf. header below).

API key

TPP identification through PSD2 QSeal certificate

Company Creation flow

OAuth scope: `organization.read`

---
Get a single external transfer.

---

## Attributes details

##### Initiator ID
ID of the membership that initiated the external transfer.
<br/>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.


Show an external transfer

OAuth scope: `organization.read`

---
Retrieve a list of external transfers.

---

## Attributes details

##### Initiator ID
ID of the membership that initiated the external transfer.
<br/>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`)


List external transfers

OAuth scope: `payment.write`

---

Automated creation of a standard external transfer with no user interaction involved once the beneficiary is trusted.

> **Only standard transfers** are supported by this endpoint for now 👉 instant transfers are **not** supported by this endpoint.

---
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**


Create an external transfer with trusted beneficiary

OAuth scope: `payment.write`


**Accessible only using [Strong Customer Authentication](https://api-doc.qonto.com/docs/business-api/ZG9jOjI5MDg3NzA4-strong-customer-authentication)**.
💡 Example of SCA usage: [**Postman visual flow**](https://www.postman.com/qontoteam/workspace/qonto-public-api/flow/6670429eb7bd63003156bd57)

---

**Solo basic plans**

- Create a single standard external transfer with creditor data.
- **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.

**Rest of plans**

Create a maximum of 400 standard external transfers with creditor data.
This 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.

> **Only standard transfers** are supported by this endpoint for now 👉 instant transfers are **not** supported by this endpoint.
---

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.

When 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.

## Max number of transfers : 400

## Attributes details

##### Initiator ID
ID of the membership that initiated the external transfer.
<br/>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 creditor will receive.
- `credit_amount_cents`: The amount that the creditor will receive in an integer format.
- `credit_currency`: Equals debit currency if issued in the SEPA network (only supported currencies). ISO 4217 format.

##### 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.

## Request parameter details

##### Idempotency_key

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.

The `idempotency_key` must be the same for all the call sequence used during the SCA flow :

- For each transfer, The `idempotency_key` is first set on the initial call, which will trigger the SCA flow.
- The **same** `idempotency_key` **must** be used on the final call that includes the SCA token.

This is so because the two calls are actually related to the **same transfer**.

##### 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 `140` characters

##### Debit iban
* `debit_iban`: IBAN of account to debit

##### Creditor
* `credit_iban`: IBAN of account to credit
* `credit_account_name`: The name of the credit account
* `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.

##### 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**


Create external transfers with beneficiary data

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`)


List beneficiaries

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.


Show beneficiary

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`.


Untrust a list of beneficiaries

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.

Upload attachment

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


List memberships

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

Get details of a single membership

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.

Create and invite a new membership

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).

Get organization and its bank accounts

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.


List attachments in a transaction

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.

Upload attachment to a transaction

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.

Remove all attachments from a transaction

OAuth scope: `organization.read`

---

Retrieves 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) 👇)


List transactions

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.

Show transaction

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.


Create multi transfer request

OAuth scope: `request_review.write`

**Accessible only using [Strong Customer Authentication](https://api-doc.qonto.com/docs/business-api/ZG9jOjI5MDg3NzA4-strong-customer-authentication)**.

💡 Example of SCA usage: [**Postman visual flow**](https://www.postman.com/qontoteam/workspace/qonto-public-api/flow/6670429eb7bd63003156bd57)

---

This 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)

Inside Qonto, requests can be listed and approved in the Requests tab.

The impacted request will change status from `status` = `pending` to `status` = `approved`.

---

**`request_type`** can take 4 different values:

- **`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.
- **`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.
- **`transfers`**: a transfer of money from one Qonto account to another account.
- **`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.

Approve a request

OAuth scope: `request_review.write`

---

This 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)

Inside Qonto, requests can be listed and declined in the Requests tab.

The impacted request will change status from `status` = `pending` to `status` = `declined`.

---

**`request_type`** can take 4 different values:

- **`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.
- **`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.
- **`transfers`**: a transfer of money from one Qonto account to another account.
- **`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.

---

Decline a request

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).


Get a list of supplier invoices for an organization

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.


Create supplier invoices with attachments

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).


List client invoices

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.

---

Create a client invoice

OAuth scope: `client_invoices.read`

---

Retrieves a single client invoice.

Show client invoice

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).


Get a list of credit notes for an organization

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
- `invoice_issue_date` represents the invoice_id's issue date


Get details of credit note for an organization

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.

Get client's details

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).

Get a list of clients

OAuth scope: `client.write`

------

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

------

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

-----

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

----

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

> 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.


Create a client

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).

List teams in an organization

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.

Create a new team

OAuth scope: `organization.read`

---
Retrieves a single statement.


Show statement

OAuth scope: `organization.read`

---
Retrieves the list of statements for the authenticated organization.


List statements

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.

Create a new insurance contract

OAuth scope: `insurance_contract.read`

---

This endpoint allows you to retrieve a insurance contract by its ID.

Get insurance contract

OAuth scope: `insurance_contract.write`

---

This endpoint allows you to update an existing insurance contract by its ID.

Update an insurance contract

OAuth scope: `insurance_contract.write`

---

This endpoint allows you to upload a PDF file representing a document for a specific insurance contract.

Upload a PDF document for a specific insurance contract

OAuth scope: `insurance_contract.write`

---

This endpoint allows you to delete a previously uploaded document from a insurance contract.

Delete uploaded document

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.

List cards

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. Currently only creation of virtual cards is supported.

Create a new Virtual (virtual, flash, advertising) card

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.

Retrieve card data view URL

Retrieve all registrations for the current partner


List Registrations

Create a Registration

Retrieve a Registration

⚠️ SUPPORTED ONLY FOR REGISTRATIONS IN COMPANY CREATION FLOW (`legal_flow` = `company_creation`).

Trigger an owner email containing their redirection link.


Trigger an owner email containing their redirection link.

⚠️ SUPPORTED ONLY FOR REGISTRATIONS IN COMPANY CREATION FLOW (`legal_flow` = `company_creation`).

Lists files owned by this partner.


List Files

⚠️ SUPPORTED ONLY FOR REGISTRATIONS IN COMPANY CREATION FLOW (`legal_flow` = `company_creation`).

Create a File.

The Openapi format is somewhat limited in specifying file uploads, but more information can be found in [the Openapi file upload documentation](https://swagger.io/docs/specification/describing-request-body/file-upload/#multipart)


Create a File

⚠️ SUPPORTED ONLY FOR REGISTRATIONS IN COMPANY CREATION FLOW (`legal_flow` = `company_creation`).

Retrieve a File.


Retrieve a File

⚠️ SUPPORTED ONLY FOR REGISTRATIONS IN COMPANY CREATION FLOW (`legal_flow` = `company_creation`).

Delete a File.


Delete a File

⚠️ SUPPORTED ONLY FOR REGISTRATIONS IN COMPANY CREATION FLOW (`legal_flow` = `company_creation`).

Download a File.


Qonto APIs

Business API

Onboarding API

Qonto Embed Web SDK

GetBeneficiariesResponse

Interface: GetBeneficiariesResponse

Properties

beneficiaries

meta?

Qonto APIs

Business API

Onboarding API

Qonto Embed Web SDK

​Interface: GetBeneficiariesResponse

​Properties

​beneficiaries

​meta?

Interface: GetBeneficiariesResponse

Properties

beneficiaries

meta?