# BeneficiaryV2

Schema: #/components/schemas/BeneficiaryV2

Method: SCHEMA
Version: 1.0.0

## Schema fields:

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

  - `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. If your business has custom field rules configured (e.g. enum constraints), values are validated against those rules. 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"}