---
title: "List beneficiaries"
method: GET
path: "/v2/beneficiaries"
tags: ["Beneficiaries"]
---

# List beneficiaries

`GET /v2/beneficiaries`

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

## Query parameters

- `trusted` boolean
- `status` string[]
- `iban` string[]
- `updated_at_from` string
- `updated_at_to` string

## Headers

- `X-Qonto-Staging-Token` string

## Response `200`

lists beneficiaries for a given organization

- object
  - `beneficiaries` Beneficiary[], required
    - `id` string, uuid, required
    - `name` string, required
    - `status` 'pending' | 'declined' | 'validated', required
    - `trusted` boolean, required
    - `bank_account` object
      - `iban` string
      - `bic` string
      - `currency` string
      - `account_number` string
      - `routing_number` string
      - `intermediary_bank_bic` string
      - `swift_sort_code` string
    - `created_at` string, required
    - `updated_at` string, required
  - `meta` Pagination, required
    - `current_page` integer
    - `next_page` integer, nullable
    - `prev_page` integer, nullable
    - `total_pages` integer
    - `total_count` integer
    - `per_page` integer

## Other responses

- `422` — Returns errors

---

[API](https://skmtc.net/hiit-consulting-fr/apis/qonto.md) · [All operations](https://skmtc.net/hiit-consulting-fr/apis/qonto/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hiit-consulting-fr/qonto/revisions/25208d6f9deb/schema)