# List Beneficiaries

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

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

## Security:

  - `JWT` (unknown)
    http bearer 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:

  - `200` (unknown)
    A paginated list of beneficiaries

## 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.
- `active` — the beneficiary can receive payouts.
- `rejected` — the beneficiary did not pass review and cannot receive payouts. Terminal.
    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

  - `data.notes` (object | null)
    Optional key-value pairs for attaching custom metadata (e.g. invoice references, project codes). Keys must be strings and cannot collide with reserved field names. Your account may require some `notes` fields: Glomo configures custom field rules per account, and for beneficiaries they are checked when the beneficiary is created. Some fields are also validated by the beneficiary's country (for example, a PAN format for Indian beneficiaries). A missing required field returns `422` with `Validation failed: Notes <field> is required`, and type and validation errors (such as enum constraints) are returned the same way. The rule is set on your account, not by currency or rail. No API lists the fields, but the `422` names each missing one: add that key to `notes` with the value your account expects, and ask your Glomo account manager if you don't know what the field should hold. See [Custom fields](/payin/custom-fields). Each key appears as a separate column in CSV report exports, with corresponding values populating the rows.
    Example: {"invoice_ref":"INV-2026-001","project":"Alpha"}

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

  - `400` (unknown)
    Bad Request - Invalid query parameters

## Response 400 fields (application/json):

  - `error` (string)
    Example: Bad Request

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