Identity verification
This API is billed separately.
The API creates an account-independent proof for password resets, second-factor resets, high-value transactions, or another sensitive action. The bank backend creates a journey for a CPF, the account holder completes the facial capture, and the backend consumes the approval once before completing the action.
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).facetec_sdk: the bank 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.
This surface is for the internet-banking master M2M credential. A child credential delegated to one account cannot create, read, or consume verifications. Never send the master credential to a browser or app.
Prerequisites
- a
client_credentialstoken from the master; - the
https://client.api.corpx.comhost and all three signing headers; X-Tenant-Id;- the
identity_verification.managescope; - the
identity_verificationtenant feature for creation; - a
callbackUriregistered under Identity verifications in the panel, compared exactly.
Downloading evidence uses the dedicated kyc.read scope.
Create
document is an 11-digit CPF. referenceId is required and identifies the
action in your system. Accepted purposes are password_reset,
second_factor_reset, high_value_transaction, and sensitive_action.
displayMessage is optional plain text up to 240 characters. ttlMinutes
defaults to 30 and consumeTtlMinutes to 10; both have a maximum of 60.
provider (unico or dracma_trust) and method (link or facetec_sdk)
are optional; referenceMatch (none, dracma by default, or image) only
applies to facetec_sdk.
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:
The quota is counted per kind, per tenant and per BRT calendar month,
across every internet-banking account: 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 them. Every
201 counts and is never refunded, even if the journey fails, expires, or is
not consumed. 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 limit.
Capture with the FaceTec SDK
With method: facetec_sdk the 201 carries no verificationLink; it carries
the facetec block (sessionToken, sessionTokenExpiresAt,
deviceKeyIdentifier) and attemptsRemaining: 3. Browser SDK v10 initializes
with deviceKeyIdentifier only (initializeWithSessionRequest); the
sessionToken stays on the backend and comes back as sessionId on each
/facetec/process. Initialization itself produces a requestBlob and counts
toward the 15-call limit. Each later capture produces another blob (1–3 MB
in base64).
The app returns the blob to the backend, and only the backend (with the master credential and request signing) calls, once per capture:
In image mode include referenceImage (base64 JPEG/PNG, up to 2 MB; a face photo, never a document). The response
carries responseBlob (hand it back to the SDK), processed, status,
attemptsRemaining, checks and, on a definitive failure, failureReason.
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.
Limits: 3 rejected captures close the verification as FAILED
(liveness_failed or face_mismatch); unprocessed captures
(processed: false) do not count. Up to 15 calls to /process per
verification (the 16th returns 429 facetec_attempts_exhausted). One capture
at a time (409 facetec_process_in_progress with Retry-After). Body up to
5 MB (413 payload_too_large). /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).
An APPROVED with referenceMatch: none only proves that a live person
completed the capture — it does not prove who they are
(checks.faceMatch.result = not_performed). Use it only as a step-up for an
already-authenticated session. 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. For password_reset and
second_factor_reset, prefer dracma or image.
Retrieve
The response includes purpose, referenceId, document, provider,
method, expiresAt, failureReason, completedAt, consumableUntil, and
consumedAt when applicable. verificationLink exists only while PENDING
with method: link. With method: facetec_sdk the response also carries
referenceMatch, attemptsRemaining and checks (liveness and
faceMatch.result/faceMatch.reference); liveness_failed and
face_mismatch are the SDK-specific failureReason values.
Consume
Purpose and reference must exactly match creation. The first valid call writes
consumedAt. Retrying the same ID and body is idempotent; a different
purpose/reference, competing consumption, non-approved state, or elapsed window
returns 409.
Consume from the backend immediately before the protected action. Seeing
APPROVED on GET does not reserve the proof and, by itself, does not prevent
concurrent reuse.
Callback and webhook
callbackUri only returns the browser. It must be identical to the registered
URI—no wildcard, prefix, or normalization—and is not proof of the outcome.
identity.verification.completed is delivered for APPROVED, FAILED, and
EXPIRED, with X-Signature. Verify the raw bytes and deduplicate on the
envelope id. See the complete example in
Account webhooks.
Evidence
GET /v1/identity-verifications/{verificationId}/artifacts requires kyc.read
instead of the management scope and the kyc_artifacts feature. Sign it like
every other call on the client host. The response may contain biometrics and
provider evidence; do not log URLs or contents.