Verification Requests

AvailabilityCopy Anchor Link

Verification-request Studio, recipient and API entry points are currently unavailable in every environment; the request API endpoints return 404. Enabling an environment flag does not open this held implementation. The contract below describes the intended flow after the remaining journey, retention and tenant-isolation prerequisites are reviewed and qualified. Controlled local/staging acceptance and an explicit business rollout are required before availability; production endpoints remain disabled.

Once available, a support agent can request verification during a call and let the customer complete it later. Use Integration Studio → Send a verification request, or create a request from your server. Select an existing verification profile, provide the reason the customer will see, and choose email, text message, or copy link. An optional case reference helps your support system match the result.

Create from your serverCopy Anchor Link

Authenticate with the profile's confidential client secret, never its publishable key. Keep this secret on your server. An idempotency key is required; repeat the same input and key to recover a response after a connection failure.

POST /api/v1/verification-requests
Authorization: Bearer YOUR_CLIENT_SECRET
Idempotency-Key: support-case-123-attempt-1
Content-Type: application/json

{
  "partnerKeyId": "YOUR_PROFILE_UUID",
  "purpose": "Verify your identity to continue your support request",
  "externalReference": "SUP-123",
  "channel": "email",
  "recipient": "customer@example.com",
  "requireFresh": false
}

For text messages use "channel": "sms" and a phone number with country code, such as +14155550123. For copy link use "channel": "link" and omit recipient. The response contains the request summary and invitationUrl. Treat the URL as a secret; do not put it in analytics or logs. Copy-link delivery is also usable through your own messaging provider.

For a known customer, provide expectedPairwiseSub using their existing CAIRL pairwise identifier. This prevents a forwarded invitation from completing against another account. Without that identifier, email/text delivery requires independently verified possession of the addressed contact. A copy link binds the first authenticated customer who consents. Contact possession alone is never an identity-verification result.

Set requireFresh to true when this specific support action requires a new verification. Otherwise your profile's normal reuse and freshness rules apply. Test profiles return synthetic results, visibly marked as test, without a verification charge.

Customer journeyCopy Anchor Link

The invitation lasts 24 hours. Opening or scanning the link does not start verification; the customer explicitly continues into the hosted flow, signs in, reviews the claims and chooses whether to share them. A new phone recipient may confirm the invited number with a verification code after agreeing to SMS delivery. Each hosted session lasts 30 minutes; the invitation can start another session within its original lifetime.

Status, resend and cancelCopy Anchor Link

GET /api/v1/verification-requests
GET /api/v1/verification-requests/REQUEST_UUID
POST /api/v1/verification-requests/REQUEST_UUID
Content-Type: application/json

{"action":"resend","operationId":"5a54d607-a91e-493f-a36a-cb50276045e1","expectedGeneration":1}

Use the same three fields with action set to cancel to withdraw an open request. Generate a new random operation UUID for each explicit new intent, and use the current request generation as expectedGeneration. Recover an uncertain response by repeating the exact original action, operation UUID and expected generation; never generate a replacement identity merely to retry. Identity-free action bodies are rejected.

A successful response contains the current request, invitationUrl, replayed, and operation with id (your supplied operation UUID), action, expectedGeneration and committedGeneration. Verify the operation binding before displaying its outcome. Exact replay creates no extra generation, delivery or action audit. The invitation is available only while that resend generation remains current and open; terminal and superseded replays return a null invitation. Current authorization and profile availability still apply to recovery.

A new resend rotates the link, so the old link and hosted session stop working. There is a one-minute cooldown and a maximum of five resends; resending does not extend the original invitation expiry. A new action against an outdated generation conflicts. Reusing an operation identity with changed action or generation also conflicts.

A 409 (or permanent-cap 429) response can include outcome: "not_applied", the current minimal request, a null invitation, and the exact operation binding with committedGeneration: null. This proves your operation was absent under the row lock and is now fenced by a higher generation, persisted terminal request status at that generation, or the permanent resend cap. The required barrier is generation_advanced, terminal_status, or resend_cap. An elapsed wall-clock deadline alone returns an ordinary error; a projected expired summary does not prove a committed expiry transition. Validate that binding and barrier before releasing uncertainty. It performs no writes and does not undo another operation. Generic errors, cooldowns, future generations, missing authority/request, and stored identity conflicts do not supply this proof. Exact previously applied operations still replay first, including after terminalization.

Request status is pending, in_progress, completed, declined, canceled or expired. Delivery has its own history: queued, processing, sent, delivered, failed, unknown or canceled. sent means the provider accepted the message. unknown means acceptance could not be established safely; CAIRL avoids an automatic duplicate send, and your agent can explicitly resend.

Retrieve the resultCopy Anchor Link

GET /api/v1/verification-requests/REQUEST_UUID?result=true
Authorization: Bearer YOUR_CLIENT_SECRET

A completed request returns accessToken while the token and the underlying credential and consent remain valid. Otherwise it returns null. Validate the JWT signature, expiry and aud of vrq:REQUEST_UUID using CAIRL's normal token validation contract; check mode before using the result. Token expiry does not itself erase the completion receipt. Request and delivery-history retention and deletion enforcement remain pending qualification before request collection; this contract does not promise a retention period or continued receipt availability.

Configured signed webhooks announce verification_request.completed, verification_request.declined, verification_request.canceled and verification_request.expired. Events contain the request ID, case reference, status and mode; retrieve the token with the authenticated API. Email and SMS carry invitations only. Identity documents and verification results are never attached to these messages.