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.

InteractiveDirect
verificationModeINTERACTIVE (default)DIRECT
Who collects documentsThe third-party provider's hosted flowYou, via the API
verificationUrl in responsePresentnull
DocumentsUploaded during the hosted flowMust be uploaded before creating the verification
Initial statusPENDINGPROCESSING
Result deliveryWebhook / pollingWebhook / 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

FieldTypeRequiredDescription
documentFrontfileYesFront side of the document
documentBackfileNoBack side of the document (when applicable)
namestringYesA descriptive name for the document
typestringYesDocument type (see table below)

Required documents

Beneficiary typeID document (one of)Plus
IndividualPASSPORT, DRIVER_LICENSE, NATIONAL_ID, ID_CARDone PROOF_OF_ADDRESS
BusinessINCORPORATION_CERTIFICATE, TAX_REGISTRATIONone 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)

CategoryValues
Individual identityPASSPORT, DRIVER_LICENSE, NATIONAL_ID, ID_CARD
BusinessINCORPORATION_CERTIFICATE, TAX_REGISTRATION
Proof of addressPROOF_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

FieldTypeDescription
accountUsageDescriptionstringHow the business intends to use the account
primarySourceOfFundsstringPrimary source of the funds that will flow through the account
calizaProductIntereststringWhich Caliza products the business plans to use
paymentCountriesstringCountries the business will send payments to or receive from
transactsWithSanctionedJurisdictionsstringWhether the business transacts with sanctioned jurisdictions
restrictedSectorsOrPurposesstringWhether the business operates in restricted sectors or for restricted purposes
transactingPartyTypestringWhether the business transacts on its own behalf or for third parties
dateOfIncorporationstringDate 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

FieldTypeDescription
idstringUnique identifier of the verification session
beneficiaryIdstringIdentifier of the beneficiary being verified
typestringBeneficiary type: INDIVIDUAL or BUSINESS
verificationTypestringVerification mode (DIRECT)
verificationUrlstring | nullAlways null for direct verifications
statusstringCurrent verification status (see table below)
createdDatestringISO 8601 timestamp of session creation
lastModifiedDatestringISO 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

StatusDescription
PROCESSINGDocuments received, verification is being processed
AWAITING_DOC_VALIDATIONAwaiting manual document review
HELD_FOR_DOC_REVIEWOn hold for manual document review
SUCCEEDEDVerification completed successfully — the beneficiary is approved and can execute transactions
FAILEDVerification 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:

EventDescription
BENEFICIARY_APPROVEDBeneficiary has been verified and approved
BENEFICIARY_FAILEDBeneficiary 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 Failed error.


Next steps


Did this page help you?