KYC/KYB Verification

KYC (Know Your Customer) and KYB (Know Your Business) verification ensures that beneficiaries are identity-verified before they can execute certain transactions. The Caliza API uses an interactive verification flow where end users are redirected to a third-party provider to complete the process.

This page covers the full interactive verification lifecycle: creating a verification session, redirecting the user, and tracking the result.

Prerequisites

• Authentication: A valid access token. See Authenticate.
• Beneficiary: A created beneficiary (individual or business). See Beneficiaries.

How interactive verification works

1. Create a verification session — The API returns a verificationUrl pointing to the third-party provider.
2. Redirect the user — Send the end user to the verificationUrl to complete identity verification.
3. Track the result — Poll the verification status or listen for webhook notifications.

The system automatically selects KYC for individual beneficiaries and KYB for business beneficiaries.

Step 1: Create a verification session

Create an interactive verification session by sending a POST request to /v1/beneficiaries/{beneficiaryId}/verification:

curl -X POST 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{BENEFICIARY_ID}}/verification' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

const response = await axios.post(
  `https://api.sandbox.caliza.com/core-api/v1/beneficiaries/${beneficiaryId}/verification`,
  {},
  {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

const { verificationUrl } = response.data;

response = requests.post(
  f'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{beneficiary_id}/verification',
  headers={
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {access_token}'
  }
)

verification_url = response.json()['verificationUrl']

The request body is optional. If omitted, the verification defaults to interactive mode.

Example response

{
  "id": "6925dd986a93002882da640b",
  "beneficiaryId": "6925dd986a93002882da640b",
  "type": "INDIVIDUAL",
  "verificationType": "INTERACTIVE",
  "verificationUrl": "https://verification.aiprise.com/session/abc123",
  "status": "PENDING",
  "createdDate": "2025-01-15T16:47:20.568Z",
  "lastModifiedDate": "2025-01-15T16:47:20.568Z"
}

Response fields

Step 2: Redirect the user

Take the verificationUrl from the response and redirect the end user to it. The user will complete the identity verification process on the third-party provider's interface (e.g., uploading ID documents, taking a selfie).

Once the user finishes, the third-party provider notifies Caliza asynchronously. The verification status will update from PENDING to either SUCCEEDED or FAILED.

Step 3: Track verification status

After redirecting the user, track the verification result by polling or subscribing to webhooks.

Polling

Send a GET request to /v1/beneficiaries/{beneficiaryId}/verification:

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

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

console.log(response.data.status); // PENDING, PROCESSING, SUCCEEDED, or FAILED

response = requests.get(
  f'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{beneficiary_id}/verification',
  headers={
    'Authorization': f'Bearer {access_token}'
  }
)

print(response.json()['status'])  # PENDING, PROCESSING, SUCCEEDED, or FAILED

Verification statuses

Webhooks

Subscribe to the following webhook events to receive real-time notifications:

See Webhook Events for details on configuring webhook endpoints.

Sandbox: Manual verification approval

In sandbox environments, you can skip the third-party verification provider and manually approve a beneficiary's verification. This is useful for testing the full flow without completing the interactive verification process.

After creating a verification session (Step 1), instead of redirecting the user, call the sandbox approval endpoint:

curl -X POST 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{BENEFICIARY_ID}}/verification/sandbox/approve' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{ "workflowId": "{{VERIFICATION_ID}}" }'

const response = await axios.post(
  `https://api.sandbox.caliza.com/core-api/v1/beneficiaries/${beneficiaryId}/verification/sandbox/approve`,
  { workflowId: verificationId },
  {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

The workflowId is the id returned when creating the verification session.

Example response

{
  "id": "6925dd986a93002882da640b",
  "beneficiaryId": "6925dd986a93002882da640b",
  "status": "SUCCEEDED"
}

After approval, the beneficiary status is updated to CREATED and all downstream flows (webhook notifications, etc.) are triggered as if the verification completed normally.

Next steps