Skip to navigation

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 a verificationLink that opens the provider’s hosted page (Unico or DracmaTrust, per provider).
  • facetec_sdk: your app embeds the FaceTec SDK v10, opens the camera itself and sends each capture to POST /v1/identity-verifications/{id}/facetec/process. Requires provider: dracma_trust, the tenant feature identity_verification_facetec_sdk and the SDK keys configured by CorpX; otherwise 403 facetec_sdk_not_enabled. The 201 returns the facetec block (session token + SDK keys) and no verificationLink.

The three modes (referenceMatch, facetec_sdk only)

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 /facetec/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 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

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
X-Request-TimestampstringRequired

Unix seconds. Required on the signed host; tolerance is 300s either way (403 request_timestamp_skew).

X-Content-SHA256stringRequired

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.

X-Request-SignaturestringRequired

Detached JWS (<protected>..<signature>, ES256 or PS256) over METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256.

Request

This endpoint expects an object.
documentstringRequiredformat: "^\d{11}$"
CPF with exactly 11 digits and no punctuation.
purposeenumRequired
Sensitive journey that this proof is allowed to authorize.
Allowed values:
referenceIdstringRequiredformat: "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"1-128 characters

Caller-owned identifier for the journey being authorized. It must be repeated exactly when consuming.

callbackUristringRequiredformat: "uri"

Exact tenant-registered URI to which the browser returns after the identity journey.

displayMessagestringOptional<=240 characters

Optional one-line plain text shown to the person. HTML, Markdown, links and controls are rejected. Maximum 240 characters.

ttlMinutesintegerOptional1-60Defaults to 30
Lifetime of the pending verification link, in minutes.
consumeTtlMinutesintegerOptional1-60Defaults to 10
Time after approval during which the result may be consumed, in minutes.
providerenumOptional

Identity provider. Omitted = the tenant’s configured hosted provider. facetec_sdk requires dracma_trust.

Allowed values:
methodenumOptionalDefaults to link

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.

Allowed values:
referenceMatchenumOptionalDefaults to dracma

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 referenceImage you send in /facetec/process.
Allowed values:

Response headers

X-RateLimit-LimitintegerOptional
Monthly limit of the kind of this verification.
X-RateLimit-RemainingintegerOptional
Remaining successful creations of this kind in the current BRT calendar month.
X-RateLimit-ResetintegerOptional
Unix timestamp for the start of the next BRT calendar month.

Response

Verification created. This response consumes one monthly quota slot of its kind.
verificationIdstring
Identifier used by all subsequent identity verification endpoints.
statusenum

A new verification always starts as PENDING.

Allowed values:
providerenum
Allowed values:
methodenumDefaults to link

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.

Allowed values:
expiresAtdatetime
RFC 3339 instant at which the pending verification expires.
purposeenumOptional
Sensitive journey that this proof is allowed to authorize.
Allowed values:
referenceIdstringOptional
documentstringOptional
referenceMatchenumOptionalDefaults to dracma

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 referenceImage you send in /facetec/process.
Allowed values:
facetecobjectOptional

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.

attemptsRemainingintegerOptional

Failed captures still allowed (starts at 3). Only for method: facetec_sdk.

checksobjectOptional

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.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error
503
Service Unavailable Error