Related Persons

Related persons are individuals associated with a business beneficiary — such as beneficial owners, directors, legal representatives, or authorized signatories. They are required for KYB compliance to identify individuals who own or control a beneficiary entity.

This page covers how to create, retrieve, update, and delete related persons for a beneficiary.

Prerequisites

Authentication: A valid access token. See Authenticate.
Beneficiary ID: The beneficiaryId of an existing business beneficiary. See Beneficiaries.

Create a related person

Send a POST request to /v1/beneficiaries/{beneficiaryId}/related-persons with the person's details.

Required fields

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

Optional fields

Field	Type	Description
`address.streetTwo`	string	Secondary address line (max 100 characters)
`placeOfBirth`	string	Place of birth
`profession`	string	Profession
`gender`	string	`MALE`, `FEMALE`, or `OTHER`
`maritalStatus`	string	Marital status
`mothersName`	string	Mother's name
`industry`	string	Industry (see enum values in API spec)
`incomeSource`	string	Source of income (see enum values in API spec)
`annualIncome`	number	Annual income
`occupation`	string	Occupation (see enum values in API spec)
`wealthSource`	string	Source of wealth (see enum values in API spec)

Example request

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": "Maria",
    "lastName": "Garcia",
    "dateOfBirth": "1978-04-12",
    "citizenship": "US",
    "idNumber": "P1234567",
    "email": "[email protected]",
    "phoneNumber": "+12125550199",
    "profession": "Chief Financial Officer",
    "gender": "FEMALE",
    "address": {
      "streetOne": "350 Fifth Avenue",
      "streetTwo": "Suite 1200",
      "city": "New York",
      "zipcode": "10118",
      "state": "NY",
      "country": "US"
    }
  }'

const response = await axios.post(
  `https://api.sandbox.caliza.com/core-api/v1/beneficiaries/${beneficiaryId}/related-persons`,
  {
    firstName: 'Maria',
    lastName: 'Garcia',
    dateOfBirth: '1978-04-12',
    citizenship: 'US',
    idNumber: 'P1234567',
    email: '[email protected]',
    phoneNumber: '+12125550199',
    profession: 'Chief Financial Officer',
    gender: 'FEMALE',
    address: {
      streetOne: '350 Fifth Avenue',
      streetTwo: 'Suite 1200',
      city: 'New York',
      zipcode: '10118',
      state: 'NY',
      country: 'US'
    }
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

Example response

{
  "id": "6930ab12c45d006789ef0123",
  "person": {
    "firstName": "Maria",
    "lastName": "Garcia",
    "dateOfBirth": "1978-04-12",
    "citizenship": "US",
    "idNumber": "P1234567",
    "email": "[email protected]",
    "phoneNumber": "+12125550199",
    "profession": "Chief Financial Officer",
    "gender": "FEMALE",
    "address": {
      "streetOne": "350 Fifth Avenue",
      "streetTwo": "Suite 1200",
      "city": "New York",
      "zipcode": "10118",
      "state": "NY",
      "country": "US"
    }
  }
}

List related persons

Retrieve all related persons for a beneficiary with GET /v1/beneficiaries/{beneficiaryId}/related-persons:

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

const response = await axios.get(
  `https://api.sandbox.caliza.com/core-api/v1/beneficiaries/${beneficiaryId}/related-persons`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

Example response

[
  {
    "id": "6930ab12c45d006789ef0123",
    "person": {
      "firstName": "Maria",
      "lastName": "Garcia",
      "dateOfBirth": "1978-04-12",
      "citizenship": "US",
      "idNumber": "P1234567",
      "email": "[email protected]",
      "phoneNumber": "+12125550199",
      "profession": "Chief Financial Officer",
      "gender": "FEMALE",
      "address": {
        "streetOne": "350 Fifth Avenue",
        "streetTwo": "Suite 1200",
        "city": "New York",
        "zipcode": "10118",
        "state": "NY",
        "country": "US"
      }
    }
  }
]

Get a related person

Retrieve a specific related person by ID with GET /v1/beneficiaries/{beneficiaryId}/related-persons/{id}:

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

const response = await axios.get(
  `https://api.sandbox.caliza.com/core-api/v1/beneficiaries/${beneficiaryId}/related-persons/${relatedPersonId}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

Example response

{
  "id": "6930ab12c45d006789ef0123",
  "person": {
    "firstName": "Maria",
    "lastName": "Garcia",
    "dateOfBirth": "1978-04-12",
    "citizenship": "US",
    "idNumber": "P1234567",
    "email": "[email protected]",
    "phoneNumber": "+12125550199",
    "profession": "Chief Financial Officer",
    "gender": "FEMALE",
    "address": {
      "streetOne": "350 Fifth Avenue",
      "streetTwo": "Suite 1200",
      "city": "New York",
      "zipcode": "10118",
      "state": "NY",
      "country": "US"
    }
  }
}

Update a related person

Update an existing related person with PUT /v1/beneficiaries/{beneficiaryId}/related-persons/{id}. Send the full person object with the updated fields.

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": "Maria",
    "lastName": "Garcia",
    "dateOfBirth": "1978-04-12",
    "citizenship": "US",
    "idNumber": "P1234567",
    "email": "[email protected]",
    "phoneNumber": "+12125550200",
    "profession": "Chief Executive Officer",
    "gender": "FEMALE",
    "address": {
      "streetOne": "350 Fifth Avenue",
      "streetTwo": "Suite 1500",
      "city": "New York",
      "zipcode": "10118",
      "state": "NY",
      "country": "US"
    }
  }'

const response = await axios.put(
  `https://api.sandbox.caliza.com/core-api/v1/beneficiaries/${beneficiaryId}/related-persons/${relatedPersonId}`,
  {
    firstName: 'Maria',
    lastName: 'Garcia',
    dateOfBirth: '1978-04-12',
    citizenship: 'US',
    idNumber: 'P1234567',
    email: '[email protected]',
    phoneNumber: '+12125550200',
    profession: 'Chief Executive Officer',
    gender: 'FEMALE',
    address: {
      streetOne: '350 Fifth Avenue',
      streetTwo: 'Suite 1500',
      city: 'New York',
      zipcode: '10118',
      state: 'NY',
      country: 'US'
    }
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

Example response

{
  "id": "6930ab12c45d006789ef0123",
  "person": {
    "firstName": "Maria",
    "lastName": "Garcia",
    "dateOfBirth": "1978-04-12",
    "citizenship": "US",
    "idNumber": "P1234567",
    "email": "[email protected]",
    "phoneNumber": "+12125550200",
    "profession": "Chief Executive Officer",
    "gender": "FEMALE",
    "address": {
      "streetOne": "350 Fifth Avenue",
      "streetTwo": "Suite 1500",
      "city": "New York",
      "zipcode": "10118",
      "state": "NY",
      "country": "US"
    }
  }
}

Delete a related person

Remove a related person from a beneficiary with DELETE /v1/beneficiaries/{beneficiaryId}/related-persons/{id}. Use this when a person is no longer associated with the beneficiary entity — for example, when an owner sells their stake or a director resigns.

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

const response = await axios.delete(
  `https://api.sandbox.caliza.com/core-api/v1/beneficiaries/${beneficiaryId}/related-persons/${relatedPersonId}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

A successful deletion returns a 204 No Content response with no body.

Next steps

Beneficiaries

Manage beneficiary lifecycle and KYX verification.

KYC/KYB Verification

Learn about identity verification requirements.

Send Your First Payment

Walk through a complete payment flow.