Beneficiary V2

This resource represents a payee of a payout initiated by your business. Beneficiary V2 introduces a structured nested format for beneficiary, address, and bank account details, and supports both bank account and UPI payment methods.

SchemasOperations

BeneficiaryV2

idstringread-only

The unique identifier for the beneficiary.

Example:"ben_5JU9yv0lGSUP"

namestring

The name of the beneficiary.

Example:"ACME Corporation"

typestring

The type of beneficiary.

Enum:"individual""business"

Example:"business"

categorystringread-only

The category of the beneficiary.

Enum:"payout""lrs"

Example:"payout"

emailstring, (email)

The email address of the beneficiary.

Example:"finance@acme.com"

phonestring

The phone number of the beneficiary.

Example:"+1-555-123-4567"

nicknamestring

A nickname for the beneficiary. If not provided, auto-generated as "{beneficiary_name} - {bank_name}".

Example:"ACME Primary Account"

addressobject

The address of the beneficiary.

bank_accountobject

The bank account details of the beneficiary.

statusstringread-only

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"

Example:"pending"

documentsArray of stringsread-only

List of document IDs attached to the beneficiary.

Example:

[
  "doc_68e7980auYRAs"
]

upi_accountobject or null

The UPI account details of the beneficiary. Present when the beneficiary uses UPI, otherwise null.

created_atstring, (date-time)read-only

Timestamp representing when the beneficiary was created in ISO 8601 format.

Example:"2025-01-15T10:00:00Z"

updated_atstring, (date-time)read-only

Timestamp representing when the beneficiary was last updated in ISO 8601 format.

Example:"2025-01-15T10:00:00Z"

notesobject or null(Notes)

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

{
  "id": "ben_5JU9yv0lGSUP",
  "name": "ACME Corporation",
  "type": "business",
  "category": "payout",
  "email": "finance@acme.com",
  "phone": "+1-555-123-4567",
  "nickname": "ACME Primary Account",
  "address": {
    "address_line1": "123 Business Park",
    "address_line2": "Suite 100",
    "city": "New York",
    "state": "NY",
    "country_code": "USA",
    "postal_code": "10001"
  },
  "bank_account": {
    "account_number": "1234567890",
    "name": "Citibank NA",
    "swift_code": "CITIUS33",
    "local_routing_number": "021000089",
    "currency": "USD",
    "address": { … },
    "intermediate_bank": { … }
  },
  "status": "pending",
  "documents": [
    "doc_68e7980auYRAs"
  ],
  "upi_account": {
    "upi_id": "1111111111@ybl"
  },
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z",
  "notes": {
    "invoice_ref": "INV-2026-001",
    "project": "Alpha"
  }
}