Consume an approved identity verification

curl -X POST https://client.api.corpx.com/v1/identity-verifications/verificationId/consume \
     -H "X-Content-SHA256: X-Content-SHA256" \
     -H "X-Request-Signature: X-Request-Signature" \
     -H "X-Request-Timestamp: X-Request-Timestamp" \
     -H "X-Tenant-Id: X-Tenant-Id" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "purpose": "password_reset",
  "referenceId": "usr_01J8Y6N7M8P9Q0R1S2T3"
}'

{
  "verificationId": "idv_01J8Y7C8D9E0F1G2H3J4",
  "status": "APPROVED",
  "purpose": "password_reset",
  "referenceId": "usr_01J8Y6N7M8P9Q0R1S2T3",
  "document": "12345678909",
  "provider": "unico",
  "expiresAt": "2026-09-24T14:30:00Z",
  "completedAt": "2026-09-24T14:08:12Z",
  "consumableUntil": "2026-09-24T14:18:12Z",
  "consumedAt": "2026-09-24T14:10:05Z"
}

Atomically marks an approved verification as consumed. purpose and referenceId must exactly match the values stored at creation, the status must be APPROVED, and the call must arrive no later than consumableUntil.

The exact retry — same verificationId, purpose and referenceId — is idempotent and returns the already-consumed result. A different purpose/reference, a competing consume, a non-approved terminal state or an expired consumption window returns 409.

Requires a master M2M credential, the identity_verification.manage scope and X-Tenant-Id.

Atomically marks an approved verification as consumed. `purpose` and `referenceId` must exactly match the values stored at creation, the status must be `APPROVED`, and the call must arrive no later than `consumableUntil`. The exact retry — same `verificationId`, `purpose` and `referenceId` — is idempotent and returns the already-consumed result. A different purpose/reference, a competing consume, a non-approved terminal state or an expired consumption window returns `409`. Requires a master M2M credential, the `identity_verification.manage` scope and `X-Tenant-Id`.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

verificationIdstringRequired

Standalone identity verification identifier returned by the creation endpoint.

Headers

X-Content-SHA256stringRequired

Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns 400 body_hash_mismatch.

Request

This endpoint expects an object.

purposeenumRequired

Sensitive journey that this proof is allowed to authorize.

Allowed values:

referenceIdstringRequired

Must exactly equal the referenceId supplied at creation.

Response

Verification consumed, or the result of an exact retry.

verificationIdstring

Standalone verification identifier.

statusenum

Current state of the standalone verification.

Allowed values:

purposeenum

Sensitive journey that this proof is allowed to authorize.

Allowed values:

referenceIdstring

Caller-owned journey identifier supplied at creation.

documentstringformat: "^\d{11}$"

CPF verified by this journey, with 11 digits and no punctuation.

providerstring

Identity provider that processed the journey.

expiresAtdatetime

RFC 3339 instant at which the pending journey expires.

verificationLinkstringOptionalformat: "uri"

Present only while status is PENDING.

failureReasonenumOptional

Provider-normalized reason when the journey failed or expired; otherwise null or omitted.

Allowed values:

completedAtdatetime or nullOptional

Terminal transition time for APPROVED, FAILED or EXPIRED.

consumableUntildatetime or nullOptional

Last instant at which an approved result may be consumed. Set for APPROVED.

consumedAtdatetime or nullOptional

First successful consume time; null or omitted until consumption.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

500

Internal Server Error