Skip to navigation

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 a verificationLink that 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 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.
Use the master, not the account credential

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_credentials token from the master;
  • the https://client.api.corpx.com host and all three signing headers;
  • X-Tenant-Id;
  • the identity_verification.manage scope;
  • the identity_verification tenant feature for creation;
  • a callbackUri registered under Identity verifications in the panel, compared exactly.

Downloading evidence uses the dedicated kyc.read scope.

Create

curl -X POST "https://client.api.corpx.com/v1/identity-verifications" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "X-Request-Timestamp: $TS" \
-H "X-Content-SHA256: $BODY_SHA256" \
-H "X-Request-Signature: $SIGNATURE" \
-H "Content-Type: application/json" \
-d '{
"document": "12345678909",
"purpose": "second_factor_reset",
"referenceId": "reset_01J8Y6N7M8P9Q0R1S2T3",
"displayMessage": "Confirm your identity to register the new device.",
"callbackUri": "https://ib.example.com/identity-verification/return",
"ttlMinutes": 30,
"consumeTtlMinutes": 10
}'

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:

{
"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"
}
Per tenant and per kind, not per account

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:

curl -X POST \
"https://client.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/facetec/process" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "X-Request-Timestamp: $TS" \
-H "X-Content-SHA256: $BODY_SHA256" \
-H "X-Request-Signature: $SIGNATURE" \
-H "Content-Type: application/json" \
-d '{ "requestBlob": "<base64 from the SDK>", "sessionId": "<sessionToken from the 201>" }'

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).

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 (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

curl "https://client.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "X-Request-Timestamp: $TS" \
-H "X-Content-SHA256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
-H "X-Request-Signature: $SIGNATURE"
StatusNext step
PENDINGWait; verificationLink remains present (link) or attemptsRemaining is reported (facetec_sdk)
APPROVEDConsume before consumableUntil
FAILEDDo not execute the action; inspect failureReason
EXPIREDCreate another journey if still needed

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

curl -X POST \
"https://client.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/consume" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "X-Request-Timestamp: $TS" \
-H "X-Content-SHA256: $BODY_SHA256" \
-H "X-Request-Signature: $SIGNATURE" \
-H "Content-Type: application/json" \
-d '{
"purpose": "second_factor_reset",
"referenceId": "reset_01J8Y6N7M8P9Q0R1S2T3"
}'

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.

Main errors

HTTPerrorCodeMeaning
400invalid_document, invalid_purpose, invalid_reference_idInvalid creation field
400invalid_display_message, invalid_verification_ttl, invalid_consume_ttlInvalid text or range
400invalid_callback_uriURI is not an exact registered match
400invalid_provider, invalid_method, invalid_reference_matchInvalid combination of provider, method and referenceMatch
400reference_image_requiredimage mode without referenceImage on /facetec/process
403feature_disabledFeature is disabled
403facetec_sdk_not_enabledMissing identity_verification_facetec_sdk feature or SDK keys
403identity_verification_kind_not_enabledThe kind (details.kind) has quota 0
403insufficient_scopeMissing identity_verification.manage or kyc.read
403forbiddenCall did not use the master M2M credential
404verification_not_foundID does not exist in this tenant
409verification_not_consumableIncompatible state, window, or consumption binding
409reference_already_consumedAnother proof already authorized this purpose/reference
409verification_method_mismatch, verification_not_pendingRoute incompatible with the method or state
409facetec_process_in_progressAnother capture in flight; wait Retry-After
409facetec_session_expiredRenew at /facetec/session
413payload_too_largerequestBlob above details.maxBytes
415unsupported_media_typeMissing Content-Type: application/json
422facetec_match_unavailableMatch mode unavailable at the provider
429identity_verification_monthly_limit_exceededQuota of the kind (details.kind) closed in the BRT month
429facetec_attempts_exhaustedToo many captures; the verification failed
429facetec_session_renewal_limitedSession renewed too often
429rate_limitedTraffic limit, separate from quota
502provider_errorProvider failure (see partner)
503facetec_unavailableSDK unavailable at the provider