# Get a Beneficiary

Retrieves the details of an existing beneficiary by ID.

Endpoint: GET /v2/beneficiaries/{id}
Version: 1.0.0
Security: JWT

## Security:

  - `JWT` (unknown)
    http bearer JWT

## Path parameters:

  - `id` (string, required)
    The ID of the beneficiary.

## Response 200:

  - `200` (unknown)
    Beneficiary details

## Response 200 fields (application/json):

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Response 404:

  - `404` (unknown)
    Beneficiary not found or does not belong to the authenticated business

## Response 404 fields (application/json):

  - `error` (string)
    Enum: "Not found"

  - `message` (string)
    Entity not found
    Enum: "Entity not found"