Beneficiary management
Create and manage your beneficiaries on our platform
Overview
- There is no limit to the number of
beneficiariesanintegratorcan create on our platform. - In production, each
beneficiaryundergoes AML/KYC checks to meet regulatory and compliance requirements. We've simplified this step in our sandbox environment.
Creating individual beneficiaries (View API reference)
When creating the beneficiary, you will need to use a valid
city,stateandpostal code. You will also need a uniquephoneNumber.
Field Details
- Address elements should be valid
- Gender options are [MALE, FEMALE, OTHER]
- Marital status options are [SINGLE, MARRIED]
- Email must have a valid form
- All fields are required.
- Citizenship, mothersName, placeOfBirth, profession, and sourceOfIncome are open string fields in which you can input anything.
curl --request POST \
--url https://sandbox.api.caliza.co/core-api/v1/beneficiaries \
--header 'Authorization: Bearer {{YOUR_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"integratorBeneficiaryId": "{your_integrator_beneficiary_id}",
"type": "INDIVIDUAL",
"person": {
"address": {
"city": "SomeCity",
"state": "Rio de Janeiro",
"streetOne": "555 A Street",
"zipcode": "12345",
"country": "Brazil"
},
"citizenship": "Brazil",
"dateOfBirth": "1975-02-02",
"email": "[email protected]",
"firstName": "TestBenTwo",
"gender": "MALE",
"idNumber": "{id_number}",
"lastName": "TestIntegrator1",
"maritalStatus": "Single",
"mothersName": "MotherOf PersonBenNine",
"phoneNumber": "{phone_number}",
"placeOfBirth": "Sao Paulo",
"profession": "Engineer",
"sourceOfIncome": "Job"
}
}'
This should return a JSON object that looks like this:
{
"id": "64c570d68d171d51e54bc616",
"integratorId": "64bea4abf8aaac3956c07844",
"integratorBeneficiaryId": "C99999-I99999",
"type": "INDIVIDUAL",
"person": {
"firstName": "Sandra",
"lastName": "Silva",
"dateOfBirth": "1992-10-10",
"idNumber": "542.877.765-99",
"email": "[email protected]",
"telephone": null,
"profession": "Engineer",
"gender": "MALE",
"address": {
"streetOne": "Street one",
"streetTwo": "Street two",
"geolocation": null,
"city": "City",
"zipcode": "1289289289",
"state": "State",
"country": "624472584d6d2578ff3d568e"
}
},
"business": null,
"localTargetBankAccount": null,
"files": [],
"active": true,
"kycVerified": false,
"status": "PENDING",
"termsAndConditions": null,
"createdDate": "2023-07-29T20:04:38.069650Z"
}
Creating business beneficiaries
Business beneficiaries represent business entities which own accounts. We require basic information about the business, including its legal address. In addition, we require basic personal information about the company's legal representative and all beneficial owners (individual shareholders who own >= 25% of the company).
The information for the legal representative and beneficial owners should be inserted as an array of objects in the "business.contacts" field.
Get beneficiaries by id (View API reference)
Returns a single beneficiary matching the id provided. This is the id field in the JSON object returned from creating the beneficiary (see above). In your dashboard, under Beneficiaries, it's labeled as Database id.
curl --request GET \
--url https://sandbox.api.caliza.co/core-api/v1/beneficiaries/64c570d68d171d51e54bc616
--header 'Authorization: Bearer {{YOUR_TOKEN}}'
Get multiple beneficiaries by query (View API reference)
- Sometimes you want a complete list of your beneficiaries, and sometimes you want to see a specific subset. We've got you covered!
- You can sort, filter, search for a list of beneficiaries passing the criteria as query params. We return the result as a page. Details on the query parameters that you can use for each are here: Pagination, filtering and Sorting
curl --request GET \
--url https://sandbox.api.caliza.co/core-api/v1/beneficiaries \
--header 'Authorization: Bearer {{your_token}}'
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("http://localhost:8080/core-api/v1/beneficiaries")
.get()
.addHeader("Accept", "*/*")
.build();
Response response = client.newCall(request).execute();
import requests
url = "http://localhost:8080/core-api/v1/beneficiaries"
headers = {"Accept": "*/*"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const options = {method: 'GET', headers: {Accept: '*/*'}};
fetch('http://localhost:8080/core-api/v1/beneficiaries', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
{
"content": [
{
"id": "630e473fbde8b33bab7490e9",
"integratorId": "630e461633afdc63d2a0b5a1",
"integratorBeneficiaryId": "C99999-I99999",
"type": "INDIVIDUAL",
"person": {
"firstName": "Sandra",
"lastName": "Silva",
"dateOfBirth": "1992-10-10",
"idNumber": "542.877.765-99",
"email": "[email protected]",
"telephone": "+571176677-5564",
"profession": "Professor",
"gender": "MALE",
"address": {
"streetOne": "Street one",
"streetTwo": "Street two",
"geolocation": null,
"city": "City",
"zipcode": "1289289289",
"state": "State",
"country": "6227f2783b237c66277d90c1"
}
},
"business": null,
"files": [],
"active": false,
"kycVerified": false,
"status": "PENDING"
},
{
"id": "630e488af9d2a030ac23f484",
"integratorId": "630e461633afdc63d2a0b5a1",
"integratorBeneficiaryId": "B99999-C99999",
"type": "BUSINESS",
"person": null,
"business": {
"name": "Corporation Integrator INC.",
"dateOfIncorporation": "2020-10-10",
"idNumber": "542.877.765-100",
"address": {
"streetOne": "Caliza street, 345",
"streetTwo": "Caliza building - 678",
"geolocation": null,
"city": "São Paulo",
"zipcode": "06783-999",
"state": "SP",
"country": "6227f2783b237c66277d90c1"
},
"telephone": "+551176677-5564",
"email": "[email protected]",
"contacts": [
{
"firstName": "First",
"lastName": "Last",
"dateOfBirth": "1992-10-10",
"idNumber": "542.877.765-99",
"email": "[email protected]",
"telephone": "+551176677-5564",
"profession": "Profession",
"gender": "MALE",
"address": {
"streetOne": "Street one",
"streetTwo": "Street two",
"geolocation": null,
"city": "City",
"zipcode": "zipcode number",
"state": "State",
"country": "630e2cfaa794547d4b80e3fa"
}
}
]
},
"files": [],
"active": false,
"kycVerified": false,
"status": "PENDING"
},
{
"id": "630e49c5437c4941722896ed",
"integratorId": "630e461633afdc63d2a0b5a1",
"integratorBeneficiaryId": "B99999-C09999",
"type": "BUSINESS",
"person": null,
"business": {
"name": "Corporation Integrator INC.",
"dateOfIncorporation": "2020-10-10",
"idNumber": "542.877.765-100",
"address": {
"streetOne": "Caliza street, 345",
"streetTwo": "Caliza building - 678",
"geolocation": null,
"city": "São Paulo",
"zipcode": "06783-999",
"state": "SP",
"country": "6227f2783b237c66277d90c1"
},
"telephone": "+551176677-5564",
"email": "[email protected]",
"contacts": [
{
"firstName": "First",
"lastName": "Last",
"dateOfBirth": "1992-10-10",
"idNumber": "542.877.765-99",
"email": "[email protected]",
"telephone": "+551176677-5564",
"profession": "Profession",
"gender": "MALE",
"address": {
"streetOne": "Street one",
"streetTwo": "Street two",
"geolocation": null,
"city": "City",
"zipcode": "zipcode number",
"state": "State",
"country": "630e2cfaa794547d4b80e3fa"
}
}
]
},
"files": [],
"active": false,
"kycVerified": false,
"status": "PENDING"
}
],
"pageable": {
"sort": {
"empty": true,
"unsorted": true,
"sorted": false
},
"offset": 0,
"pageNumber": 0,
"pageSize": 20,
"paged": true,
"unpaged": false
},
"last": true,
"totalPages": 1,
"totalElements": 3,
"first": true,
"size": 20,
"number": 0,
"sort": {
"empty": true,
"unsorted": true,
"sorted": false
},
"numberOfElements": 3,
"empty": false
}
Delete beneficiaries (View API reference)
Deletes the beneficiary matching the id provided
curl --request DELETE \
--url https://sandbox.api.caliza.co/core-api/v1/beneficiaries/{id}
--header 'Authorization: Bearer {{your_token}}'
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("http://localhost:8080/core-api/v1/beneficiaries/id")
.delete(null)
.build();
Response response = client.newCall(request).execute();
import requests
url = "http://localhost:8080/core-api/v1/beneficiaries/id"
response = requests.request("DELETE", url)
print(response.text)
const options = {method: 'DELETE'};
fetch('http://localhost:8080/core-api/v1/beneficiaries/id', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
Update beneficiaries (View API reference)
Updates the beneficiary in the provided fields
curl --request PUT \
--url https://sandbox.api.caliza.co/core-api/v1/beneficiaries/{id} \
--header 'Authorization: Bearer {{YOUR_TOKEN}}' \
--header 'Content-Type: application/json' \
-data-raw '{
"integratorBeneficiaryId": "B99999-C99999"
}'
Updated 3 months ago
What’s Next