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 averificationLinkthat 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 toPOST /v1/identity-verifications/{id}/facetec/process. Requiresprovider: dracma_trust, theidentity_verification_facetec_sdkfeature 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-Idheader; - the
identity_verification.managescope; - the
identity_verificationtenant feature for creation; - a
callbackUriregistered under Identity verifications in the panel, compared exactly.
The credential needs the dedicated kyc.read scope to download KYC evidence.
Create the verification
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:
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.
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:
Flow in the app (Browser SDK v10):
- Keep
sessionTokenon your backend. Initialize the SDK withdeviceKeyIdentifieronly (FaceTecSDK.initializeWithSessionRequest). Initialization already produces arequestBloband counts toward the 15-call limit. - For each
requestBlob(the init one and each capture, 1–3 MB in base64), send one call toPOST /v1/identity-verifications/{id}/facetec/processwithContent-Type: application/json,sessionIdset to thatsessionTokenand, inimagemode, thereferenceImage(base64 JPEG/PNG, up to 2 MB; a face photo, never a document). - Hand
responseBlobback to the SDK viaprocessResponse. The response also carriesprocessed,status,attemptsRemaining,checksand, on a definitive failure,failureReason. - When the session token expires (10 minutes) or
/processreturns409 facetec_session_expired, request another one fromPOST /v1/identity-verifications/{id}/facetec/sessionand reopen the SDK.
Journey limits:
- 3 rejected captures close the verification as
FAILED(liveness_failedorface_mismatch). Captures the provider did not process (processed: false, e.g. out of focus) do not count. - Up to 15 calls to
/processper verification; the 16th returns429 facetec_attempts_exhaustedand the verification fails. - One capture at a time: while a call is in flight another one returns
409 facetec_process_in_progresswithRetry-After. - Body up to 5 MB; above that,
413 payload_too_large(details.maxBytes). /facetec/sessioncan be called at any time whilePENDING, throttled to 1 every 5 s and 30 per verification (429 facetec_session_renewal_limited).
The match modes
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
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:
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
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.