Create Beneficiaries

Beneficiaries are entities (individuals or businesses) registered on the Caliza platform to send or receive funds. When you create a beneficiary, the system automatically initiates the KYX (Know Your Customer/Business) verification process.

Prerequisites

Before you begin, ensure that you have:

A valid Integrator ID. If you don't have one yet, follow the steps in How to get the Integrator ID for more details.
You need to have an access token. If you don't have one yet, follow the steps in How to authenticate with Caliza API.

Understanding beneficiary types

The Caliza API supports two types of beneficiaries:

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 in the request. This separation ensures proper regulatory compliance, risk management, and different data structures for personal vs. commercial transactions.

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

To create an individual beneficiary, you need to send a POST request to the /beneficiaries endpoint setting the typeparameter as INDIVIDUAL, along with all the details of the Beneficiary.

Required fields

The following fields are required when creating an individual beneficiary:

Field	Type	Description
`integratorBeneficiaryId`	string	Your unique identifier for this beneficiary
`type`	string	Must be `"INDIVIDUAL"`
`person`	object	Person information object (see fields below)
`person.firstName`	string	First name (max 100 characters)
`person.lastName`	string	Last name (max 100 characters)
`person.dateOfBirth`	string	Date of birth (format: `YYYY-MM-DD`)
`person.citizenship`	string	Country code
`person.idNumber`	string	Government-issued identification number
`person.email`	string	Email address
`person.phoneNumber`	string	Phone number (format: `+[country code][number]`, 6-20 digits)
`person.address`	object	Address object (see fields below)
`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	Country code (2-character ISO code)

Optional fields

The following fields are optional when creating an individual beneficiary:

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	Gender (`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` if not specified)
`integratorId`	string	Your integrator ID (optional if authenticated)

Example request

curl --location --request POST 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--data-raw '{
  "integratorBeneficiaryId": "{{INTEGRATOR_BENEFICIARY_ID}}",
  "type": "INDIVIDUAL",
  "person": {
    "firstName": "{{FIRST_NAME}}",
    "lastName": "{{LAST_NAME}}",
    "dateOfBirth": "{{DATE_OF_BIRTH}}",
    "citizenship": "{{CITIZENSHIP}}",
    "idNumber": "{{ID_NUMBER}}",
    "email": "{{EMAIL}}",
    "phoneNumber": "{{PHONE_NUMBER}}",
    "address": {
      "streetOne": "{{STREET_ONE}}",
      "streetTwo": "{{STREET_TWO}}",
      "city": "{{CITY}}",
      "zipcode": "{{ZIPCODE}}",
      "state": "{{STATE}}",
      "country": "{{COUNTRY}}"
    },
    "profession": "{{PROFESSION}}",
    "gender": "{{GENDER}}"
  },
  "active": true
}'

const axios = require('axios');

const response = await axios.post(
  'https://api.sandbox.caliza.com/core-api/v1/beneficiaries',
  {
    integratorBeneficiaryId: '{{INTEGRATOR_BENEFICIARY_ID}}',
    type: 'INDIVIDUAL',
    person: {
      firstName: '{{FIRST_NAME}}',
      lastName: '{{LAST_NAME}}',
      dateOfBirth: '{{DATE_OF_BIRTH}}',
      citizenship: '{{CITIZENSHIP}}',
      idNumber: '{{ID_NUMBER}}',
      email: '{{EMAIL}}',
      phoneNumber: '{{PHONE_NUMBER}}',
      address: {
        streetOne: '{{STREET_ONE}}',
        streetTwo: '{{STREET_TWO}}',
        city: '{{CITY}}',
        zipcode: '{{ZIPCODE}}',
        state: '{{STATE}}',
        country: '{{COUNTRY}}'
      },
      profession: '{{PROFESSION}}',
      gender: '{{GENDER}}'
    },
    active: true
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

console.log('Beneficiary ID:', response.data.id);

import requests

response = requests.post(
  'https://api.sandbox.caliza.com/core-api/v1/beneficiaries',
  headers={
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {access_token}'
  },
  json={
    'integratorBeneficiaryId': '{{INTEGRATOR_BENEFICIARY_ID}}',
    'type': 'INDIVIDUAL',
    'person': {
      'firstName': '{{FIRST_NAME}}',
      'lastName': '{{LAST_NAME}}',
      'dateOfBirth': '{{DATE_OF_BIRTH}}',
      'citizenship': '{{CITIZENSHIP}}',
      'idNumber': '{{ID_NUMBER}}',
      'email': '{{EMAIL}}',
      'phoneNumber': '{{PHONE_NUMBER}}',
      'address': {
        'streetOne': '{{STREET_ONE}}',
        'streetTwo': '{{STREET_TWO}}',
        'city': '{{CITY}}',
        'zipcode': '{{ZIPCODE}}',
        'state': '{{STATE}}',
        'country': '{{COUNTRY}}'
      },
      'profession': '{{PROFESSION}}',
      'gender': '{{GENDER}}'
    },
    'active': True
  }
)

beneficiary_data = response.json()
print('Beneficiary ID:', beneficiary_data['id'])

Example response

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

Create a business beneficiary

To create a business beneficiary, send a POST request to /v1/beneficiaries with type set to BUSINESS and include the required business information.

Required fields

The following fields are required when creating a business beneficiary:

Field	Type	Description
`integratorBeneficiaryId`	string	Your unique identifier for this beneficiary
`type`	string	Must be `"BUSINESS"`
`business`	object	Business information object (see fields below)
`business.name`	string	Business name (max 60 characters)
`business.dateOfIncorporation`	string	Date of incorporation (format: `YYYY-MM-DD`)
`business.idNumber`	string	Business tax ID or registration number
`business.phoneNumber`	string	Business phone number (format: `+[country code][number]`, 6-20 digits)
`business.email`	string	Business email address
`business.address`	object	Business address object (see fields below)
`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	Country code (2-character ISO code)
`business.contacts`	array	Array of at least one contact person (each contact requires the same fields as an individual beneficiary's `person` object)

Optional fields

The following fields are optional when creating a business beneficiary:

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` if not specified)
`integratorId`	string	Your integrator ID (optional if authenticated)

Example request

curl --location --request POST 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--data-raw '{
 "integratorBeneficiaryId": "{{INTEGRATOR_BENEFICIARY_ID}}",
 "type": "BUSINESS",
 "business": {
   "name": "{{BUSINESS_NAME}}",
   "dateOfIncorporation": "{{DATE_OF_INCORPORATION}}",
   "idNumber": "{{BUSINESS_ID_NUMBER}}",
   "phoneNumber": "{{BUSINESS_PHONE_NUMBER}}",
   "email": "{{BUSINESS_EMAIL}}",
   "website": "{{BUSINESS_WEBSITE}}",
   "legalStructure": "{{LEGAL_STRUCTURE}}",
   "address": {
     "streetOne": "{{BUSINESS_STREET_ONE}}",
     "streetTwo": "{{BUSINESS_STREET_TWO}}",
     "city": "{{BUSINESS_CITY}}",
     "zipcode": "{{BUSINESS_ZIPCODE}}",
     "state": "{{BUSINESS_STATE}}",
     "country": "{{BUSINESS_COUNTRY}}"
   },
   "contacts": [
     {
       "firstName": "{{CONTACT_FIRST_NAME}}",
       "lastName": "{{CONTACT_LAST_NAME}}",
       "dateOfBirth": "{{CONTACT_DATE_OF_BIRTH}}",
       "citizenship": "{{CONTACT_CITIZENSHIP}}",
       "idNumber": "{{CONTACT_ID_NUMBER}}",
       "email": "{{CONTACT_EMAIL}}",
       "phoneNumber": "{{CONTACT_PHONE_NUMBER}}",
       "address": {
         "streetOne": "{{CONTACT_STREET_ONE}}",
         "streetTwo": "{{CONTACT_STREET_TWO}}",
         "city": "{{CONTACT_CITY}}",
         "zipcode": "{{CONTACT_ZIPCODE}}",
         "state": "{{CONTACT_STATE}}",
         "country": "{{CONTACT_COUNTRY}}"
       }
     }
   ]
 },
 "active": true
}'

const axios = require('axios');

const response = await axios.post(
  'https://api.sandbox.caliza.com/core-api/v1/beneficiaries',
  {
    integratorBeneficiaryId: '{{INTEGRATOR_BENEFICIARY_ID}}',
    type: 'BUSINESS',
    business: {
      name: '{{BUSINESS_NAME}}',
      dateOfIncorporation: '{{DATE_OF_INCORPORATION}}',
      idNumber: '{{BUSINESS_ID_NUMBER}}',
      phoneNumber: '{{BUSINESS_PHONE_NUMBER}}',
      email: '{{BUSINESS_EMAIL}}',
      website: '{{BUSINESS_WEBSITE}}',
      legalStructure: '{{LEGAL_STRUCTURE}}',
      address: {
        streetOne: '{{BUSINESS_STREET_ONE}}',
        streetTwo: '{{BUSINESS_STREET_TWO}}',
        city: '{{BUSINESS_CITY}}',
        zipcode: '{{BUSINESS_ZIPCODE}}',
        state: '{{BUSINESS_STATE}}',
        country: '{{BUSINESS_COUNTRY}}'
      },
      contacts: [
        {
          firstName: '{{CONTACT_FIRST_NAME}}',
          lastName: '{{CONTACT_LAST_NAME}}',
          dateOfBirth: '{{CONTACT_DATE_OF_BIRTH}}',
          citizenship: '{{CONTACT_CITIZENSHIP}}',
          idNumber: '{{CONTACT_ID_NUMBER}}',
          email: '{{CONTACT_EMAIL}}',
          phoneNumber: '{{CONTACT_PHONE_NUMBER}}',
          address: {
            streetOne: '{{CONTACT_STREET_ONE}}',
            streetTwo: '{{CONTACT_STREET_TWO}}',
            city: '{{CONTACT_CITY}}',
            zipcode: '{{CONTACT_ZIPCODE}}',
            state: '{{CONTACT_STATE}}',
            country: '{{CONTACT_COUNTRY}}'
          }
        }
      ]
    },
    active: true
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

console.log('Beneficiary ID:', response.data.id);

import requests

response = requests.post(
  'https://api.sandbox.caliza.com/core-api/v1/beneficiaries',
  headers={
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {access_token}'
  },
  json={
    'integratorBeneficiaryId': '{{INTEGRATOR_BENEFICIARY_ID}}',
    'type': 'BUSINESS',
    'business': {
      'name': '{{BUSINESS_NAME}}',
      'dateOfIncorporation': '{{DATE_OF_INCORPORATION}}',
      'idNumber': '{{BUSINESS_ID_NUMBER}}',
      'phoneNumber': '{{BUSINESS_PHONE_NUMBER}}',
      'email': '{{BUSINESS_EMAIL}}',
      'website': '{{BUSINESS_WEBSITE}}',
      'legalStructure': '{{LEGAL_STRUCTURE}}',
      'address': {
        'streetOne': '{{BUSINESS_STREET_ONE}}',
        'streetTwo': '{{BUSINESS_STREET_TWO}}',
        'city': '{{BUSINESS_CITY}}',
        'zipcode': '{{BUSINESS_ZIPCODE}}',
        'state': '{{BUSINESS_STATE}}',
        'country': '{{BUSINESS_COUNTRY}}'
      },
      'contacts': [
        {
          'firstName': '{{CONTACT_FIRST_NAME}}',
          'lastName': '{{CONTACT_LAST_NAME}}',
          'dateOfBirth': '{{CONTACT_DATE_OF_BIRTH}}',
          'citizenship': '{{CONTACT_CITIZENSHIP}}',
          'idNumber': '{{CONTACT_ID_NUMBER}}',
          'email': '{{CONTACT_EMAIL}}',
          'phoneNumber': '{{CONTACT_PHONE_NUMBER}}',
          'address': {
            'streetOne': '{{CONTACT_STREET_ONE}}',
            'streetTwo': '{{CONTACT_STREET_TWO}}',
            'city': '{{CONTACT_CITY}}',
            'zipcode': '{{CONTACT_ZIPCODE}}',
            'state': '{{CONTACT_STATE}}',
            'country': '{{CONTACT_COUNTRY}}'
          }
        }
      ]
    },
    'active': True
  }
)

beneficiary_data = response.json()
print('Beneficiary ID:', beneficiary_data['id'])

Example response

{
  "id": "{{BENEFICIARY_ID}}",
  "integratorId": "{{INTEGRATOR_ID}}",
  "integratorBeneficiaryId": "{{INTEGRATOR_BENEFICIARY_ID}}",
  "type": "BUSINESS",
  "person": null,
  "business": {
    "name": "{{BUSINESS_NAME}}",
    "dateOfIncorporation": "{{DATE_OF_INCORPORATION}}",
    "idNumber": "{{BUSINESS_ID_NUMBER}}",
    "address": {
      "streetOne": "{{BUSINESS_STREET_ONE}}",
      "streetTwo": "{{BUSINESS_STREET_TWO}}",
      "geolocation": null,
      "city": "{{BUSINESS_CITY}}",
      "zipcode": "{{BUSINESS_ZIPCODE}}",
      "state": "{{BUSINESS_STATE}}",
      "country": "{{BUSINESS_COUNTRY}}"
    },
    "telephone": null,
    "email": "{{BUSINESS_EMAIL}}",
    "contacts": [
      {
        "firstName": "{{CONTACT_FIRST_NAME}}",
        "lastName": "{{CONTACT_LAST_NAME}}",
        "dateOfBirth": "{{CONTACT_DATE_OF_BIRTH}}",
        "placeOfBirth": null,
        "citizenship": "{{CONTACT_CITIZENSHIP}}",
        "idNumber": "{{CONTACT_ID_NUMBER}}",
        "email": "{{CONTACT_EMAIL}}",
        "phoneNumber": "{{CONTACT_PHONE_NUMBER}}",
        "profession": null,
        "gender": null,
        "maritalStatus": null,
        "mothersName": null,
        "address": {
          "streetOne": "{{CONTACT_STREET_ONE}}",
          "streetTwo": "{{CONTACT_STREET_TWO}}",
          "geolocation": null,
          "city": "{{CONTACT_CITY}}",
          "zipcode": "{{CONTACT_ZIPCODE}}",
          "state": "{{CONTACT_STATE}}",
          "country": "{{CONTACT_COUNTRY}}"
        },
        "industry": null,
        "incomeSource": null,
        "annualIncome": null,
        "occupation": null,
        "wealthSource": null
      }
    ]
  },
  "localTargetBankAccount": null,
  "files": [],
  "active": true,
  "kycVerified": false,
  "status": "PENDING",
  "termsAndConditions": null,
  "hasValidPixKey": null,
  "createdDate": "{{CREATED_DATE}}",
  "riskScore": null,
  "beneficiaryLifeCycle": null
}

Understanding the response

The API returns a BeneficiaryResponse object with the following key fields:

id: Unique identifier assigned by Caliza
status: Current status of the beneficiary. Possible values:
- CREATED: Beneficiary record created
- PENDING: Awaiting KYX verification
- MANUAL_REVIEW: Requires manual review
- KYC_IN_PROGRESS: KYX verification in progress
- DISABLED: Beneficiary is disabled
- FAILED: KYX verification failed
kycVerified: Boolean indicating whether KYX verification is complete
active: Whether the beneficiary account is active
createdDate: Timestamp when the beneficiary was created

KYX verification process

When you create a beneficiary, the system automatically initiates the KYX (Know Your Customer/Business) verification process. This process verifies the beneficiary's identity and compliance status.

The KYX process begins automatically after a beneficiary is created. The system:

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 typically sends webhook notifications about KYX status changes
May direct users: End users may be directed to a third-party verification provider (such as AiPrise) to upload documents or complete verification steps

For individuals, the system typically requests:

Government-issued identification

For businesses, the system typically requests:

Proof of address
Business registration documents
Beneficial ownership information

You can monitor KYX status by:

Checking the status and kycVerified fields in the beneficiary response
Subscribing to webhook notifications
Using the GET /v1/beneficiaries/{beneficiaryId} endpoint to check current status
Using KYX-specific endpoints:
- 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

Important: Beneficiaries must complete KYX verification before they can execute certain transactions. Monitor the status and handle rejections or resubmissions as needed.

Check beneficiary status

After creating a beneficiary, you can check its status using the GET /v1/beneficiaries/{beneficiaryId} endpoint:

curl --location --request GET 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{BENEFICIARY_ID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}'

The response includes the current status and kycVerified fields, which indicate the beneficiary's verification state.

Next steps

Manage Recipients

Learn how to create recipients for payments.

Create Virtual Accounts

Set up virtual accounts for beneficiaries.

Send Your First Payment

Learn how to send payments to beneficiaries.