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.

Create a business beneficiary

Send a POST request to /v1/beneficiaries with type set to BUSINESS. You can optionally include contacts in the business object — these are automatically created as related persons.

With contacts

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-business-001",
    "type": "BUSINESS",
    "business": {
      "name": "Acme Corp",
      "dateOfIncorporation": "2015-06-10",
      "idNumber": "12345678000199",
      "email": "[email protected]",
      "phoneNumber": "+12025550199",
      "website": "https://acmecorp.com",
      "description": "Fintech company",
      "address": {
        "streetOne": "100 Market Street",
        "city": "San Francisco",
        "state": "CA",
        "zipcode": "94105",
        "country": "US"
      },
      "contacts": [
        {
          "firstName": "Alice",
          "lastName": "Johnson",
          "dateOfBirth": "1980-03-25",
          "citizenship": "US",
          "idNumber": "A1234567",
          "email": "[email protected]",
          "phoneNumber": "+12025550101",
          "address": {
            "streetOne": "100 Market Street",
            "city": "San Francisco",
            "state": "CA",
            "zipcode": "94105",
            "country": "US"
          }
        }
      ]
    }
  }'

{
  "id": "6925dd986a93002882da650a",
  "integratorId": "6920925fdbadfe09b1bf9e5e",
  "integratorBeneficiaryId": "my-business-001",
  "type": "BUSINESS",
  "business": {
    "name": "Acme Corp",
    "dateOfIncorporation": "2015-06-10",
    "idNumber": "12345678000199",
    "email": "[email protected]",
    "telephone": "+12025550199",
    "address": {
      "streetOne": "100 Market Street",
      "city": "San Francisco",
      "state": "CA",
      "zipcode": "94105",
      "country": "US"
    },
    "contacts": [
      {
        "firstName": "Alice",
        "lastName": "Johnson",
        "dateOfBirth": "1980-03-25",
        "citizenship": "US",
        "idNumber": "A1234567",
        "email": "[email protected]",
        "phoneNumber": "+12025550101",
        "address": {
          "streetOne": "100 Market Street",
          "city": "San Francisco",
          "state": "CA",
          "zipcode": "94105",
          "country": "US"
        }
      }
    ]
  },
  "active": true,
  "status": "PENDING",
  "createdDate": "2025-01-15T17:10:45.123456789Z"
}

📘
Contacts included in the business beneficiary request are automatically stored as related persons. You can retrieve, update, or delete them via the related persons endpoints described below.

Without contacts

If you don't have contact information at creation time, you can omit the contacts field and add related persons later through the dedicated endpoints:

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-business-002",
    "type": "BUSINESS",
    "business": {
      "name": "Globex Inc",
      "dateOfIncorporation": "2020-01-15",
      "idNumber": "98765432000188",
      "email": "[email protected]",
      "phoneNumber": "+12025550200",
      "address": {
        "streetOne": "200 Broadway",
        "city": "New York",
        "state": "NY",
        "zipcode": "10007",
        "country": "US"
      }
    }
  }'

{
  "id": "6925dd986a93002882da650b",
  "integratorId": "6920925fdbadfe09b1bf9e5e",
  "integratorBeneficiaryId": "my-business-002",
  "type": "BUSINESS",
  "business": {
    "name": "Globex Inc",
    "dateOfIncorporation": "2020-01-15",
    "idNumber": "98765432000188",
    "email": "[email protected]",
    "telephone": "+12025550200",
    "address": {
      "streetOne": "200 Broadway",
      "city": "New York",
      "state": "NY",
      "zipcode": "10007",
      "country": "US"
    },
    "contacts": []
  },
  "active": true,
  "status": "PENDING",
  "createdDate": "2025-01-15T17:15:30.987654321Z"
}

Business request fields

Field	Type	Required	Description
`name`	string	Yes	Business name (max 60 characters)
`dateOfIncorporation`	string	Yes	Date of incorporation in `yyyy-MM-dd` format
`idNumber`	string	Yes	Business registration number
`email`	string	Yes	Valid email address
`phoneNumber`	string	Yes	Phone number with country code
`address`	object	Yes	Address object (same structure as individual beneficiary)
`website`	string	No	Business website (max 100 characters)
`description`	string	No	Business description
`contacts`	array	No	List of person objects (same fields as individual `person`). Automatically created as related persons

Manage related persons

Related persons are individuals associated with a business beneficiary — for example, business contacts, legal representatives, or authorized signers. You can manage them through a dedicated set of CRUD endpoints nested under a beneficiary.

All related person endpoints require the beneficiary to be owned by the current integrator.

Create a related person

Send a POST request to /v1/beneficiaries/{beneficiaryId}/related-persons:

curl -X POST 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{BENEFICIARY_ID}}/related-persons' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1990-01-15",
    "citizenship": "BR",
    "idNumber": "12345678901",
    "email": "[email protected]",
    "phoneNumber": "+5511999999999",
    "address": {
      "streetOne": "Rua Test 123",
      "city": "São Paulo",
      "state": "SP",
      "zipcode": "01000-000",
      "country": "BR"
    }
  }'

{
  "id": "6925dd986a93002882da641c",
  "person": {
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1990-01-15",
    "citizenship": "BR",
    "idNumber": "12345678901",
    "email": "[email protected]",
    "phoneNumber": "+5511999999999",
    "address": {
      "streetOne": "Rua Test 123",
      "city": "São Paulo",
      "state": "SP",
      "zipcode": "01000-000",
      "country": "BR"
    }
  }
}

Request fields

Field	Type	Required	Description
`firstName`	string	Yes	First name (max 100 characters)
`lastName`	string	Yes	Last name (max 100 characters)
`dateOfBirth`	string	Yes	Date of birth in `yyyy-MM-dd` format
`citizenship`	string	Yes	ISO 3166-1 alpha-2 country code
`idNumber`	string	Yes	Government-issued ID number
`email`	string	Yes	Valid email address
`phoneNumber`	string	Yes	Phone number with country code (e.g., `+5511999999999`)
`address`	object	Yes	Address object (see below)
`placeOfBirth`	string	No	Place of birth
`profession`	string	No	Profession
`gender`	string	No	One of: `MALE`, `FEMALE`
`maritalStatus`	string	No	Marital status
`mothersName`	string	No	Mother's name
`industry`	string	No	Industry type
`incomeSource`	string	No	Income source type
`annualIncome`	number	No	Annual income
`occupation`	string	No	Occupation type
`wealthSource`	string	No	Wealth source type

Address object

Field	Type	Required	Description
`streetOne`	string	Yes	Street address
`city`	string	Yes	City
`state`	string	Yes	State code
`zipcode`	string	Yes	Postal code
`country`	string	Yes	ISO 3166-1 alpha-2 country code

List related persons

Send a GET request to /v1/beneficiaries/{beneficiaryId}/related-persons:

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

Returns an array of related person objects.

Get a related person

Send a GET request to /v1/beneficiaries/{beneficiaryId}/related-persons/{id}:

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

Update a related person

Send a PUT request to /v1/beneficiaries/{beneficiaryId}/related-persons/{id} with the full updated person object:

curl -X PUT 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{BENEFICIARY_ID}}/related-persons/{{RELATED_PERSON_ID}}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "firstName": "Updated",
    "lastName": "Name",
    "dateOfBirth": "1990-01-15",
    "citizenship": "BR",
    "idNumber": "12345678901",
    "email": "[email protected]",
    "phoneNumber": "+5511999999999",
    "address": {
      "streetOne": "Rua Updated 456",
      "city": "São Paulo",
      "state": "SP",
      "zipcode": "01000-000",
      "country": "BR"
    }
  }'

Delete a related person

Send a DELETE request to /v1/beneficiaries/{beneficiaryId}/related-persons/{id}:

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

Returns 204 No Content on success.

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.