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, give its link to the person, then consume the approval once from your backend.

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

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
  }'

Do not send Idempotency-Key: every POST intentionally creates a fresh proof and consumes one quota unit when it returns 201.

201 response:

{
  "verificationId": "idv_01J8Y7C8D9E0F1G2H3J4",
  "status": "PENDING",
  "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.

Track the state

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

The response also carries purpose, referenceId, document, provider, expiresAt, and, when applicable, failureReason, completedAt, consumableUntil, and consumedAt. verificationLink appears only while PENDING.

Consume the approval

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

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.

KYC artifacts

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