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.

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

Authentication

Headers

Request

Response headers

Response

Errors