Create a standalone identity verification

curl -X POST https://tenant.api.corpx.com/v1/identity-verifications \
     -H "X-Tenant-Id: X-Tenant-Id" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "document": "12345678909",
  "purpose": "password_reset",
  "referenceId": "usr_01J8Y6N7M8P9Q0R1S2T3",
  "callbackUri": "https://app.example.com/identity-verification/return",
  "displayMessage": "Confirme sua identidade para redefinir a senha.",
  "ttlMinutes": 30,
  "consumeTtlMinutes": 10
}'

{
  "verificationId": "idv_01J8Y7C8D9E0F1G2H3J4",
  "status": "PENDING",
  "verificationLink": "https://tenant.api.corpx.com/v1/identity-verifications/verify#capability-redacted",
  "expiresAt": "2026-09-24T14:30:00Z"
}

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.

The fixed quota is 10 successful creations per tenant per calendar month in BRT. Every 201 consumes one slot, including verifications that later fail, expire or are never consumed; slots are never refunded. A closed monthly quota returns HTTP 429 with identity_verification_monthly_limit_exceeded. This is distinct from the short-window rate_limited error, which also uses HTTP 429.

Do not send Idempotency-Key: every POST deliberately opens a new proof and a 201 always consumes one monthly quota slot.

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. The fixed quota is **10 successful creations per tenant per calendar month in BRT**. Every `201` consumes one slot, including verifications that later fail, expire or are never consumed; slots are never refunded. A closed monthly quota returns HTTP `429` with `identity_verification_monthly_limit_exceeded`. This is distinct from the short-window `rate_limited` error, which also uses HTTP `429`. 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.

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.

Response headers

X-RateLimit-LimitintegerOptional

Fixed monthly limit (10).

X-RateLimit-RemainingintegerOptional

Remaining successful creations 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.

verificationIdstring

Identifier used by all subsequent identity verification endpoints.

statusenum

A new verification always starts as PENDING.

Allowed values:

verificationLinkstringformat: "uri"

Link to open for the person who owns the CPF.

expiresAtdatetime

RFC 3339 instant at which the pending link expires.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error