Resuming Inquiries

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

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.

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

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.

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

1
{
2
  "data": { ... },
3
  "meta": {
4
    "session-token": "SESSION_TOKEN"
5
  }
6
}

Step 2: Load the session

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

Embedded flow

Add the inquiryId and the sessionToken as an input to the builder:

1
<!-- Replace "X.Y.Z" with the Inquiry SDK version you want to use. -->
2
<script src="https://cdn.withpersona.com/dist/persona-vX.Y.Z.js"></script>
3
4
<script>
5
  const client = new Persona.Client({
6
    inquiryId: "inq_SOME_INQUIRY_ID",
7
    sessionToken: "SOME_SESSION_TOKEN"
8
    onLoad: (_error) => client.open(),
9
    onComplete: meta => {
10
      // Inquiry completed. Optionally tell your server about it.
11
      console.log('Sending finished inquiry ' + meta.inquiryId + ' to backend');
12
      fetch('/server-handler?inquiry-id=' + meta.inquiryId);
13
    }
14
  });
15
</script>

Hosted flow

Append the inquiryId with the sessionToken to the end of the hosted flow URL: &inquiry-id=<inquiry id>&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.

For additional guidance, learn more at our Help Center