Beneficiaries

Caliza beneficiaries represent the holders and senders of funds within the Caliza platform. This section provides a practical guide to interacting with both Business and Individual beneficiaries. Below, you will find detailed instructions and cURL examples for creating a beneficiary, retrieving a beneficiary's current status, and updating beneficiary information.

Prerequisites

Before you begin managing beneficiaries or executing transactions, ensure you have the following configurations in place:

Base URL: All requests in this guide target the Sandbox environment: https://api.sandbox.caliza.com.
Authentication: You must have a valid Access Token. Include this token in the header of every request as Authorization: Bearer YOUR_TOKEN. To learn how to authenticate, refer to the Authenticate with the Caliza API documentation.
Integrator ID: You will need your unique integratorId. You can retrieve this by calling the GET /v1/integrators/me endpoint. For detailed instructions, refer to the Get the Integrator ID documentation.
Headers: Ensure all POST, PUT, and PATCH requests include the header Content-Type: application/json.

For detailed information about required and optional fields when creating beneficiaries, refer to the Create Beneficiaries documentation.

Create an individual beneficiary

To create an individual beneficiary using cURL, you need to send a POST request to the /beneficiaries endpoint with your access token and the details for the beneficiary you want to create.

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 '{
  "integratorId": "{{INTEGRATOR_ID}}",
  "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}}"
    }
  },
  "localTargetBankAccount": {
      "accountDetails": {
          "routingNumber": "{{ROUTING_NUMBER}}",
          "accountNumber": "{{ACCOUNT_NUMBER}}"
      }
  },
  "active": {{ACTIVE}}
}'

{
    "id": "{{BENEFICIARY_ID}}",
    "integratorId": "{{INTEGRATOR_ID}}",
    "integratorBeneficiaryId": "{{INTEGRATOR_BENEFICIARY_ID}}",
    "type": "INDIVIDUAL",
    "person": {
        "firstName": "{{FIRST_NAME}}",
        "lastName": "{{LAST_NAME}}",
        "dateOfBirth": "{{DATE_OF_BIRTH}}",
        "placeOfBirth": {{PLACE_OF_BIRTH}},
        "citizenship": "{{CITIZENSHIP}}",
        "idNumber": "{{ID_NUMBER}}",
        "email": "{{EMAIL}}",
        "phoneNumber": "{{PHONE_NUMBER}}",
        "profession": {{PROFESSION}},
        "gender": {{GENDER}},
        "maritalStatus": {{MARITAL_STATUS}},
        "mothersName": {{MOTHERS_NAME}},
        "address": {
            "streetOne": "{{STREET_ONE}}",
            "streetTwo": "{{STREET_TWO}}",
            "geolocation": {{GEOLOCATION}},
            "city": "{{CITY}}",
            "zipcode": "{{ZIPCODE}}",
            "state": "{{STATE}}",
            "country": "{{COUNTRY}}"
        },
        "industry": {{INDUSTRY}},
        "incomeSource": {{INCOME_SOURCE}},
        "annualIncome": {{ANNUAL_INCOME}},
        "occupation": {{OCCUPATION}},
        "wealthSource": {{WEALTH_SOURCE}}
    },
    "business": null,
    "localTargetBankAccount": {
        "accountNumber": "{{ACCOUNT_NUMBER}}"
    },
    "files": [],
    "active": {{ACTIVE}},
    "kycVerified": {{KYC_VERIFIED}},
    "status": "{{STATUS}}",
    "termsAndConditions": {{TERMS_AND_CONDITIONS}},
    "hasValidPixKey": {{HAS_VALID_PIX_KEY}},
    "createdDate": "{{CREATED_DATE}}",
    "riskScore": {{RISK_SCORE}},
    "beneficiaryLifeCycle": {{BENEFICIARY_LIFECYCLE}}
}

Check the beneficiary status

To check the status of a beneficiary, you can use the following cURL command. Replace YOUR_TOKEN with your actual access token and beneficiary_id with the ID of the beneficiary you want to check:

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

{
    "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": "{{STREET_ONE}}",
            "streetTwo": "{{STREET_TWO}}",
            "geolocation": {{GEOLOCATION}},
            "city": "{{CITY}}",
            "zipcode": "{{ZIPCODE}}",
            "state": "{{STATE}}",
            "country": "{{COUNTRY}}"
        },
        "telephone": {{TELEPHONE}},
        "email": "{{BUSINESS_EMAIL}}",
        "contacts": [
            {
                "firstName": "{{CONTACT_FIRST_NAME}}",
                "lastName": "{{CONTACT_LAST_NAME}}",
                "dateOfBirth": "{{CONTACT_DATE_OF_BIRTH}}",
                "placeOfBirth": {{CONTACT_PLACE_OF_BIRTH}},
                "citizenship": "{{CONTACT_CITIZENSHIP}}",
                "idNumber": "{{CONTACT_ID_NUMBER}}",
                "email": "{{CONTACT_EMAIL}}",
                "phoneNumber": "{{CONTACT_PHONE_NUMBER}}",
                "profession": {{CONTACT_PROFESSION}},
                "gender": {{CONTACT_GENDER}},
                "maritalStatus": {{CONTACT_MARITAL_STATUS}},
                "mothersName": {{CONTACT_MOTHERS_NAME}},
                "address": {
                    "streetOne": "{{CONTACT_STREET_ONE}}",
                    "streetTwo": "{{CONTACT_STREET_TWO}}",
                    "geolocation": {{CONTACT_GEOLOCATION}},
                    "city": "{{CONTACT_CITY}}",
                    "zipcode": "{{CONTACT_ZIPCODE}}",
                    "state": "{{CONTACT_STATE}}",
                    "country": "{{CONTACT_COUNTRY}}"
                },
                "industry": {{CONTACT_INDUSTRY}},
                "incomeSource": {{CONTACT_INCOME_SOURCE}},
                "annualIncome": {{CONTACT_ANNUAL_INCOME}},
                "occupation": {{CONTACT_OCCUPATION}},
                "wealthSource": {{CONTACT_WEALTH_SOURCE}}
            }
        ]
    },
    "localTargetBankAccount": {{LOCAL_TARGET_BANK_ACCOUNT}},
    "files": [],
    "active": {{ACTIVE}},
    "kycVerified": {{KYC_VERIFIED}},
    "status": "{{STATUS}}",
    "termsAndConditions": {{TERMS_AND_CONDITIONS}},
    "hasValidPixKey": {{HAS_VALID_PIX_KEY}},
    "createdDate": "{{CREATED_DATE}}",
    "riskScore": {{RISK_SCORE}},
    "beneficiaryLifeCycle": {{BENEFICIARY_LIFECYCLE}}
}

The response provides details about the beneficiary, including its current status. Look for the status field in the response to determine the beneficiary's KYX verification status. The status field can be one of the following values: CREATED, PENDING, MANUAL_REVIEW, KYC_IN_PROGRESS, DISABLED, or FAILED.

Create business beneficiary

To create a business beneficiary using cURL, you need to send a POST request to the /beneficiaries endpoint with your access token and the details for the beneficiary you want to create.

curl -s --location --request POST 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--data-raw '{
  "integratorId": "{{INTEGRATOR_ID}}",
  "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}}",
    "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}}"
        }
      }
    ],
    "address": {
      "streetOne": "{{STREET_ONE}}",
      "streetTwo": "{{STREET_TWO}}",
      "city": "{{CITY}}",
      "zipcode": "{{ZIPCODE}}",
      "state": "{{STATE}}",
      "country": "{{COUNTRY}}"
    }
  }
}'

{
    "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": "{{STREET_ONE}}",
            "streetTwo": "{{STREET_TWO}}",
            "geolocation": null,
            "city": "{{CITY}}",
            "zipcode": "{{ZIPCODE}}",
            "state": "{{STATE}}",
            "country": "{{COUNTRY}}"
        },
        "telephone": "{{TELEPHONE}}",
        "email": "{{BUSINESS_EMAIL}}",
        "website": "{{BUSINESS_WEBSITE}}",
        "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": {{ACTIVE}},
    "kycVerified": {{KYC_VERIFIED}},
    "status": "{{STATUS}}",
    "termsAndConditions": null,
    "hasValidPixKey": null,
    "createdDate": "{{CREATED_DATE}}",
    "riskScore": null,
    "beneficiaryLifeCycle": null
}

The response includes the beneficiary ID and other relevant information. The status field indicates the current KYX verification status, which can be CREATED, PENDING, MANUAL_REVIEW, KYC_IN_PROGRESS, DISABLED, or FAILED (as defined in the API specification).