# Create a Beneficiary (v2)

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

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

## Request fields (application/json):

  - `category` (string, required)
    The category of the beneficiary. Use "lrs" for LRS (Liberalised Remittance Scheme) beneficiaries or "payout" for payout beneficiaries.
    Enum: "lrs", "payout"

  - `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)
    The type of beneficiary. Defaults to "business" if not provided.
    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"

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

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

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

  - `bank_account.swift_code` (string, required)
    The SWIFT/BIC code of the bank (required). Must be 8-11 characters with first 6 being letters only. For LRS category, must be exactly 8 characters (no branch suffix like XXX).
    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, SORT in UK, ABA in the US, etc.
    Example: "021000089"

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

  - `bank_account.address` (object, required)
    The address of the bank. 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 (optional). If provided, must be a valid object.

  - `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 code of the intermediate bank (optional).
    Example: "CHASUS33"

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

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

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

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

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

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