# Create a Beneficiary

Creates a beneficiary with structured nested objects for beneficiary details, address, and bank account or UPI information.

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

## Request fields (application/json):

  - `category` (string, required)
    The category of the beneficiary.
- `payout` — the primary use case. Processes a payout from your Glomo balance.
- `lrs` — a specific case. Processes an LRS (Liberalised Remittance Scheme) payin whose funds
go directly to a customer-specific bank account rather than into your Glomo balance.
    Enum: "payout", "lrs"

  - `beneficiary` (object, required)
    The beneficiary details including name, contact information, and address.

  - `beneficiary.name` (string, required)
    The name of the beneficiary. This is a required field.
    Example: ACME Corporation

  - `beneficiary.type` (string, required)
    The type of beneficiary. Must be either `individual` or `business`.
    Enum: "individual", "business"

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

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

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

  - `beneficiary.address` (object, required)
    The address of the beneficiary. All fields except address_line2 are required.

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

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

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

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

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

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

  - `beneficiary.documents` (array)
    Optional list of document IDs to attach to the beneficiary.
    Example: ["doc_68e7980auYRAs"]

  - `bank_account` (object)
    The bank account details of the beneficiary.
For `category: payout`, `name` and `address` are resolved from the `swift_code`, the
`local_routing_number`, or an IBAN `account_number`. Send them only if the identifier cannot be
resolved, or to override the resolved values. Both remain required for `category: lrs`.
Routing identifier rules differ by category:
- `category: lrs` — `local_routing_number` is required. `swift_code` is optional.
- `category: payout` — provide exactly one of `swift_code` or `local_routing_number`, except
for EUR and AED accounts identified by an IBAN alone, which send neither.

For the rails each identifier maps to, see
[Payout rails](../../../../product-guide/payout/rails).

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

  - `bank_account.name` (string)
    The name of the bank where the account is held. Required for `category: lrs`, optional for `category: payout`.
    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. For LRS category it is optional, and must be exactly 8 characters (no branch suffix like XXX). For payout category, see [Payout rails](../../../../product-guide/payout/rails).
    Example: CITIUS33

  - `bank_account.local_routing_number` (string)
    The local routing code or domestic clearing code of the bank account. Required for LRS category, optional for payout category. For reference, this is the IFSC code in India, the sort code in the UK, ABA in the US, etc. For payout category, see [Payout rails](../../../../product-guide/payout/rails).
    Example: 021000089

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

  - `bank_account.address` (object)
    The address of the bank. Required for `category: lrs`, optional for `category: payout`. When sent, all fields except address_line2 are required.

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

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

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

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

  - `bank_account.address.country_code` (string, required)
    The country where the bank is located (required). 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, required)
    The postal code of the bank's address (required).
    Example: 10013

  - `bank_account.intermediate_bank` (object)
    Details of the intermediate/correspondent bank. **`swift_code` is required for LRS category beneficiaries.** Optional for payout category beneficiaries.

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

  - `bank_account.intermediate_bank.country` (string)
    The country of the intermediate bank (optional). 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/BIC code of the correspondent/intermediary bank used to route the remittance. Required for LRS category, optional for payout category.
    Example: CHASUS33

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

  - `upi_account` (object)
    UPI account details. Provide either bank_account or upi_account, not both.

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

## Response 201 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.
    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

## Response 400 fields (application/json):

  - `error` (string)
    Example: Bad Request

  - `message` (string)
    Error message indicating which fields failed validation

## Response 422 fields (application/json):

  - `error` (string)
    Example: Unprocessable Entity

  - `message` (string)
    Error message indicating the business logic error