Create a Beneficiary

Beneficiaries are entities (individuals or businesses) registered on the Caliza platform to send or receive funds. Creating a beneficiary is a prerequisite for most operations — you'll need a beneficiary before you can create recipients, virtual accounts, or send payments.

When you create a beneficiary, the system automatically initiates KYX (Know Your Customer/Business) verification.

Prerequisites

A valid access token. See Authenticate.
Your Integrator ID. See Get the Integrator ID.

Create an individual beneficiary

Send a POST request to /v1/beneficiaries with type set to INDIVIDUAL:

curl -X POST 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "integratorBeneficiaryId": "my-user-001",
    "type": "INDIVIDUAL",
    "person": {
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "1985-11-20",
      "citizenship": "US",
      "idNumber": "D1234567",
      "email": "[email protected]",
      "phoneNumber": "+12025550148",
      "address": {
        "streetOne": "1600 Pennsylvania Avenue NW",
        "city": "Washington",
        "zipcode": "20500",
        "state": "DC",
        "country": "US"
      }
    }
  }'

The response includes the beneficiary id (save this for subsequent API calls) and a status of PENDING, indicating that KYX verification has started.

{
  "id": "6925dd986a93002882da640b",
  "integratorId": "6920925fdbadfe09b1bf9e5e",
  "integratorBeneficiaryId": "my-user-001",
  "type": "INDIVIDUAL",
  "active": true,
  "kycVerified": false,
  "status": "PENDING",
  "createdDate": "2025-01-15T16:47:20.568615486Z"
}

📘
The beneficiary must complete KYX verification before you can create recipients or execute transactions. Monitor the status field via the API or subscribe to BENEFICIARY_APPROVED / BENEFICIARY_FAILED webhooks.

What's next

Once your beneficiary is approved, you're ready to continue the Quickstart flow:

Create Virtual Accounts

Set up USD virtual accounts for deposits.

Manage Recipients

Create destination accounts for payments.

Send Your First Payment

Walk through a complete payment flow.

For the full beneficiary reference — including business beneficiaries, all required and optional fields, KYX details, and status management — see Beneficiaries.