Direct KYC/KYB Verification
Direct verification lets you collect a beneficiary's identity documents and compliance data yourself and submit them to Caliza through the API — without redirecting the end user to a third-party provider. Use it when you own the end-user experience and want to keep users inside your own application.
This page covers the full direct verification lifecycle: uploading documents, (for businesses) adding related persons, creating the verification, and tracking the result.
If you would rather hand the user off to a hosted verification flow, see Interactive KYC/KYB Verification instead.
Prerequisites
- Authentication: A valid access token. See Authenticate.
- Beneficiary: A created beneficiary (individual or business). See Beneficiaries.
Direct vs. interactive
The verification mode is selected per beneficiary when you create the verification. Caliza automatically runs KYC for individual beneficiaries and KYB for business beneficiaries.
| Interactive | Direct | |
|---|---|---|
verificationMode | INTERACTIVE (default) | DIRECT |
| Who collects documents | The third-party provider's hosted flow | You, via the API |
verificationUrl in response | Present | null |
| Documents | Uploaded during the hosted flow | Must be uploaded before creating the verification |
| Initial status | PENDING | PROCESSING |
| Result delivery | Webhook / polling | Webhook / polling |
Step 1: Upload the beneficiary's documents
In direct mode you must upload the required documents before creating the verification. If any required document is missing, creating the verification returns 400 Bad Request.
Upload each document with a multipart/form-data POST to /v1/beneficiaries/{beneficiaryId}/documents:
curl -X POST 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{BENEFICIARY_ID}}/documents' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-F '[email protected]' \
-F '[email protected]' \
-F 'name=John Doe passport' \
-F 'type=PASSPORT'const form = new FormData();
form.append('documentFront', documentFrontFile); // File or Blob
form.append('documentBack', documentBackFile); // optional
form.append('name', 'John Doe passport');
form.append('type', 'PASSPORT');
await axios.post(
`https://api.sandbox.caliza.com/core-api/v1/beneficiaries/${beneficiaryId}/documents`,
form,
{
headers: {
'Authorization': `Bearer ${accessToken}`,
...form.getHeaders?.() // Node.js form-data; browsers set this automatically
}
}
);A successful upload returns 201 Created with no body.
Form fields
| Field | Type | Required | Description |
|---|---|---|---|
documentFront | file | Yes | Front side of the document |
documentBack | file | No | Back side of the document (when applicable) |
name | string | Yes | A descriptive name for the document |
type | string | Yes | Document type (see table below) |
Required documents
| Beneficiary type | ID document (one of) | Plus |
|---|---|---|
| Individual | PASSPORT, DRIVER_LICENSE, NATIONAL_ID, ID_CARD | one PROOF_OF_ADDRESS |
| Business | INCORPORATION_CERTIFICATE, TAX_REGISTRATION | one PROOF_OF_ADDRESS |
For business beneficiaries, each related person also needs their own identity document and proof of address — see Step 2.
Document types (type)
type)| Category | Values |
|---|---|
| Individual identity | PASSPORT, DRIVER_LICENSE, NATIONAL_ID, ID_CARD |
| Business | INCORPORATION_CERTIFICATE, TAX_REGISTRATION |
| Proof of address | PROOF_OF_ADDRESS |
Step 2: Add related persons (business beneficiaries only)
For KYB, every beneficial owner, director, or legal representative must be added as a related person and individually verified.
First create each related person with POST /v1/beneficiaries/{beneficiaryId}/related-persons — see Related Persons for the full field reference.
Then upload each related person's identity document and proof of address with a multipart/form-data POST to /v1/beneficiaries/{beneficiaryId}/related-persons/{id}/documents. The form fields are identical to Step 1:
curl -X POST 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{BENEFICIARY_ID}}/related-persons/{{RELATED_PERSON_ID}}/documents' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-F '[email protected]' \
-F '[email protected]' \
-F 'name=Jane Smith national ID' \
-F 'type=NATIONAL_ID'const form = new FormData();
form.append('documentFront', idFrontFile);
form.append('documentBack', idBackFile); // optional
form.append('name', 'Jane Smith national ID');
form.append('type', 'NATIONAL_ID');
await axios.post(
`https://api.sandbox.caliza.com/core-api/v1/beneficiaries/${beneficiaryId}/related-persons/${relatedPersonId}/documents`,
form,
{
headers: {
'Authorization': `Bearer ${accessToken}`,
...form.getHeaders?.()
}
}
);Each related person needs one individual ID document (from the individual list in Step 1) and one PROOF_OF_ADDRESS.
Step 3: Create the direct verification
Once all required documents are uploaded, create the verification with a POST to /v1/beneficiaries/{beneficiaryId}/verification and verificationMode set to DIRECT.
Individuals (KYC)
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}}' \
-d '{ "verificationMode": "DIRECT" }'const response = await axios.post(
`https://api.sandbox.caliza.com/core-api/v1/beneficiaries/${beneficiaryId}/verification`,
{ verificationMode: 'DIRECT' },
{
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${accessToken}`
}
}
);Businesses (KYB)
Business verifications require a KYB questionnaire in the kybAnswers object. All fields are required.
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}}' \
-d '{
"verificationMode": "DIRECT",
"kybAnswers": {
"accountUsageDescription": "Invoice financing and working capital management",
"primarySourceOfFunds": "B2B service revenue",
"calizaProductInterest": "USDC payments to international vendors",
"paymentCountries": "US, MX, BR",
"transactsWithSanctionedJurisdictions": "No",
"restrictedSectorsOrPurposes": "No",
"transactingPartyType": "On own behalf",
"dateOfIncorporation": "2020-01-15"
}
}'const response = await axios.post(
`https://api.sandbox.caliza.com/core-api/v1/beneficiaries/${beneficiaryId}/verification`,
{
verificationMode: 'DIRECT',
kybAnswers: {
accountUsageDescription: 'Invoice financing and working capital management',
primarySourceOfFunds: 'B2B service revenue',
calizaProductInterest: 'USDC payments to international vendors',
paymentCountries: 'US, MX, BR',
transactsWithSanctionedJurisdictions: 'No',
restrictedSectorsOrPurposes: 'No',
transactingPartyType: 'On own behalf',
dateOfIncorporation: '2020-01-15'
}
},
{
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${accessToken}`
}
}
);kybAnswers fields
kybAnswers fields| Field | Type | Description |
|---|---|---|
accountUsageDescription | string | How the business intends to use the account |
primarySourceOfFunds | string | Primary source of the funds that will flow through the account |
calizaProductInterest | string | Which Caliza products the business plans to use |
paymentCountries | string | Countries the business will send payments to or receive from |
transactsWithSanctionedJurisdictions | string | Whether the business transacts with sanctioned jurisdictions |
restrictedSectorsOrPurposes | string | Whether the business operates in restricted sectors or for restricted purposes |
transactingPartyType | string | Whether the business transacts on its own behalf or for third parties |
dateOfIncorporation | string | Date of incorporation (YYYY-MM-DD) |
Example response
{
"id": "00000000000000000000640b",
"beneficiaryId": "00000000000000000000640b",
"type": "INDIVIDUAL",
"verificationType": "DIRECT",
"verificationUrl": null,
"status": "PROCESSING",
"createdDate": "2025-01-15T16:47:20.568Z",
"lastModifiedDate": "2025-01-15T16:47:20.568Z"
}Response fields
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier of the verification session |
beneficiaryId | string | Identifier of the beneficiary being verified |
type | string | Beneficiary type: INDIVIDUAL or BUSINESS |
verificationType | string | Verification mode (DIRECT) |
verificationUrl | string | null | Always null for direct verifications |
status | string | Current verification status (see table below) |
createdDate | string | ISO 8601 timestamp of session creation |
lastModifiedDate | string | ISO 8601 timestamp of last status update |
If a required document is missing when you create the verification, the API returns
400 Bad Request. Upload the missing documents (Steps 1–2) and try again.
Step 4: Track verification status
Direct verifications are processed asynchronously. Track the result by polling or by 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);Verification statuses
| Status | Description |
|---|---|
PROCESSING | Documents received, verification is being processed |
AWAITING_DOC_VALIDATION | Awaiting manual document review |
HELD_FOR_DOC_REVIEW | On hold for manual document review |
SUCCEEDED | Verification completed successfully — the beneficiary is approved and can execute transactions |
FAILED | Verification failed — review the beneficiary status for details |
When a verification enters AWAITING_DOC_VALIDATION or HELD_FOR_DOC_REVIEW, a reviewer resolves it manually. See Document Validation and Review.
Webhooks
Subscribe to the following webhook events to receive real-time notifications:
| Event | Description |
|---|---|
BENEFICIARY_APPROVED | Beneficiary has been verified and approved |
BENEFICIARY_FAILED | Beneficiary verification has failed |
See Webhook Events for details on configuring webhook endpoints.
Sandbox: Manual verification approval
In sandbox environments, you can skip the verification provider and manually approve a beneficiary's direct verification. This is useful for testing the full flow without waiting for the asynchronous verification result.
After creating the direct verification (Step 3), 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 direct verification (Step 3).
Example response
{
"id": "00000000000000000000640b",
"beneficiaryId": "00000000000000000000640b",
"status": "SUCCEEDED"
}After approval, the verification is marked SUCCEEDED, the beneficiary status is updated to CREATED, and all downstream flows (webhook notifications, etc.) are triggered as if the verification completed normally.
This endpoint is only available in sandbox environments. Calling it in production returns a
412 Precondition Failederror.
Next steps
Updated 15 days ago
