Inquiries may need to be resumed in several situations:

1. The inquiry is in progress and the user does not have a session token. As inquiries contain PII, we restrict when inquiries can be resumed. While newly created inquiries can be accessed by anyone with a link to the inquiry, pending inquiries require a session token to be accessed by the end user. Session tokens are generated by resuming inquiries, and can be passed via query string parameters for hosted flows, and via the client SDKs for embedded, inline, and native flows.
2. The user lost their session token. Session tokens are stored in session storage, which is local to the current browser tab. If a user closes a pending inquiry and reopens it in a separate browser window, they will lose their session token and see a 'Session expired' error. They will be unable to continue the inquiry without a new session token or one-time link.
3. The inquiry has expired. To ensure that inquiries are associated with only one individual, pending inquiries are expired after a set time period (24 hours by default), after which the inquiry becomes inaccessible to end users. For more information, see Inquiry Expiration.
4. The inquiry session has expired. This is less common, but if an inquiry has multiple sessions, older sessions may expire before the inquiry expires.

Persona provides two ways to access Inquiries that are in progress:

1. Generating a one-time link
2. Creating a new session token

📘

One-time link codes vs. session tokens

While pending inquiries can also be accessed by including a session token in the inquiry link URL, one-time links present the following benefits:

1. Security: one-time link codes expire after a single use (with a 5 minute grace period), whereas session tokens are valid for the lifetime of the Inquiry Session.
2. Convenience: session tokens are JWTs and can result in verbose links, while one-time links are short and portable. This can be useful when presenting one-time links as QR codes.

One-time links have the following downsides:

1. Browser-only: as one-time links are URLs, they can only be used for browser-based flows (Hosted Flow Integration, and cannot be used in Inquiry SDKs (Embedded Integration and Mobile Integration).
2. Expired inquiries: one-time links cannot be generated for expired inquiries. Expired inquiries must first be resumed.

Generating a one-time link

If you are using a browser-based integration, you can generate a one-time link that will allow the end user to access the Inquiry.

Call /api/v1/inquiries/<inquiry-id>/generate-one-time-link to receive a one-time link. Within the response, the one-time link can be found within the response's meta object. This link will expire after a set time period (24 hours by default) if not used.

require 'http'
response = HTTP.
  headers('Authorization': "Bearer #{api_key}").
  post("https://api.withpersona.com/api/v1/inquiries/#{inquiry_id}/generate-one-time-link")
inquiry = JSON.parse(response.body)

import requests
response = requests.post(
  'https://withpersona.com/api/v1/inquiries/{}/generate-one-time-link'.format(inquiry_id),
  headers: { 'Authorization': 'Bearer {}'.format(api_key) },
)
inquiry = response.json()

const request = require("request");
request.post(
  {
    json: true,
    url: `https://withpersona.com/api/v1/inquiries/${inquiryId}/generate-one-time-link`,
    headers: { Authorization: `Bearer ${apiKey}` }
  },
  (err, res, body) => {
    inquiry = res;
  }
);

Then, send the one-time link to the end user.

Creating a new session token

If the Inquiry is expired, or if you use a non-browser-based integration, you will need to create a new session token and use that to access the Inquiry.

Step 1: Create a session token

Call /api/v1/inquiries/<inquiry-id>/resume to receive a session token. Within the response, the session token can be found as session-token within the response's meta object. This token will expire after a set time period (24 hours by default) if it is not used.

require 'http'
response = HTTP.
  headers('Authorization': "Bearer #{api_key}").
  post("https://api.withpersona.com/api/v1/inquiries/#{inquiry_id}/resume")
inquiry = JSON.parse(response.body)

import requests
response = requests.post(
  'https://withpersona.com/api/v1/inquiries/{}/resume'.format(inquiry_id),
  headers: { 'Authorization': 'Bearer {}'.format(api_key) },
)
inquiry = response.json()

const request = require("request");
request.post(
  {
    json: true,
    url: `https://withpersona.com/api/v1/inquiries/${inquiryId}/resume`,
    headers: { Authorization: `Bearer ${apiKey}` }
  },
  (err, res, body) => {
    inquiry = res;
  }
);

{
  "data": { ... },
  "meta": {
    "session-token": "SESSION_TOKEN"
  }
}

Step 2: Load the session

Boot up the flow using both the inquiry ID and session token as parameters.

Embedded flow

Add the sessionToken as an input to the builder:

<!-- Replace "X.Y.Z" with the Inquiry SDK version you want to use. -->
<script src="https://cdn.withpersona.com/dist/persona-vX.Y.Z.js"></script>

<script>
  const client = new Persona.Client({
    inquiryId: "inq_SOME_INQUIRY_ID",
    sessionToken: "SOME_SESSION_TOKEN"
    onLoad: (_error) => client.open(),
    onComplete: meta => {
      // Inquiry completed. Optionally tell your server about it.
      console.log(`Sending finished inquiry ${meta.inquiryId} to backend`);
      fetch(`/server-handler?inquiry-id=${meta.inquiryId}`);
    }
  });
</script>

Hosted flow

Append the token to the end of the hosted flow URL: &session-token=<session token>

Resuming inquiries vs. creating new inquiries

When possible, we recommend resuming pending inquiries rather than creating a brand new inquiry when handling returning users. If your user has already completed part of the inquiry, resuming the inquiry will allow them to pick up where they left off, which improves the user experience and reduces data duplication.

Note that resuming inquiries on older versions of a template can lead to unexpected results. Inquiries are pinned to the current state of their template when created, and any updates made to the template between when the inquiry was created and when it was resumed will not be reflected in the resumed inquiry. If the latest published version of the inquiry's template has changed, we recommend creating a new inquiry instead of resuming the pending inquiry, to ensure that the most up-to-date configuration is used.

To check if an inquiry is on the latest template version, examine the inquiry-template object within the included array in the Inquiry API response. The inquiry-template object in the response will contain the ID of the latest published template version under the field latest-published-version.id. If this ID differs from the inquiry-template-version-id on the inquiry, then the Inquiry is not on the latest template version.