Skip to content

Quick start

End-to-end integration in five steps. Should take about ten minutes if you already have API credentials.

1. Create an applicant

curl -X POST https://api.your-platform.example/v1/applicants \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Api-Secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_42",
    "type": "individual",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com"
  }'

The call is idempotent. Posting the same externalUserId returns the existing applicant with 200 OK instead of creating a duplicate.

Prefilling more fields? Send whatever you have — firstName, lastName, email, phone for individuals; the full company block (companyName, registrationNumber, legalForm, incorporationDate, registeredAddress, country, email, phone) for type: "company". The backend silently drops fields the resolved level doesn't enable; everything else is locked — the SDK renders it as disabled so the user can't overwrite what you sent, and POST /api/v1/sdk/personal-info refuses to mutate it server-side. See the Verification Levels guide for the per-level personalInfoFields / companyDataFields lists and the Field lock section for how to reopen a claim.

2. Assign a verification level (optional)

If you didn't pass verificationLevelName at creation, assign one now. The level (configured by your team in the product portal) decides which checks run. The level name is a short identifier like KYC_01 — same string you see on the level builder. Rename is locked once any applicant uses the level, so it's safe to hard-code.

curl -X POST \
  https://api.your-platform.example/v1/applicants/user_42/levels/KYC_01 \
  -H "X-Api-Key: $API_KEY" -H "X-Api-Secret: $API_SECRET"

curl -X POST \
  https://api.your-platform.example/v1/applicants/user_42/verification-sessions \
  -H "X-Api-Key: $API_KEY" -H "X-Api-Secret: $API_SECRET" \
  -d '{}'

Response:

{
  "url": "https://sdk.your-platform.example/?token=eyJhbGciOi…",
  "expiresAt": "2026-04-30T10:00:00Z"
}

Redirect the user to url. They complete every step the level requires (document upload, selfie, questionnaire) in the hosted UI and are returned to your site when done.

Don't want a hosted flow? POST /v1/applicants/{externalUserId}/verify takes the document images + selfie as base64 in a single call.

4. Listen for the webhook

When the user finishes (or anything else changes on the applicant), we POST a JSON event to your callback URL. Configure the URL once in the product portal — see Webhook integration for the full event catalog and signature-verification recipe.

5. Read the final state

Once you've received the webhook (or any time you want to check), fetch the applicant:

curl https://api.your-platform.example/v1/applicants/user_42 \
  -H "X-Api-Key: $API_KEY" -H "X-Api-Secret: $API_SECRET"

The response includes the current status, riskLevel, document upload timestamps, and the resolved verification result.

That's the whole loop — create → assign → run → webhook → read.