Create a standalone identity verification
Creates a standalone CPF identity check and returns the link that must be opened by the person being verified.
This route requires a master M2M (client_credentials) credential,
X-Tenant-Id, the identity_verification.manage scope and the
identity_verification feature enabled for the tenant. User sessions
and delegated child credentials are rejected.
callbackUri must be an exact match for a URI registered for the
tenant. Prefix matches, wildcards, case normalization and adding or
removing query parameters are not accepted.
Capture methods
method chooses how the person is captured:
link(default): CorpX returns averificationLinkthat opens the provider’s hosted page (Unico or DracmaTrust, perprovider).facetec_sdk: your app embeds the FaceTec SDK v10, opens the camera itself and sends each capture toPOST /v1/identity-verifications/{id}/facetec/process. Requiresprovider: dracma_trust, the tenant featureidentity_verification_facetec_sdkand the SDK keys configured by CorpX; otherwise403 facetec_sdk_not_enabled. The201returns thefacetecblock (session token + SDK keys) and noverificationLink.
The three modes (referenceMatch, facetec_sdk only)
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 requested but not yet available at the provider,
the create responds 422 facetec_match_unavailable; the API never
silently downgrades to liveness-only.
Glossary: 1:1 compares one capture against one reference (this
API); 1:N searches a capture in a gallery (not offered);
3D:3D compares two FaceTec 3D FaceMaps; 3D:2D compares a 3D
FaceMap against a 2D photo (CPF base or referenceImage); FAR /
FRR are the false-accept and false-reject rates of the matcher;
PAD is presentation-attack detection (the liveness check).
Recommendation: password_reset / second_factor_reset → dracma
or image (prove identity); high_value_transaction /
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.
Quota per kind
The monthly quota is counted per kind (link_unico,
link_dracma, liveness, face_match_image, face_match_cpf),
per tenant, per BRT calendar month. Link kinds default to 10; SDK
kinds default to 0 (blocked until CorpX enables them —
403 identity_verification_kind_not_enabled). Every 201 consumes
one slot of its kind, including verifications that later fail,
expire or are never consumed; slots are never refunded. A closed
quota returns HTTP 429 with
identity_verification_monthly_limit_exceeded and details.kind.
This is distinct from the short-window rate_limited error, which
also uses HTTP 429 and is shared by all kinds. The
X-RateLimit-* headers describe the kind of the verification created.
Do not send Idempotency-Key: every POST deliberately opens a new
proof and a 201 always consumes one monthly quota slot.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Headers
Unix seconds. Required on the signed host; tolerance is 300s either way (403 request_timestamp_skew).
Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns 400 body_hash_mismatch.
Detached JWS (<protected>..<signature>, ES256 or PS256) over METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256.
Request
Caller-owned identifier for the journey being authorized. It must be repeated exactly when consuming.
Exact tenant-registered URI to which the browser returns after the identity journey.
Optional one-line plain text shown to the person. HTML, Markdown, links and controls are rejected. Maximum 240 characters.
Identity provider. Omitted = the tenant’s configured hosted provider. facetec_sdk requires dracma_trust.
How the person is captured. link (default) opens the provider’s
hosted page via verificationLink; facetec_sdk means your app
embeds the FaceTec SDK v10 and sends captures to /facetec/process.
Only for method: facetec_sdk. none = liveness only (proves a live
person, not who they are); dracma (default) = liveness + 1:1 face
match against DracmaTrust’s reference for the CPF; image = liveness
- 1:1 face match against the
referenceImageyou send in/facetec/process.
Response headers
Response
A new verification always starts as PENDING.
How the person is captured. link (default) opens the provider’s
hosted page via verificationLink; facetec_sdk means your app
embeds the FaceTec SDK v10 and sends captures to /facetec/process.
Only for method: facetec_sdk. none = liveness only (proves a live
person, not who they are); dracma (default) = liveness + 1:1 face
match against DracmaTrust’s reference for the CPF; image = liveness
- 1:1 face match against the
referenceImageyou send in/facetec/process.
Link to open for the person who owns the CPF. Only for method: link.
FaceTec Browser SDK v10 bootstrap for method: facetec_sdk.
deviceKeyIdentifier is not a secret (it is embedded in the app) and
is the only value the SDK takes at initializeWithSessionRequest.
The session token stays on your backend: the SDK v10 does not accept
it. Echo it as sessionId on each /facetec/process. It lives 10
minutes.
Failed captures still allowed (starts at 3). Only for method: facetec_sdk.
Per-capability result, read separately from the aggregate status.
faceMatch.result is not_performed when referenceMatch is none:
an APPROVED in that mode only proves liveness.