Skip to navigation

Identity verification

This API is billed separately.

The Identity Verification API proves that a person controls the supplied CPF before a sensitive action. It is independent of account opening and bank accounts: create the journey, let the person complete the facial capture, then consume the approval once from your backend.

There are two capture methods, chosen with method at creation:

  • link (default): the API returns a verificationLink that opens the provider’s hosted page (Unico or DracmaTrust). Nothing to embed in your app.
  • facetec_sdk: your app embeds the FaceTec SDK v10, opens the camera and sends each capture to POST /v1/identity-verifications/{id}/facetec/process. Requires provider: dracma_trust, the identity_verification_facetec_sdk feature and the SDK keys configured by CorpX. Request the package (bundle id, application id, domains) before embedding — the request and accepted languages are in the facial capture guide. The in-app protocol is in Capture with the FaceTec SDK.

Prerequisites

  • a master M2M (client_credentials) credential, never a user session or delegated child credential;
  • the X-Tenant-Id header;
  • the identity_verification.manage scope;
  • the identity_verification tenant feature for creation;
  • a callbackUri registered under Identity verifications in the panel, compared exactly.

The credential needs the dedicated kyc.read scope to download KYC evidence.

Create the verification

curl -X POST "https://tenant.api.corpx.com/v1/identity-verifications" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
-d '{
"document": "12345678909",
"purpose": "password_reset",
"referenceId": "usr_01J8Y6N7M8P9Q0R1S2T3",
"displayMessage": "Confirm your identity to reset your password.",
"callbackUri": "https://app.example.com/identity-verification/return",
"ttlMinutes": 30,
"consumeTtlMinutes": 10
}'
FieldRule
documentCPF, exactly 11 digits without punctuation
purposepassword_reset, second_factor_reset, high_value_transaction, or sensitive_action
referenceIdRequired; your action ID and the binding used at consumption
displayMessageOptional plain text, up to 240 characters
callbackUriRegistered URI, exactly as sent
ttlMinutesJourney lifetime; default 30, maximum 60
consumeTtlMinutesWindow to consume after approval; default 10, maximum 60
providerOptional: unico or dracma_trust; defaults to the provider configured for the tenant
methodOptional: link (default) or facetec_sdk (requires provider: dracma_trust)
referenceMatchfacetec_sdk only: none, dracma (default) or image — see the match modes

Do not send Idempotency-Key: every POST intentionally creates a fresh proof and consumes one quota unit when it returns 201.

201 response with method: link:

{
"verificationId": "idv_01J8Y7C8D9E0F1G2H3J4",
"status": "PENDING",
"provider": "unico",
"method": "link",
"verificationLink": "https://tenant.api.corpx.com/v1/identity-verifications/verify#capability-redacted",
"expiresAt": "2026-09-24T14:30:00Z"
}

Give verificationLink only to the person who owns the CPF. Do not treat the return to callbackUri as proof of approval: query the resource or process the webhook, then call the consumption endpoint.

Monthly quota per kind

The quota is counted per verification kind, per tenant and per BRT calendar month: link_unico, link_dracma, liveness (facetec_sdk + none), face_match_image (facetec_sdk + image) and face_match_cpf (facetec_sdk + dracma). Link kinds start at 10; SDK kinds start at 0 and return 403 identity_verification_kind_not_enabled until CorpX enables the kind for the tenant. Every 201 consumes one slot of its kind even if the verification later fails, expires, or is never consumed, and quota is never refunded. A closed quota returns HTTP 429 with identity_verification_monthly_limit_exceeded and details.kind. The rate_limited error also uses HTTP 429, but it is a separate traffic control shared by all kinds. The X-RateLimit-* headers on the 201 describe the kind of the verification created.

Capture with the FaceTec SDK

With method: facetec_sdk your app controls the camera. The 201 carries no verificationLink; it carries the facetec block the SDK needs:

{
"verificationId": "idv_01J8Y7C8D9E0F1G2H3J4",
"status": "PENDING",
"provider": "dracma_trust",
"method": "facetec_sdk",
"referenceMatch": "dracma",
"attemptsRemaining": 3,
"expiresAt": "2026-09-24T14:30:00Z",
"facetec": {
"sessionToken": "…",
"sessionTokenExpiresAt": "2026-09-24T14:10:00Z",
"deviceKeyIdentifier": "…"
}
}

Flow in the app (Browser SDK v10):

  1. Keep sessionToken on your backend. Initialize the SDK with deviceKeyIdentifier only (FaceTecSDK.initializeWithSessionRequest). Initialization already produces a requestBlob and counts toward the 15-call limit.
  2. For each requestBlob (the init one and each capture, 1–3 MB in base64), send one call to POST /v1/identity-verifications/{id}/facetec/process with Content-Type: application/json, sessionId set to that sessionToken and, in image mode, the referenceImage (base64 JPEG/PNG, up to 2 MB; a face photo, never a document).
  3. Hand responseBlob back to the SDK via processResponse. The response also carries processed, status, attemptsRemaining, checks and, on a definitive failure, failureReason.
  4. When the session token expires (10 minutes) or /process returns 409 facetec_session_expired, request another one from POST /v1/identity-verifications/{id}/facetec/session and reopen the SDK.
curl -X POST \
"https://tenant.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/facetec/process" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
-d '{ "requestBlob": "<base64 from the SDK>", "sessionId": "<sessionToken from the 201>" }'

Journey limits:

  • 3 rejected captures close the verification as FAILED (liveness_failed or face_mismatch). Captures the provider did not process (processed: false, e.g. out of focus) do not count.
  • Up to 15 calls to /process per verification; the 16th returns 429 facetec_attempts_exhausted and the verification fails.
  • One capture at a time: while a call is in flight another one returns 409 facetec_process_in_progress with Retry-After.
  • Body up to 5 MB; above that, 413 payload_too_large (details.maxBytes).
  • /facetec/session can be called at any time while PENDING, throttled to 1 every 5 s and 30 per verification (429 facetec_session_renewal_limited).

The match modes

referenceMatchWhat is provenCompared againstQuota kind
noneA live person is in front of the camera (3D liveness / PAD)nobodyliveness
dracma (default)Liveness and the face belongs to the CPFDracmaTrust’s reference base for the CPF (1:1, 3D:2D)face_match_cpf
imageLiveness and the face matches a photo you sendreferenceImage sent in /process (1:1, 3D:2D)face_match_image

An APPROVED with referenceMatch: none only proves that a live person completed the capture — it does not prove who they are. Read checks.faceMatch.result (not_performed) and treat it as a step-up for an already-authenticated session, never as onboarding. When a match mode is not yet available at the provider, creation returns 422 facetec_match_unavailable; the API never silently downgrades to liveness-only.

Recommendation: password_reset and second_factor_reset → dracma or image (prove identity); high_value_transaction and sensitive_action inside an authenticated session → none is acceptable when the person was already identified at login; link remains the right choice when you do not control the device.

Track the state

curl "https://tenant.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID"
StatusMeaning
PENDINGThe person can still complete the journey; verificationLink is present (link) or attemptsRemaining is reported (facetec_sdk)
APPROVEDIdentity approved; consume by consumableUntil
FAILEDVerification rejected; inspect failureReason
EXPIREDThe journey expired without approval

The response also carries purpose, referenceId, document, provider, method, expiresAt, and, when applicable, failureReason, completedAt, consumableUntil, and consumedAt. verificationLink appears only while PENDING with method: link. With method: facetec_sdk the response also carries referenceMatch, attemptsRemaining and checks ({"liveness": "pending|passed|failed", "faceMatch": {"result": "pending|passed|failed|not_performed", "reference": "dracma|image"}}). liveness_failed and face_mismatch are the SDK-specific failureReason values.

Consume the approval

Consumption binds the proof to the action you are about to execute:

curl -X POST \
"https://tenant.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/consume" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
-d '{
"purpose": "password_reset",
"referenceId": "usr_01J8Y6N7M8P9Q0R1S2T3"
}'

purpose and referenceId must exactly match creation. The first valid call sets consumedAt. Retrying the exact same verificationId and body is idempotent and returns the same result. A different reference or purpose, a competing consume, a state other than APPROVED, or an elapsed consumption window returns 409.

Keep consumption and the sensitive action in the same logical backend unit. Do not authorize the action merely because GET showed APPROVED: without consumption, concurrent requests could reuse the same proof.

Callback and webhook

callbackUri returns the browser to your app; it is not a server notification. The value must match the tenant registration exactly—no wildcard, prefix matching, or query-string normalization.

For terminal states APPROVED, FAILED, and EXPIRED, the platform sends identity.verification.completed. Verify X-Signature against the raw request body and deduplicate on the envelope id. See the complete payload in Webhooks.

KYC artifacts

curl \
"https://tenant.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/artifacts" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID"

This route uses kyc.read instead of the management scope and requires the kyc_artifacts feature. The files may contain biometrics and identity material: do not log URLs or contents, and apply your KYC retention policy.

Main errors

HTTPerrorCodeAction
400invalid_document, invalid_purpose, invalid_reference_idCorrect the named field
400invalid_display_message, invalid_verification_ttl, invalid_consume_ttlFollow the documented plain-text and range rules
400invalid_callback_uriSend an exactly registered URI
400invalid_provider, invalid_method, invalid_reference_matchCombine provider, method and referenceMatch as documented
400reference_image_requiredIn image mode, send referenceImage to /facetec/process
403feature_disabledRequest feature enablement
403facetec_sdk_not_enabledAsk CorpX for the identity_verification_facetec_sdk feature and the SDK keys
403identity_verification_kind_not_enabledThe kind (details.kind) has quota 0; ask for enablement
403insufficient_scopeUse identity_verification.manage for journeys and kyc.read for artifacts
403forbiddenUse the master M2M credential
404verification_not_foundCheck the ID and X-Tenant-Id
409verification_not_consumableCheck state, window, purpose, and referenceId
409reference_already_consumedAnother proof already consumed that purpose/reference
409verification_method_mismatch, verification_not_pendingThe route does not apply to this method or state
409facetec_process_in_progressWait Retry-After and resend the same capture
409facetec_session_expiredRenew at /facetec/session and reopen the SDK
413payload_too_largeShrink the requestBlob (details.maxBytes)
415unsupported_media_typeSend Content-Type: application/json
422facetec_match_unavailableThe match mode is not available yet; use another referenceMatch or link
429identity_verification_monthly_limit_exceededQuota of the kind (details.kind) is closed; wait for the next BRT month
429facetec_attempts_exhaustedToo many captures; the verification failed, create another
429facetec_session_renewal_limitedWait Retry-After before renewing the session
429rate_limitedReduce request frequency and retry
502provider_errorProvider failure; inspect partner and retry
503facetec_unavailableSDK unavailable at the provider; retry later or use link