Resuming Inquiries

Inquiries may need to be resumed in several situations:

1. The inquiry is in progress. 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 webviews, and via the client SDKs for embedded, inline, and native flows.
2. The user lost access to their session token. Session tokens are stored in session storage, which is local to the current browser window. 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.
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.

🚧

Allowed statuses

Prior to resuming an inquiry, check the status of the inquiry to see if it can be resumed. Only inquiries with a pending, or expired status should be resumed. Attempting to resume a completed, failed or decisioned inquiry (approved, declined, or needs_review) will result in an error.

🚧

Resuming old Dynamic Flow inquiries and template configurations

Dynamic Flow template configurations are versioned, and Inquiries are locked to the latest version of the configuration when created. This means that if an old inquiry is resumed, it will be using the configuration from when it was created, and any template configuration changes made between then and now will not apply. To guarantee that the latest template configuration is used, we recommend creating a new Inquiry instead of resuming.

Legacy, pre-Dynamic Flow templates are not versioned, and will always use the latest configuration.

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://withpersona.com/api/v1/inquiries/inq_RQ4jHMYx8wHMCSjQ2M43jf4r/resume')
inquiry = JSON.parse(response.body)

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

const request = require("request");
request.post(
  {
    json: true,
    url: "https://withpersona.com/api/v1/inquiries/inq_RQ4jHMYx8wHMCSjQ2M43jf4r/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

<script src="https://cdn.withpersona.com/assets/v2/persona.js"></script>

<script>
  const client = new Persona.Client({
    environment: "sandbox",
    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>