> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# Identity verification

This API is billed separately.

The Identity Verification API proves that a person controls the supplied CPF
before a sensitive action. It is independent of account opening and bank
accounts: create the journey, let the person complete the facial capture, then
consume the approval once from your backend.

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). Nothing to embed in your app.
* **`facetec_sdk`**: your 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](/baas/guias/abertura-de-contas/captura-facial#request-the-sdk).
  The in-app protocol is in [Capture with the FaceTec SDK](#capture-with-the-facetec-sdk).

## Prerequisites

* a **master M2M** (`client_credentials`) credential, never a user session or
  delegated child credential;
* the `X-Tenant-Id` header;
* the `identity_verification.manage` scope;
* the `identity_verification` tenant feature for creation;
* a `callbackUri` registered under **Identity verifications** in the panel, compared **exactly**.

The credential needs the dedicated `kyc.read` scope to download KYC evidence.

## Create the verification

```bash
curl -X POST "https://tenant.api.corpx.com/v1/identity-verifications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "12345678909",
    "purpose": "password_reset",
    "referenceId": "usr_01J8Y6N7M8P9Q0R1S2T3",
    "displayMessage": "Confirm your identity to reset your password.",
    "callbackUri": "https://app.example.com/identity-verification/return",
    "ttlMinutes": 30,
    "consumeTtlMinutes": 10
  }'
```

| Field               | Rule                                                                                                |
| ------------------- | --------------------------------------------------------------------------------------------------- |
| `document`          | CPF, exactly 11 digits without punctuation                                                          |
| `purpose`           | `password_reset`, `second_factor_reset`, `high_value_transaction`, or `sensitive_action`            |
| `referenceId`       | Required; your action ID and the binding used at consumption                                        |
| `displayMessage`    | Optional plain text, up to 240 characters                                                           |
| `callbackUri`       | Registered URI, exactly as sent                                                                     |
| `ttlMinutes`        | Journey lifetime; default 30, maximum 60                                                            |
| `consumeTtlMinutes` | Window to consume after approval; default 10, maximum 60                                            |
| `provider`          | Optional: `unico` or `dracma_trust`; defaults to the provider configured for the tenant             |
| `method`            | Optional: `link` (default) or `facetec_sdk` (requires `provider: dracma_trust`)                     |
| `referenceMatch`    | `facetec_sdk` only: `none`, `dracma` (default) or `image` — see [the match modes](#the-match-modes) |

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`:

```json
{
  "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"
}
```

Give `verificationLink` only to the person who owns the CPF. Do not treat the
return to `callbackUri` as proof of approval: query the resource or process the
webhook, then call the consumption endpoint.

> **Monthly quota per kind**
>
> The quota is counted **per verification kind**, per tenant and per BRT
> calendar month: `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 the kind for the tenant. Every `201` consumes one slot of its kind even
> if the verification later fails, expires, or is never consumed, and quota is
> never refunded. 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 control
> shared by all kinds. The `X-RateLimit-*` headers on the `201` describe the kind
> of the verification created.

## Capture with the FaceTec SDK

With `method: facetec_sdk` your app controls the camera. The `201` carries no
`verificationLink`; it carries the `facetec` block the SDK needs:

```json
{
  "verificationId": "idv_01J8Y7C8D9E0F1G2H3J4",
  "status": "PENDING",
  "provider": "dracma_trust",
  "method": "facetec_sdk",
  "referenceMatch": "dracma",
  "attemptsRemaining": 3,
  "expiresAt": "2026-09-24T14:30:00Z",
  "facetec": {
    "sessionToken": "…",
    "sessionTokenExpiresAt": "2026-09-24T14:10:00Z",
    "deviceKeyIdentifier": "…"
  }
}
```

Flow in the app (Browser SDK v10):

1. Keep `sessionToken` on your backend. Initialize the SDK with
   `deviceKeyIdentifier` only (`FaceTecSDK.initializeWithSessionRequest`).
   Initialization already produces a `requestBlob` and counts toward the
   15-call limit.
2. For each `requestBlob` (the init one and each capture, 1–3 MB in base64),
   send **one** call to `POST /v1/identity-verifications/{id}/facetec/process`
   with `Content-Type: application/json`, `sessionId` set to that
   `sessionToken` and, in `image` mode, the `referenceImage` (base64 JPEG/PNG,
   up to 2 MB; a face photo, never a document).
3. Hand `responseBlob` back to the SDK via `processResponse`. The response
   also carries `processed`,
   `status`, `attemptsRemaining`, `checks` and, on a definitive failure,
   `failureReason`.
4. 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.

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

Journey limits:

* **3 rejected captures** close the verification as `FAILED`
  (`liveness_failed` or `face_mismatch`). Captures the provider did not process
  (`processed: false`, e.g. out of focus) do not count.
* Up to **15 calls** to `/process` per verification; the 16th returns
  `429 facetec_attempts_exhausted` and the verification fails.
* One capture at a time: while a call is in flight another one returns
  `409 facetec_process_in_progress` with `Retry-After`.
* Body up to **5 MB**; above that, `413 payload_too_large` (`details.maxBytes`).
* `/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`).

### The match modes

| `referenceMatch`   | What is proven                                              | Compared against                                      | Quota kind         |
| ------------------ | ----------------------------------------------------------- | ----------------------------------------------------- | ------------------ |
| `none`             | A live person is in front of the camera (3D liveness / PAD) | nobody                                                | `liveness`         |
| `dracma` (default) | Liveness **and** the face belongs to the CPF                | DracmaTrust's reference base for the CPF (1:1, 3D:2D) | `face_match_cpf`   |
| `image`            | Liveness **and** the face matches a photo you send          | `referenceImage` 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. 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 not
yet available at the provider, creation returns `422 facetec_match_unavailable`;
the API never silently downgrades to liveness-only.

Recommendation: `password_reset` and `second_factor_reset` → `dracma` or
`image` (prove identity); `high_value_transaction` and `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.

## Track the state

```bash
curl "https://tenant.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID"
```

| Status     | Meaning                                                                                                                              |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `PENDING`  | The person can still complete the journey; `verificationLink` is present (`link`) or `attemptsRemaining` is reported (`facetec_sdk`) |
| `APPROVED` | Identity approved; consume by `consumableUntil`                                                                                      |
| `FAILED`   | Verification rejected; inspect `failureReason`                                                                                       |
| `EXPIRED`  | The journey expired without approval                                                                                                 |

The response also carries `purpose`, `referenceId`, `document`, `provider`,
`method`, `expiresAt`, and, when applicable, `failureReason`, `completedAt`,
`consumableUntil`, and `consumedAt`. `verificationLink` appears **only** while
`PENDING` with `method: link`. With `method: facetec_sdk` the response also
carries `referenceMatch`, `attemptsRemaining` and `checks`
(`{"liveness": "pending|passed|failed", "faceMatch": {"result":
"pending|passed|failed|not_performed", "reference": "dracma|image"}}`).
`liveness_failed` and `face_mismatch` are the SDK-specific `failureReason`
values.

## Consume the approval

Consumption binds the proof to the action you are about to execute:

```bash
curl -X POST \
  "https://tenant.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/consume" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "password_reset",
    "referenceId": "usr_01J8Y6N7M8P9Q0R1S2T3"
  }'
```

`purpose` and `referenceId` must exactly match creation. The first valid call
sets `consumedAt`. Retrying the exact same `verificationId` and body is
idempotent and returns the same result. A different reference or purpose, a
competing consume, a state other than `APPROVED`, or an elapsed consumption
window returns `409`.

Keep consumption and the sensitive action in the same logical backend unit. Do
not authorize the action merely because `GET` showed `APPROVED`: without
consumption, concurrent requests could reuse the same proof.

## Callback and webhook

`callbackUri` returns the browser to your app; it is not a server notification.
The value must match the tenant registration exactly—no wildcard, prefix
matching, or query-string normalization.

For terminal states `APPROVED`, `FAILED`, and `EXPIRED`, the platform sends
`identity.verification.completed`. Verify `X-Signature` against the raw request
body and deduplicate on the envelope `id`. See the complete payload in
[Webhooks](/baas/guias/conta/webhooks#identityverificationcompleted).

## KYC artifacts

```bash
curl \
  "https://tenant.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/artifacts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID"
```

This route uses `kyc.read` instead of the management scope and requires the
`kyc_artifacts` feature. The files may contain biometrics and identity material:
do not log URLs or contents, and apply your KYC retention policy.

## Main errors

| HTTP | `errorCode`                                                                  | Action                                                                         |
| ---- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| 400  | `invalid_document`, `invalid_purpose`, `invalid_reference_id`                | Correct the named field                                                        |
| 400  | `invalid_display_message`, `invalid_verification_ttl`, `invalid_consume_ttl` | Follow the documented plain-text and range rules                               |
| 400  | `invalid_callback_uri`                                                       | Send an exactly registered URI                                                 |
| 400  | `invalid_provider`, `invalid_method`, `invalid_reference_match`              | Combine `provider`, `method` and `referenceMatch` as documented                |
| 400  | `reference_image_required`                                                   | In `image` mode, send `referenceImage` to `/facetec/process`                   |
| 403  | `feature_disabled`                                                           | Request feature enablement                                                     |
| 403  | `facetec_sdk_not_enabled`                                                    | Ask CorpX for the `identity_verification_facetec_sdk` feature and the SDK keys |
| 403  | `identity_verification_kind_not_enabled`                                     | The kind (`details.kind`) has quota 0; ask for enablement                      |
| 403  | `insufficient_scope`                                                         | Use `identity_verification.manage` for journeys and `kyc.read` for artifacts   |
| 403  | `forbidden`                                                                  | Use the master M2M credential                                                  |
| 404  | `verification_not_found`                                                     | Check the ID and `X-Tenant-Id`                                                 |
| 409  | `verification_not_consumable`                                                | Check state, window, `purpose`, and `referenceId`                              |
| 409  | `reference_already_consumed`                                                 | Another proof already consumed that purpose/reference                          |
| 409  | `verification_method_mismatch`, `verification_not_pending`                   | The route does not apply to this `method` or state                             |
| 409  | `facetec_process_in_progress`                                                | Wait `Retry-After` and resend the same capture                                 |
| 409  | `facetec_session_expired`                                                    | Renew at `/facetec/session` and reopen the SDK                                 |
| 413  | `payload_too_large`                                                          | Shrink the `requestBlob` (`details.maxBytes`)                                  |
| 415  | `unsupported_media_type`                                                     | Send `Content-Type: application/json`                                          |
| 422  | `facetec_match_unavailable`                                                  | The match mode is not available yet; use another `referenceMatch` or `link`    |
| 429  | `identity_verification_monthly_limit_exceeded`                               | Quota of the kind (`details.kind`) is closed; wait for the next BRT month      |
| 429  | `facetec_attempts_exhausted`                                                 | Too many captures; the verification failed, create another                     |
| 429  | `facetec_session_renewal_limited`                                            | Wait `Retry-After` before renewing the session                                 |
| 429  | `rate_limited`                                                               | Reduce request frequency and retry                                             |
| 502  | `provider_error`                                                             | Provider failure; inspect `partner` and retry                                  |
| 503  | `facetec_unavailable`                                                        | SDK unavailable at the provider; retry later or use `link`                     |