> This page is for Internet banking (beta).

> 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 API creates an account-independent proof for password resets, second-factor
resets, high-value transactions, or another sensitive action. The bank backend
creates a journey for a CPF, the account holder completes the facial capture,
and the backend consumes the approval once before completing the action.

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).
* **`facetec_sdk`**: the bank 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).

> **Use the master, not the account credential**
>
> This surface is for the internet-banking **master M2M** credential. A child
> credential delegated to one account cannot create, read, or consume
> verifications. Never send the master credential to a browser or app.

## Prerequisites

* a `client_credentials` token from the master;
* the `https://client.api.corpx.com` host and all three
  [signing](/ib/guias/autenticacao/assinatura-de-requisicoes) headers;
* `X-Tenant-Id`;
* the `identity_verification.manage` scope;
* the `identity_verification` tenant feature for creation;
* a `callbackUri` registered under **Identity verifications** in the panel, compared **exactly**.

Downloading evidence uses the dedicated `kyc.read` scope.

## Create

```bash
curl -X POST "https://client.api.corpx.com/v1/identity-verifications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: $BODY_SHA256" \
  -H "X-Request-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "12345678909",
    "purpose": "second_factor_reset",
    "referenceId": "reset_01J8Y6N7M8P9Q0R1S2T3",
    "displayMessage": "Confirm your identity to register the new device.",
    "callbackUri": "https://ib.example.com/identity-verification/return",
    "ttlMinutes": 30,
    "consumeTtlMinutes": 10
  }'
```

`document` is an 11-digit CPF. `referenceId` is required and identifies the
action in your system. Accepted purposes are `password_reset`,
`second_factor_reset`, `high_value_transaction`, and `sensitive_action`.
`displayMessage` is optional plain text up to 240 characters. `ttlMinutes`
defaults to 30 and `consumeTtlMinutes` to 10; both have a maximum of 60.
`provider` (`unico` or `dracma_trust`) and `method` (`link` or `facetec_sdk`)
are optional; `referenceMatch` (`none`, `dracma` by default, or `image`) only
applies to `facetec_sdk`.

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

> **Per tenant and per kind, not per account**
>
> The quota is counted **per kind**, per tenant and per BRT calendar month,
> across every internet-banking account: `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 them. Every
> `201` counts and is never refunded, even if the journey fails, expires, or is
> not consumed. 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 limit.

## Capture with the FaceTec SDK

With `method: facetec_sdk` the `201` carries no `verificationLink`; it carries
the `facetec` block (`sessionToken`, `sessionTokenExpiresAt`,
`deviceKeyIdentifier`) and `attemptsRemaining: 3`. Browser SDK v10 initializes
with `deviceKeyIdentifier` only (`initializeWithSessionRequest`); the
`sessionToken` stays on the backend and comes back as `sessionId` on each
`/facetec/process`. Initialization itself produces a `requestBlob` and counts
toward the 15-call limit. Each later capture produces another blob (1–3 MB
in base64).

The app returns the blob to the backend, and **only the backend** (with the
master credential and request signing) calls, once per capture:

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

In `image` mode include `referenceImage` (base64 JPEG/PNG, up to 2 MB; a face photo, never a document). The response
carries `responseBlob` (hand it back to the SDK), `processed`, `status`,
`attemptsRemaining`, `checks` and, on a definitive failure, `failureReason`.
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.

Limits: **3 rejected captures** close the verification as `FAILED`
(`liveness_failed` or `face_mismatch`); unprocessed captures
(`processed: false`) do not count. Up to **15 calls** to `/process` per
verification (the 16th returns `429 facetec_attempts_exhausted`). One capture
at a time (`409 facetec_process_in_progress` with `Retry-After`). Body up to
**5 MB** (`413 payload_too_large`). `/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`).

| `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
(`checks.faceMatch.result = not_performed`). Use it only as a step-up for an
already-authenticated session. 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. For `password_reset` and
`second_factor_reset`, prefer `dracma` or `image`.

## Retrieve

```bash
curl "https://client.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "X-Request-Signature: $SIGNATURE"
```

| Status     | Next step                                                                                            |
| ---------- | ---------------------------------------------------------------------------------------------------- |
| `PENDING`  | Wait; `verificationLink` remains present (`link`) or `attemptsRemaining` is reported (`facetec_sdk`) |
| `APPROVED` | Consume before `consumableUntil`                                                                     |
| `FAILED`   | Do not execute the action; inspect `failureReason`                                                   |
| `EXPIRED`  | Create another journey if still needed                                                               |

The response includes `purpose`, `referenceId`, `document`, `provider`,
`method`, `expiresAt`, `failureReason`, `completedAt`, `consumableUntil`, and
`consumedAt` when applicable. `verificationLink` exists only while `PENDING`
with `method: link`. With `method: facetec_sdk` the response also carries
`referenceMatch`, `attemptsRemaining` and `checks` (`liveness` and
`faceMatch.result`/`faceMatch.reference`); `liveness_failed` and
`face_mismatch` are the SDK-specific `failureReason` values.

## Consume

```bash
curl -X POST \
  "https://client.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/consume" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: $BODY_SHA256" \
  -H "X-Request-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "second_factor_reset",
    "referenceId": "reset_01J8Y6N7M8P9Q0R1S2T3"
  }'
```

Purpose and reference must exactly match creation. The first valid call writes
`consumedAt`. Retrying the same ID and body is idempotent; a different
purpose/reference, competing consumption, non-approved state, or elapsed window
returns `409`.

Consume from the backend immediately before the protected action. Seeing
`APPROVED` on `GET` does not reserve the proof and, by itself, does not prevent
concurrent reuse.

## Callback and webhook

`callbackUri` only returns the browser. It must be identical to the registered
URI—no wildcard, prefix, or normalization—and is not proof of the outcome.

`identity.verification.completed` is delivered for `APPROVED`, `FAILED`, and
`EXPIRED`, with `X-Signature`. Verify the raw bytes and deduplicate on the
envelope `id`. See the complete example in
[Account webhooks](/ib/guias/conta/webhooks#identityverificationcompleted).

## Evidence

`GET /v1/identity-verifications/{verificationId}/artifacts` requires `kyc.read`
instead of the management scope and the `kyc_artifacts` feature. Sign it like
every other call on the client host. The response may contain biometrics and
provider evidence; do not log URLs or contents.

## Main errors

| HTTP | `errorCode`                                                                  | Meaning                                                          |
| ---- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| 400  | `invalid_document`, `invalid_purpose`, `invalid_reference_id`                | Invalid creation field                                           |
| 400  | `invalid_display_message`, `invalid_verification_ttl`, `invalid_consume_ttl` | Invalid text or range                                            |
| 400  | `invalid_callback_uri`                                                       | URI is not an exact registered match                             |
| 400  | `invalid_provider`, `invalid_method`, `invalid_reference_match`              | Invalid combination of `provider`, `method` and `referenceMatch` |
| 400  | `reference_image_required`                                                   | `image` mode without `referenceImage` on `/facetec/process`      |
| 403  | `feature_disabled`                                                           | Feature is disabled                                              |
| 403  | `facetec_sdk_not_enabled`                                                    | Missing `identity_verification_facetec_sdk` feature or SDK keys  |
| 403  | `identity_verification_kind_not_enabled`                                     | The kind (`details.kind`) has quota 0                            |
| 403  | `insufficient_scope`                                                         | Missing `identity_verification.manage` or `kyc.read`             |
| 403  | `forbidden`                                                                  | Call did not use the master M2M credential                       |
| 404  | `verification_not_found`                                                     | ID does not exist in this tenant                                 |
| 409  | `verification_not_consumable`                                                | Incompatible state, window, or consumption binding               |
| 409  | `reference_already_consumed`                                                 | Another proof already authorized this purpose/reference          |
| 409  | `verification_method_mismatch`, `verification_not_pending`                   | Route incompatible with the `method` or state                    |
| 409  | `facetec_process_in_progress`                                                | Another capture in flight; wait `Retry-After`                    |
| 409  | `facetec_session_expired`                                                    | Renew at `/facetec/session`                                      |
| 413  | `payload_too_large`                                                          | `requestBlob` above `details.maxBytes`                           |
| 415  | `unsupported_media_type`                                                     | Missing `Content-Type: application/json`                         |
| 422  | `facetec_match_unavailable`                                                  | Match mode unavailable at the provider                           |
| 429  | `identity_verification_monthly_limit_exceeded`                               | Quota of the kind (`details.kind`) closed in the BRT month       |
| 429  | `facetec_attempts_exhausted`                                                 | Too many captures; the verification failed                       |
| 429  | `facetec_session_renewal_limited`                                            | Session renewed too often                                        |
| 429  | `rate_limited`                                                               | Traffic limit, separate from quota                               |
| 502  | `provider_error`                                                             | Provider failure (see `partner`)                                 |
| 503  | `facetec_unavailable`                                                        | SDK unavailable at the provider                                  |