Parameters
The most common way to set up the hosted flow is to specify a template-id.
Optionally, you can connect new inquiries to an account. To connect the inquiry to an account, specify either referenceId or accountId. You cannot specify both.
Special characters in URL parameters
Be sure to escape your values if you are passing non-alphanumeric characters in your parameters. For example, values including whitespace or symbols like
+need to be escaped. In JavaScript, this can be done withencodeURIComponent.
Deprecated attributes
Deprecated attributes are planned to be removed or replaced in the future. They will continue to work in the immediate future.
| Parameter | Requirement | Description |
|---|---|---|
| template-id, inquiry-template-id, or inquiry-template-version-id | Required | This template ID corresponds to a pre-set configuration and determines how the flow is customized. See Am I using Dynamic Flow Templates? for more information on the differences between Templates and Dynamic Flow Templates. |
| theme-id | Pass a specific theme to be used. | |
| environment-id | The Persona API environment on which to create inquiries. | |
| environment | Deprecated. Use environment-id instead. The Persona API environment on which to create inquiries. For sandbox and production, use sandbox and production respectively. | |
| reference-id | You can generate and provide a unique ID which we will associate with the inquiry. The identifier can be used to monitor user progress in newly created inquiries. Inquiries with the same reference ID will be grouped under a single account. | |
| account-id | ID of the account to associate newly created inquiries with. | |
| language | Specify a supported language to localize the flow. Language will be inferred from browser settings by default. See Languages. | |
| fields | Provide an object to set inquiry field values. Each attribute in the object is optional. If using Dynamic Flow Templates, will also prefill form inputs in the flow. See Fields documentation. | |
| prefill | Deprecated. Provide an object to prefill form inputs in the flow. Each attribute in the object is optional. See Prefill documentation. | |
| redirect-uri | When the user successfully verifies their identity, we redirect back to this URI. The callback should expect a GET parameter named inquiry-id that references the completed inquiry. If no redirect-uri is specified, then the success page shown to users will not have a continue button. |
Resuming an inquiry
To resume an existing inquiry instead of creating a new one, use the inquiry-id parameter. Do not pass a template-id when resuming the inquiry.
If the inquiry already has submitted verifications, you need to specify a session-token as well. You can generate a session token with the /api/v1/inquiries//resume endpoint.
| Parameter | Required | Description |
|---|---|---|
| inquiry-id | Required | Specify an inquiry ID to resume an existing inquiry. If the inquiry has a pending status, then a sessionToken from the server-side API is required. |
| session-token | When resuming an inquiry with a pending status, you must also generate a session token from the server-side API. | |
| language | Specify a supported language to localize the flow. Language will be inferred from browser settings by default. | |
| prefill | Provide an object to prefill form inputs in the flow. Each attribute in the object is optional. | |
| redirect-uri | When the user successfully verifies their identity, we redirect back to this URL. The callback should expect a GET parameter named inquiry-id that references the completed inquiry. If no redirect-uri is specified, then the success page shown to users will not have a continue button. |
Updated about 2 years ago