> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List beneficiaries
>
This endpoint will be sunsetted on March 31, 2026.
For SEPA beneficiaries, please use the [List SEPA beneficiaries](/api-reference/business-api/payments-transfers/sepa-transfers/beneficiaries/sepa-beneficiaries) endpoint instead.
For international beneficiaries, please use the [List international beneficiaries](/api-reference/business-api/payments-transfers/international-transfers/list-beneficiaries-by-currency) endpoint instead.
OAuth scope: `organization.read`
Retrieves the list of beneficiaries for the authenticated organization.
You can filter (ex: only retrieve the latest beneficiaries) and sort this list by using [query parameters](#Query-Parameters) 👇
## OpenAPI
````yaml get /v2/beneficiaries
openapi: 3.1.1
info:
version: v2
title: Qonto
servers:
- url: https://thirdparty.qonto.com
description: Production URL
- url: https://thirdparty-sandbox.staging.qonto.co
description: Sandbox URL
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
- product.read
- product.write
- request_review.write
- request_review.read
- team.read
- team.write
- request_transfers.write
- insurance_contract.read
- insurance_contract.write
- card.read
- card.write
- bank_account.write
- beneficiary.trust
- webhook
- payment_link.write
- payment_link.read
- sepa_direct_debit.read
- sepa_direct_debit.write
- terminal.read
- terminal.write
- SecretKey: []
paths:
/v2/beneficiaries:
get:
tags:
- Beneficiaries
summary: List beneficiaries
description: >
This endpoint will be sunsetted on March 31, 2026.
For SEPA beneficiaries, please use the [List SEPA beneficiaries](/api-reference/business-api/payments-transfers/sepa-transfers/beneficiaries/sepa-beneficiaries) endpoint instead.
For international beneficiaries, please use the [List international beneficiaries](/api-reference/business-api/payments-transfers/international-transfers/list-beneficiaries-by-currency) endpoint instead.
OAuth scope: `organization.read`
Retrieves the list of beneficiaries for the authenticated organization.
You can filter (ex: only retrieve the latest beneficiaries) and sort
this list by using [query parameters](#Query-Parameters) 👇
operationId: list_beneficiaries
parameters:
- $ref: '#/components/parameters/X-Qonto-Staging-Token'
- name: trusted
in: query
description: Beneficiaries can be filtered by their `trusted` field.
required: false
schema:
type: boolean
- name: status[]
in: query
description: >-
Beneficiaries can be filtered by their `status`. This filter accepts
an array of statuses.
required: false
schema:
type: array
items:
type: string
enum:
- pending
- validated
- declined
default: validated
example: pending
example: status[]=pending&status[]=validated&status[]=declined
- name: iban[]
in: query
description: >-
Beneficiaries can be filtered by their `iban`. This filter accepts
an array of IBANs as value.
required: false
schema:
type: array
items:
type: string
example: FR7616798000010000005663951
- name: updated_at_from
in: query
description: >-
Beneficiaries can be filtered by their `updated_at` property. This
filter can be used in combination with the `updated_at_to` query
parameter to get beneficiaries updated within a specific timeframe.
Please use a valid date time format (**ISO 8601** for instance).
required: false
schema:
type: string
format: date-time
example: '2019-01-10T11:47:53.123Z'
- name: updated_at_to
in: query
description: >-
Beneficiaries can be filtered by their `updated_at` property. This
filter can be used in combination with the `updated_at_from` query
parameter to get beneficiaries updated within a specific timeframe.
Please use a valid date time format (**ISO 8601** for instance).
required: false
schema:
type: string
format: date-time
example: '2019-01-10T11:47:53.123Z'
- name: sort_by
in: query
description: >-
Beneficiaries can be sorted by their `updated_at` property in 2
possible orders: `asc` (Ascending) / `desc` (Descending).
schema:
type: string
enum:
- updated_at:desc
- updated_at:asc
format: property:order
default: updated_at:desc
- name: page
in: query
description: Returned page (cf. [Pagination](/get-started/general/pagination)).
schema:
type: string
- name: per_page
in: query
description: >-
Number of beneficiaries per page (cf.
[Pagination](/get-started/general/pagination)).
schema:
type: string
responses:
'200':
description: >-
Returns the list of beneficiaries for the authenticated
organization.
content:
application/json:
schema:
type: object
properties:
beneficiaries:
type: array
items:
$ref: '#/components/schemas/Beneficiary'
meta:
$ref: '#/components/schemas/Pagination'
required:
- beneficiaries
- meta
'400':
$ref: '#/components/responses/400-Bad-request'
'401':
$ref: '#/components/responses/401-Unauthorized'
'403':
$ref: '#/components/responses/403-Forbidden'
'422':
description: Returns an unprocessable entity error.
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/UnprocessableEntityError'
x-examples:
Example 1:
errors:
- code: invalid
detail: updated_at_from is not a valid date
source:
properties:
pointer: /external_transfer/updated_at_from
examples:
Invalid filter:
value:
errors:
- code: invalid
detail: updated_at_from is not a valid date
source:
properties:
pointer: /external_transfer/updated_at_from
'500':
$ref: '#/components/responses/500-Internal-Server-Error'
deprecated: true
security:
- OAuth:
- organization.read
- SecretKey: []
components:
parameters:
X-Qonto-Staging-Token:
name: X-Qonto-Staging-Token
in: header
description: >-
Required only for Sandbox API requests; to get one, please sign up to
the [Developer Portal](https://developers.qonto.com/).
schema:
type: string
schemas:
Beneficiary:
type: object
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
description: >
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.
example: validated
trusted:
type: boolean
description: >-
Indicates whether you can automate transfer through API to the
beneficiary or not.
bank_account:
type: object
description: >-
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.
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
description: UTC, the time at which the beneficiary was first recorded.
example: '2021-01-27T22:05:07.000Z'
updated_at:
type: string
description: UTC, the time at which the beneficiary was last updated.
example: '2021-01-27T22:05:07.000Z'
required:
- id
- name
- status
- trusted
- created_at
- updated_at
Pagination:
type: object
description: Metadata for paginated responses
required:
- current_page
- next_page
- prev_page
- total_pages
- total_count
- per_page
properties:
current_page:
type: integer
description: The current page number
example: 2
next_page:
type:
- integer
- 'null'
description: The next page number (null if on last page)
example: 3
prev_page:
type:
- integer
- 'null'
description: The previous page number (null if on first page)
example: 1
total_pages:
type: integer
description: Total number of pages
example: 11
total_count:
type: integer
description: Total number of items across all pages
example: 210
per_page:
type: integer
description: Number of items per page
example: 20
UnprocessableEntityError:
type: object
properties:
status:
type: string
example: unprocessable entity
code:
type: string
description: Error code.
example: missing_key
detail:
type: string
description: Human readable error that explains error `code`.
example: property is missing
message:
type: string
example: property id is missing
source:
type: object
properties:
pointer:
type: string
description: >-
The property and the item in an array (if applicable) that
causes the error.
example: id
required:
- code
- detail
x-examples:
Missing property:
code: missing_key
detail: property is missing
source:
pointer: /external_transfer/atrribute
BadRequestResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/BadRequestError'
required:
- errors
UnauthorizedResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/UnauthorizedError'
required:
- errors
ForbiddenResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ForbiddenError'
required:
- errors
BadRequestError:
type: object
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 property in the request body that caused the error
(optional).
parameter:
type: string
description: The query parameter that caused the error (optional).
required:
- code
- detail
x-examples:
Authorization field missing:
code: bad_request
detail: Authorization field missing
UnauthorizedError:
type: object
properties:
code:
type: string
description: Error code.
detail:
type: string
description: Human readable error that explains error `code`.
required:
- code
- detail
x-examples:
Invalid credentials:
code: unauthorized
detail: Invalid credentials
ForbiddenError:
type: object
properties:
code:
type: string
description: Error code.
detail:
type: string
description: Human readable error that explains error `code`.
required:
- code
- detail
x-examples:
Insufficient permissions:
code: forbidden
detail: User does not have sufficient permissions for this action.
responses:
400-Bad-request:
description: Returns a bad request error.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseBody'
examples:
Authorization field missing:
value:
errors:
- code: bad_request
detail: Authorization field missing
401-Unauthorized:
description: Returns an unauthorized error.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponseBody'
examples:
authorization_header_missing:
value:
errors:
- code: authorization_header_missing
detail: authorization header missing
authorization_token_invalid:
value:
errors:
- code: authorization_token_invalid
detail: authorization token invalid
403-Forbidden:
description: Returns a forbidden error.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseBody'
examples:
Insufficient permissions:
value:
errors:
- code: forbidden
detail: User does not have sufficient permissions for this action.
500-Internal-Server-Error:
description: Returns an internal server error.
securitySchemes:
OAuth:
type: oauth2
description: >
Bearer authorization header: `Bearer `, where `` is the
access token received from the authorization server at the end of the
[OAuth 2.0
flow](/get-started/business-api/authentication/oauth/oauth-flow).
flows:
authorizationCode:
refreshUrl: https://oauth.qonto.com/oauth2/token
authorizationUrl: https://oauth.qonto.com/oauth2/auth
scopes:
attachment.read: Retrieve attachments
attachment.write: Upload attachments and remove attachments from transactions
bank_account.write: Create, update and close bank accounts
beneficiary.trust: Trust SEPA beneficiaries
card.read: Retrieve cards
card.write: Create or update cards
client.read: Retrieve clients
client.write: Create clients
client_invoice.write: Create client invoices
client_invoices.read: Retrieve client invoices and credit notes
einvoicing.read: Retrieve e-invoicing settings
embed_auth_link.write: Create Embed auth links
insurance_contract.read: Retrieve insurance contracts
insurance_contract.write: Create and update insurance contracts
internal_transfer.write: >-
Create internal transfers (between 2 Qonto accounts of the same
organization)
international_transfer.write: Create international transfers
membership.read: Retrieve the authentified membership
membership.write: Invite team members
offline_access: Retrieve a refresh token
organization.read: >-
Retrieve organization, bank accounts, transactions, transfers,
beneficiaries, labels, memberships, requests & statements
payment.write: Create external transfers and untrust beneficiaries
payment_link.read: >-
Retrieve payment links, their payments, and the available payment
methods
payment_link.write: >-
Connect to the payment links provider, create and deactivate
payment links
product.read: Retrieve products
product.write: Create products
request_cards.write: Create card requests
request_review.write: Approve or decline requests
request_transfers.write: Create transfer requests
sepa_direct_debit.read: View SEPA Direct Debit payments
sepa_direct_debit.write: Manage SEPA Direct Debit payments
supplier_invoice.read: Retrieve supplier invoices
supplier_invoice.write: Create supplier invoices
team.read: Retrieve teams
team.write: Create teams
terminal.read: View your payment terminals
terminal.write: Configure your terminals and initiate payments
webhook: >-
Receive a notification each time a particular event occurs in
Qonto
tokenUrl: https://oauth.qonto.com/oauth2/token
SecretKey:
type: apiKey
description: cf. [API key](/get-started/business-api/authentication/api-key)
name: Authorization
in: header
````