Resume Persona Inquiry Session

Overview

Session resumption allows customers to return to incomplete identity verification flows without starting over. When a customer 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 Persona via the SDK client (embedded flow) or as a URL query parameter (hosted flow).

ℹ️
Session token usage differs by flow
How you pass the session token depends on which Persona flow you use:

Embedded flow: Pass the session token to the Persona SDK client (see Resume via the embedded flow).

Hosted flow: Append the session token as a query parameter to the hosted URL (see Resume via the hosted flow).

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

To extract the session token's expiry time, decode the JWT payload and check the exp attribute.

Session expiry vs inquiry expiry

Session expiry and inquiry expiry are distinct concepts:

Session expiry: In the hosted flow, a session token is scoped to a single browser tab (stored in session storage). If the user closes the tab, switches browsers, or opens the inquiry in a new window, the session token is lost and the user sees a "Session expired" error. Request a new session token via POST /api/persona_sessions to let the user continue — the inquiry itself is still valid.
Inquiry expiry: Pending inquiries expire after a set time period (24 hours by default), after which the inquiry becomes permanently inaccessible. Once an inquiry expires, you must create a new identity verification for the customer.

ℹ️
Session expired does not mean inquiry expired
A lost or expired session token does not affect the underlying inquiry. As long as the inquiry remains in created or pending state and has not exceeded its expiry window, you can generate a new session token and resume where the user left off.

Resume the inquiry

Use the session token together with the inquiry ID to restore the user's progress and let them continue from their last step. Choose the approach that matches your integration flow.

Resume via the embedded flow

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.

Resume via the hosted flow

For the hosted flow, append the session-token query parameter to the Persona verification URL along with the inquiry ID:

https://withpersona.com/verify?inquiry-id=persona_inquiry_id&session-token=persona_session_token

Redirect or share this URL with the customer. The hosted flow restores their progress and allows them to continue from their last step.

❗️
Protect the hosted URL
The URL contains the session token as a query parameter. Transmit over HTTPS only and avoid exposing the full URL in logs, analytics, or support systems.

Implement completion callbacks (embedded flow)

Configure Persona's callback handlers to respond to customer actions in the embedded SDK flow:

onComplete: Fires when the customer completes the verification flow. Poll the Cybrid API to confirm verification success.
onCancel: Fires when the customer 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 customer-facing 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: