# 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.
    Enum: "pending", "active", "rejected"

  - `page` (integer)
    Page number for pagination.
    Example: 1

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

## 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. Defaults to "business" if not provided.
    Enum: "individual", "business"

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

  - `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, if any.

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

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