# List Beneficiaries

Returns a paginated list of beneficiaries. Optionally filter by status.

Endpoint: GET /v2/beneficiaries
Version: 1.0.0
Security: JWT

## Query parameters:

  - `status` (string)
    Filter beneficiaries by status.

  - `page` (integer)
    Page number for pagination.

  - `per_page` (integer)
    Number of results per page.

## Response 200 fields (application/json):

  - `data` (array)

  - `data.id` (string)
    The unique identifier for the beneficiary.
    Example: ben_5JU9yv0lGSUP

  - `data.name` (string)
    The name of the beneficiary.
    Example: ACME Corporation

  - `data.type` (string)
    The type of beneficiary.
    Enum: "individual", "business"

  - `data.category` (string)
    The category of the beneficiary.
    Enum: "payout", "lrs"

  - `data.email` (string)
    The email address of the beneficiary.
    Example: finance@acme.com

  - `data.phone` (string)
    The phone number of the beneficiary.
    Example: +1-555-123-4567

  - `data.nickname` (string)
    A nickname for the beneficiary. If not provided, auto-generated as "{beneficiary_name} - {bank_name}".
    Example: ACME Primary Account

  - `data.address` (object)
    The address of the beneficiary.

  - `data.address.address_line1` (string)
    The street address of the beneficiary.
    Example: 123 Business Park

  - `data.address.address_line2` (string)
    The second line of street address of the beneficiary.
    Example: Suite 100

  - `data.address.city` (string)
    The city where the beneficiary is located.
    Example: New York

  - `data.address.state` (string)
    The state or administrative area where the beneficiary is located.
    Example: NY

  - `data.address.country_code` (string)
    The country where the beneficiary is located. Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.
    Example: USA

  - `data.address.postal_code` (string)
    The postal code of the beneficiary's address.
    Example: 10001

  - `data.bank_account` (object)
    The bank account details of the beneficiary.

  - `data.bank_account.account_number` (string)
    The account number of the beneficiary.
    Example: 1234567890

  - `data.bank_account.name` (string)
    The name of the bank where the account is held.
    Example: Citibank NA

  - `data.bank_account.swift_code` (string)
    The SWIFT/BIC code of the bank. Must be 8-11 characters with first 6 being letters only.
    Example: CITIUS33

  - `data.bank_account.local_routing_number` (string)
    The local routing code or domestic clearing code of the bank account. For reference, this is the IFSC code in India, SORT in UK, ABA in the US, etc.
    Example: 021000089

  - `data.bank_account.currency` (string)
    The currency of the bank account.
    Example: USD

  - `data.bank_account.address` (object)
    The address of the bank.

  - `data.bank_account.address.address_line1` (string)
    The street address of the bank.
    Example: 388 Greenwich Street

  - `data.bank_account.address.address_line2` (string)
    The second line of street address of the bank.

  - `data.bank_account.address.city` (string)
    The city where the bank is located.
    Example: New York

  - `data.bank_account.address.state` (string)
    The state or administrative area where the bank is located.
    Example: NY

  - `data.bank_account.address.country_code` (string)
    The country where the bank is located. Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.
    Example: USA

  - `data.bank_account.address.postal_code` (string)
    The postal code of the bank's address.
    Example: 10013

  - `data.bank_account.intermediate_bank` (object)
    Details of the intermediate/correspondent bank. Present for LRS category beneficiaries (swift_code is required at creation). May be null for payout category beneficiaries.

  - `data.bank_account.intermediate_bank.name` (string)
    The name of the intermediate bank.
    Example: JPMorgan Chase Bank

  - `data.bank_account.intermediate_bank.country` (string)
    The country of the intermediate bank. Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.
    Example: USA

  - `data.bank_account.intermediate_bank.swift_code` (string)
    The SWIFT code of the intermediate bank.
    Example: CHASUS33

  - `data.bank_account.intermediate_bank.account_number` (string)
    The account number at the intermediate bank.
    Example: 123456789

  - `data.status` (string)
    The current review status of the beneficiary.
    Enum: "pending", "active", "rejected"

  - `data.documents` (array)
    List of document IDs attached to the beneficiary.
    Example: ["doc_68e7980auYRAs"]

  - `data.upi_account` (object | null)
    The UPI account details of the beneficiary. Present when the beneficiary uses UPI, otherwise null.

  - `data.upi_account.upi_id` (string)
    The UPI ID of the beneficiary.
    Example: 1111111111@ybl

  - `data.created_at` (string)
    Timestamp representing when the beneficiary was created in ISO 8601 format.
    Example: 2025-01-15T10:00:00Z

  - `data.updated_at` (string)
    Timestamp representing when the beneficiary was last updated in ISO 8601 format.
    Example: 2025-01-15T10:00:00Z

  - `page_meta` (object)

  - `page_meta.current` (integer)
    Example: 1

  - `page_meta.previous` (integer | null)
    Example: null

  - `page_meta.next` (integer | null)
    Example: 2

  - `page_meta.per_page` (integer)
    Example: 20

  - `page_meta.pages` (integer)
    Example: 3

  - `page_meta.count` (integer)
    Example: 50

## Response 400 fields (application/json):

  - `error` (string)
    Example: Bad Request

  - `message` (string)
    Example: Status is not included in the list