API BaaSIdentity Verification

Consume an approved identity verification

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-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringOptional

Optional client-generated idempotency token (recommended for safe retries).

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.
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