Beneficiaries

Beneficiaries are the integrator's customers — the individuals or businesses that hold funds and execute transactions on the Caliza platform. Every API call that moves funds requires a beneficiaryId.

This page covers the full beneficiary lifecycle: creating individual and business beneficiaries, understanding KYX verification, checking status, and managing beneficiary state. For a quick walkthrough of creating your first beneficiary, see Create a Beneficiary.

Prerequisites

Authentication: A valid access token. See Authenticate.
Integrator ID: Your unique integratorId. See Get the Integrator ID.

Beneficiary types

The Caliza API supports two types:

INDIVIDUAL — A person with personal KYC requirements (name, DOB, citizenship)
BUSINESS — A company with corporate KYB requirements (incorporation info, tax ID, authorized contacts)

The type field determines which data structure you must provide. If you're creating a beneficiary for your own business and your account has already completed KYB onboarding, the system automatically approves the beneficiary.

Create an individual beneficiary

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

Required fields

Field	Type	Description
`integratorBeneficiaryId`	string	Your unique identifier for this beneficiary
`type`	string	Must be `"INDIVIDUAL"`
`person.firstName`	string	First name (max 100 characters)
`person.lastName`	string	Last name (max 100 characters)
`person.dateOfBirth`	string	Date of birth (`YYYY-MM-DD`)
`person.citizenship`	string	2-letter ISO country code
`person.idNumber`	string	Government-issued identification number
`person.email`	string	Email address
`person.phoneNumber`	string	Phone number (`+[country code][number]`, 6–20 digits)
`person.address.streetOne`	string	Primary street address (max 100 characters)
`person.address.city`	string	City name
`person.address.zipcode`	string	Postal or ZIP code
`person.address.state`	string	State or province (max 3 characters)
`person.address.country`	string	2-letter ISO country code

Optional fields

Field	Type	Description
`person.address.streetTwo`	string	Secondary address line (max 100 characters)
`person.placeOfBirth`	string	Place of birth
`person.profession`	string	Profession
`person.gender`	string	`MALE`, `FEMALE`, or `OTHER`
`person.maritalStatus`	string	Marital status
`person.mothersName`	string	Mother's name
`person.industry`	string	Industry (see enum values in API spec)
`person.incomeSource`	string	Source of income (see enum values in API spec)
`person.annualIncome`	number	Annual income
`person.occupation`	string	Occupation (see enum values in API spec)
`person.wealthSource`	string	Source of wealth (see enum values in API spec)
`localTargetBankAccount`	object	Bank account details for receiving payouts
`active`	boolean	Whether the beneficiary is active (defaults to `true`)

Example request

curl -X POST 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "integratorBeneficiaryId": "individual_jane_doe_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",
        "streetTwo": "Suite 200",
        "city": "Washington",
        "zipcode": "20500",
        "state": "DC",
        "country": "US"
      },
      "profession": "Software Engineer",
      "gender": "FEMALE"
    },
    "active": true
  }'

const response = await axios.post(
  'https://api.sandbox.caliza.com/core-api/v1/beneficiaries',
  {
    integratorBeneficiaryId: 'individual_jane_doe_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',
        streetTwo: 'Suite 200',
        city: 'Washington',
        zipcode: '20500',
        state: 'DC',
        country: 'US'
      },
      profession: 'Software Engineer',
      gender: 'FEMALE'
    },
    active: true
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

response = requests.post(
  'https://api.sandbox.caliza.com/core-api/v1/beneficiaries',
  headers={
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {access_token}'
  },
  json={
    'integratorBeneficiaryId': 'individual_jane_doe_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',
        'streetTwo': 'Suite 200',
        'city': 'Washington',
        'zipcode': '20500',
        'state': 'DC',
        'country': 'US'
      },
      'profession': 'Software Engineer',
      'gender': 'FEMALE'
    },
    'active': True
  }
)

Example response

{
  "id": "6925dd986a93002882da640b",
  "integratorId": "6920925fdbadfe09b1bf9e5e",
  "integratorBeneficiaryId": "individual_jane_doe_001",
  "type": "INDIVIDUAL",
  "person": {
    "firstName": "Jane",
    "lastName": "Doe",
    "dateOfBirth": "1985-11-20",
    "citizenship": "US",
    "idNumber": "D1234567",
    "email": "[email protected]",
    "phoneNumber": "+12025550148",
    "profession": "Software Engineer",
    "gender": "FEMALE",
    "address": {
      "streetOne": "1600 Pennsylvania Avenue NW",
      "streetTwo": "Suite 200",
      "city": "Washington",
      "zipcode": "20500",
      "state": "DC",
      "country": "US"
    }
  },
  "business": null,
  "localTargetBankAccount": null,
  "files": [],
  "active": true,
  "kycVerified": false,
  "status": "PENDING",
  "createdDate": "2025-01-15T16:47:20.568615486Z"
}

Create a business beneficiary

Send a POST request to /v1/beneficiaries with type set to BUSINESS.

Required fields

Field	Type	Description
`integratorBeneficiaryId`	string	Your unique identifier for this beneficiary
`type`	string	Must be `"BUSINESS"`
`business.name`	string	Business name (max 60 characters)
`business.dateOfIncorporation`	string	Date of incorporation (`YYYY-MM-DD`)
`business.idNumber`	string	Business tax ID or registration number
`business.phoneNumber`	string	Business phone number (`+[country code][number]`, 6–20 digits)
`business.email`	string	Business email address
`business.address.streetOne`	string	Primary street address (max 100 characters)
`business.address.city`	string	City name
`business.address.zipcode`	string	Postal or ZIP code
`business.address.state`	string	State or province (max 3 characters)
`business.address.country`	string	2-letter ISO country code
`business.contacts`	array	At least one contact person (each contact requires the same fields as an individual's `person` object)

Optional fields

Field	Type	Description
`business.address.streetTwo`	string	Secondary address line (max 100 characters)
`business.website`	string	Business website URL (max 100 characters)
`business.description`	string	Business description
`business.legalStructure`	string	Legal structure: `MEI`, `ME`, `EI`, `SLU`, `LTDA`, `SS`, `SA`, `SOLE_PROP`, `SINGLE_MEMBER_LLC`, `LLC`, `GP`, `LP`, `LLP`, `S_CORP`, `C_CORP`, `PC`, `NONPROFIT`, `B_CORP`
`localTargetBankAccount`	object	Bank account details for receiving payouts
`localCalizaOwnedBankAccountId`	string	ID of a Caliza-owned bank account
`active`	boolean	Whether the beneficiary is active (defaults to `true`)

Example request

curl -X POST 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "integratorBeneficiaryId": "business_acme_001",
    "type": "BUSINESS",
    "business": {
      "name": "Acme Corp",
      "dateOfIncorporation": "2015-03-20",
      "idNumber": "12-3456789",
      "phoneNumber": "+12125550100",
      "email": "[email protected]",
      "website": "https://acme.example.com",
      "legalStructure": "LLC",
      "address": {
        "streetOne": "350 Fifth Avenue",
        "city": "New York",
        "zipcode": "10118",
        "state": "NY",
        "country": "US"
      },
      "contacts": [
        {
          "firstName": "John",
          "lastName": "Smith",
          "dateOfBirth": "1980-06-15",
          "citizenship": "US",
          "idNumber": "A9876543",
          "email": "[email protected]",
          "phoneNumber": "+12125550101",
          "address": {
            "streetOne": "350 Fifth Avenue",
            "city": "New York",
            "zipcode": "10118",
            "state": "NY",
            "country": "US"
          }
        }
      ]
    },
    "active": true
  }'

const response = await axios.post(
  'https://api.sandbox.caliza.com/core-api/v1/beneficiaries',
  {
    integratorBeneficiaryId: 'business_acme_001',
    type: 'BUSINESS',
    business: {
      name: 'Acme Corp',
      dateOfIncorporation: '2015-03-20',
      idNumber: '12-3456789',
      phoneNumber: '+12125550100',
      email: '[email protected]',
      website: 'https://acme.example.com',
      legalStructure: 'LLC',
      address: {
        streetOne: '350 Fifth Avenue',
        city: 'New York',
        zipcode: '10118',
        state: 'NY',
        country: 'US'
      },
      contacts: [
        {
          firstName: 'John',
          lastName: 'Smith',
          dateOfBirth: '1980-06-15',
          citizenship: 'US',
          idNumber: 'A9876543',
          email: '[email protected]',
          phoneNumber: '+12125550101',
          address: {
            streetOne: '350 Fifth Avenue',
            city: 'New York',
            zipcode: '10118',
            state: 'NY',
            country: 'US'
          }
        }
      ]
    },
    active: true
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

response = requests.post(
  'https://api.sandbox.caliza.com/core-api/v1/beneficiaries',
  headers={
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {access_token}'
  },
  json={
    'integratorBeneficiaryId': 'business_acme_001',
    'type': 'BUSINESS',
    'business': {
      'name': 'Acme Corp',
      'dateOfIncorporation': '2015-03-20',
      'idNumber': '12-3456789',
      'phoneNumber': '+12125550100',
      'email': '[email protected]',
      'website': 'https://acme.example.com',
      'legalStructure': 'LLC',
      'address': {
        'streetOne': '350 Fifth Avenue',
        'city': 'New York',
        'zipcode': '10118',
        'state': 'NY',
        'country': 'US'
      },
      'contacts': [
        {
          'firstName': 'John',
          'lastName': 'Smith',
          'dateOfBirth': '1980-06-15',
          'citizenship': 'US',
          'idNumber': 'A9876543',
          'email': '[email protected]',
          'phoneNumber': '+12125550101',
          'address': {
            'streetOne': '350 Fifth Avenue',
            'city': 'New York',
            'zipcode': '10118',
            'state': 'NY',
            'country': 'US'
          }
        }
      ]
    },
    'active': True
  }
)

Example response

{
  "id": "6925ee107b04003992eb751c",
  "integratorId": "6920925fdbadfe09b1bf9e5e",
  "integratorBeneficiaryId": "business_acme_001",
  "type": "BUSINESS",
  "person": null,
  "business": {
    "name": "Acme Corp",
    "dateOfIncorporation": "2015-03-20",
    "idNumber": "12-3456789",
    "address": {
      "streetOne": "350 Fifth Avenue",
      "city": "New York",
      "zipcode": "10118",
      "state": "NY",
      "country": "US"
    },
    "email": "[email protected]",
    "website": "https://acme.example.com",
    "contacts": [
      {
        "firstName": "John",
        "lastName": "Smith",
        "dateOfBirth": "1980-06-15",
        "citizenship": "US",
        "idNumber": "A9876543",
        "email": "[email protected]",
        "phoneNumber": "+12125550101",
        "address": {
          "streetOne": "350 Fifth Avenue",
          "city": "New York",
          "zipcode": "10118",
          "state": "NY",
          "country": "US"
        }
      }
    ]
  },
  "localTargetBankAccount": null,
  "files": [],
  "active": true,
  "kycVerified": false,
  "status": "PENDING",
  "createdDate": "2025-01-15T17:10:08.123456789Z"
}

Check beneficiary status

Retrieve the current status of a beneficiary with GET /v1/beneficiaries/{beneficiaryId}:

curl -X GET 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{BENEFICIARY_ID}}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

The response includes the full beneficiary object. The key fields for status tracking are:

Field	Type	Description
`status`	string	Current verification status (see table below)
`kycVerified`	boolean	`true` once KYX verification is complete
`active`	boolean	Whether the beneficiary is active

Beneficiary statuses

Status	Description
`CREATED`	Beneficiary record created
`PENDING`	Awaiting KYX verification
`KYC_IN_PROGRESS`	KYX verification in progress
`MANUAL_REVIEW`	Requires manual review
`APPROVED`	Fully verified — ready for transactions
`DISABLED`	Beneficiary has been disabled
`FAILED`	KYX verification failed

KYX verification

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

Triggers verification — Creating a beneficiary automatically starts KYX.
Determines requirements — Required documents depend on the beneficiary's risk profile and jurisdiction.
Notifies integrators — The system sends BENEFICIARY_APPROVED or BENEFICIARY_FAILED webhook notifications.
May direct users — End users may be directed to a third-party verification provider (such as AiPrise) to upload documents.

For individuals, the system typically requests government-issued identification.

For businesses, the system typically requests proof of address, business registration documents, and beneficial ownership information.

KYX endpoints

Endpoint	Description
`GET /v1/beneficiaries/{beneficiaryId}`	Check `status` and `kycVerified` fields
`GET /v1/kyx/{id}/kyx/documents`	Retrieve submitted KYX documents
`GET /v1/kyx/{id}/kyx/re-run`	Retry identity verification
`POST /v1/kyx/check-requirements`	Check required documents before starting KYX

📘
Beneficiaries must complete KYX verification before they can execute certain transactions. Subscribe to webhooks to be notified when verification completes or fails.

Next steps

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.