Resume Persona Inquiry Session

Overview

Session resumption allows users to return to incomplete identity verification flows without starting over. When a user begins a Persona verification but doesn't complete it due to navigation away, closing the browser, or switching devices, they can pick up exactly where they left off using a fresh session token.

Session tokens authenticate a user's return to a specific Persona inquiry with time limits and single-use credentials. Request a new session token from the Cybrid API each time a user resumes, then pass it to the Persona embedded client.

Prerequisites

Before resuming a session, verify these conditions:

Valid inquiry state: The Persona inquiry must be in created or pending status. Check this via the Identity Verification API endpoint by examining the persona_state field.
Time remaining: The inquiry must have at least 1 minute remaining before its 24-hour expiration. This safety buffer prevents requesting a session token for an inquiry that will immediately expire.
Proper authorization: Your API token must have access rights to the identity verification resource—either at the organization, bank, or customer scope level.
Correct inquiry ID: The inquiry ID you provide must match either the primary inquiry on the identity verification or one of the UBO child inquiries for business verifications.

Verify inquiry status

Before showing a "Resume Verification" option to users, query the identity verification endpoint to confirm the current state. Check both the state field (your platform's state) and persona_state (Persona's inquiry state). Only offer resumption if persona_state is created or pending.

GET /api/identity_verifications/{identity_verification_guid}
Authorization: Bearer YOUR_TOKEN

{
  "guid": "identity_verification_guid",
  "customer_guid": "customer_guid",
  "type": "kyc",
  "method": "id_and_selfie",
  "created_at": "2023-03-23T16:05:40.757Z",
  "state": "waiting",
  "persona_inquiry_id": "persona_inquiry_id",
  "persona_state": "created"
}

ℹ️
Eligible inquiry states
Only inquiries with persona_state of created or pending can be resumed.

Request a session token

Request a new session token using the POST /api/persona_sessions endpoint:

POST /api/persona_sessions
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "persona_inquiry_id": "persona_inquiry_id",
  "identity_verification_guid": "identity_verification_guid"
}

{
  "persona_session_token": "persona_session_token",
  "persona_inquiry_id": "persona_inquiry_id",
  "identity_verification_guid": "identity_verification_guid"
}

❗️
Protect session tokens
The Persona session token grants direct access to customer PII within an inquiry flow. Share this token only with the authenticated user who initiated the verification. Never log or expose this token to third parties. In production, transmit tokens over HTTPS only.

The token remains valid until the Persona inquiry expires. To extract the expiry time, decode the JWT token payload and extract the exp attribute.

Configure the Persona client

Pass the session token along with the inquiry ID to Persona's embedded client. The client restores the user's progress and allows them to continue from their last step.

import Persona from 'persona';

const client = new Persona.Client({
  sessionToken: 'persona_session_token',
  inquiryId: 'persona_inquiry_id',
  language: 'en',
  onReady: () => client.open(),
  onComplete: ({ inquiryId, status, fields }) => {
    console.log(`Completed inquiry ${inquiryId}`);
    // Poll Cybrid API to confirm verification completion
  },
  onCancel: ({ inquiryId, sessionToken }) => {
    console.log('User cancelled verification');
    // User can resume again later if inquiry still valid
  },
  onError: (error) => {
    console.error('Verification error:', error);
  }
});

For complete integration details, see Persona's resuming inquiries documentation.

Implement completion callbacks

Configure Persona's callback handlers to respond to user actions:

onComplete: Fires when the user completes the verification flow. Poll the Cybrid API to confirm verification success.
onCancel: Fires when the user cancels the flow. They can resume again later if the inquiry remains in a valid state.
onError: Fires when an error occurs. Log errors for troubleshooting and provide user-friendly error messages.

Error handling

If you attempt to generate a session token for an expired or completed Persona inquiry, the platform returns an error:

{
  "status": 400,
  "error_message": "Invalid persona inquiry state",
  "message_code": "invalid_parameter"
}

Common error scenarios:

Invalid inquiry state: The inquiry has reached a terminal state (expired, approved, or declined) and cannot be resumed. Guide the user to create a new verification.
Expired inquiry: The 24-hour window has passed. Create a new identity verification for the customer.
Rate limiting: Too many requests in a short time. Implement exponential backoff and retry after a delay.
Authorization error: The API token lacks access to the identity verification resource. Verify token scope includes the customer or organization.

Next steps

For detailed information on implementing the complete identity verification flow, see: