--- updatedAt: 2026-05-29T16:52:18.000Z agentTools: projectIndex: https://docs.caliza.com/llms.txt --- # 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](/docs/authenticate). * **Beneficiary ID:** The `beneficiaryId` of an existing business beneficiary. See [Beneficiaries](/docs/manage-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 ```shell cURL 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": "maria.garcia@acme.example.com", "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" } }' ``` ```javascript JavaScript 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: 'maria.garcia@acme.example.com', 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 ```json { "id": "6930ab12c45d006789ef0123", "person": { "firstName": "Maria", "lastName": "Garcia", "dateOfBirth": "1978-04-12", "citizenship": "US", "idNumber": "P1234567", "email": "maria.garcia@acme.example.com", "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`: ```shell cURL curl -X GET 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{BENEFICIARY_ID}}/related-persons' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' ``` ```javascript JavaScript const response = await axios.get( `https://api.sandbox.caliza.com/core-api/v1/beneficiaries/${beneficiaryId}/related-persons`, { headers: { 'Authorization': `Bearer ${accessToken}` } } ); ``` ### Example response ```json [ { "id": "6930ab12c45d006789ef0123", "person": { "firstName": "Maria", "lastName": "Garcia", "dateOfBirth": "1978-04-12", "citizenship": "US", "idNumber": "P1234567", "email": "maria.garcia@acme.example.com", "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}`: ```shell cURL curl -X GET 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{BENEFICIARY_ID}}/related-persons/{{RELATED_PERSON_ID}}' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' ``` ```javascript JavaScript const response = await axios.get( `https://api.sandbox.caliza.com/core-api/v1/beneficiaries/${beneficiaryId}/related-persons/${relatedPersonId}`, { headers: { 'Authorization': `Bearer ${accessToken}` } } ); ``` ### Example response ```json { "id": "6930ab12c45d006789ef0123", "person": { "firstName": "Maria", "lastName": "Garcia", "dateOfBirth": "1978-04-12", "citizenship": "US", "idNumber": "P1234567", "email": "maria.garcia@acme.example.com", "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. ```shell cURL 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": "maria.garcia@acme.example.com", "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" } }' ``` ```javascript JavaScript 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: 'maria.garcia@acme.example.com', 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 ```json { "id": "6930ab12c45d006789ef0123", "person": { "firstName": "Maria", "lastName": "Garcia", "dateOfBirth": "1978-04-12", "citizenship": "US", "idNumber": "P1234567", "email": "maria.garcia@acme.example.com", "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. ```shell cURL curl -X DELETE 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{BENEFICIARY_ID}}/related-persons/{{RELATED_PERSON_ID}}' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' ``` ```javascript JavaScript 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 Manage beneficiary lifecycle and KYX verification. Learn about identity verification requirements. Walk through a complete payment flow.