Skip to content
Docs/
API reference
/
/
Create a Beneficiary

Create a Beneficiary

Request

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

Security
JWT
Bodyapplication/jsonrequired
categorystringrequired

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.

An account funding beneficiary uses payout. It is the customer's own account - the account the card funds are credited to - not a third party.

Enum:"payout""lrs"
Example:"payout"
beneficiaryobjectrequired

The beneficiary details including name, contact information, and address.

bank_accountobject

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.

upi_accountobject

UPI account details. Provide either bank_account or upi_account, not both.

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"
}
curl -i -X POST \
  https://api.glomopay.com/api/v2/beneficiaries \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "category": "payout",
    "beneficiary": {
      "name": "John Doe",
      "type": "individual",
      "address": {
        "address_line1": "456 Main Street",
        "city": "Los Angeles",
        "state": "CA",
        "country_code": "USA",
        "postal_code": "90001"
      }
    },
    "bank_account": {
      "account_number": "1234567890",
      "swift_code": "CITIUS33",
      "currency": "USD"
    },
    "notes": {
      "invoice_ref": "INV-2026-002"
    }
  }'

Responses

Beneficiary created successfully

Bodyapplication/json
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"
}
Response
{
  "id": "bene_5JU9yv0lGSUP",
  "name": "ACME Corporation",
  "type": "business",
  "category": "lrs",
  "status": "pending",
  "email": "finance@acme.com",
  "phone": "+1-555-123-4567",
  "nickname": "ACME Primary Account",
  "upi_account": null,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z",
  "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": { … }
  },
  "notes": {
    "invoice_ref": "INV-2026-001",
    "project": "Alpha"
  }
}