Parameters
Creating inquiries
The most common way to set up the embedded flow is to specify a templateId. This will create a new inquiry on every visit.
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.
For more details on the callback parameters, see Client Callbacks.
Deprecated attributes in v4
Deprecated attributes are planned to be removed or replaced in a future major version (
persona@5). They will continue to work in the immediate future.If you are on
persona@3, view our migration guide for a list of changes.
| Parameters | Requirement | Description |
|---|---|---|
| templateId or templateVersionId | Required | This template ID corresponds to a pre-set configuration and determines how the flow is customized. If using Dynamic Flow Templates, a version ID can be passed instead. |
| themeId | Pass a specific theme to be used. | |
| environmentId | The Persona API environment on which to create inquiries. | |
| environment | Deprecated. Use environmentId instead. The Persona API environment on which to create inquiries. For sandbox and production, use sandbox and production respectively. | |
| referenceId | 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. | |
| accountId | 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. | |
| onLoad | A function that is called when the Persona module has finished loading, but before the inquiry flow UI is ready for user interaction. Calls to open() prior to the onLoad callback will still open the flow, and a loading spinner will be shown. | |
| onReady | A function that is called when the inquiry has finished loading and is ready for user interaction. Will always be called after onLoad. | |
| onCancel | A function that is called when an individual has specifically exited the flow without completing. The function should expect two arguments, the inquiry ID and a sessionToken for resuming. | |
| onComplete | A function that is called when an individual completes the inquiry flow (passed or failed). It is passed the inquiry ID, status, and fields. | |
| onError | A function that is called when an error occurs in the flow. | |
| onEvent | A function that is called when an individual reaches certain points in the inquiry flow. The function should expect two arguments, an eventName string and a metadata object which contains event-specific values. | |
| frameAncestors | Should only be used if your page integrating Persona's iframe is itself embedded into another page as an iframe. If this matches your use case, you must pass an array of origins for ALL frames that are ancestors of the Persona iframe.Allows specifying additional origins for CSP purposes. Values should include both protocol and host (e.g. https://withpersona.com). Defaults to ['window.location.origin']. | |
| frameHeight | Control the height of the Persona widget iframe. Values must be valid CSS size strings. | |
| frameWidth | Control the height of the Persona widget iframe. Values must be valid CSS size strings. Size cannot exceed 768px. | |
| messageTargetOrigin | Should only be used if your page integrating Persona's iframe is itself embedded into another page as an iframe. If this matches your use case, you must pass your page's domain here.Allows specifying a custom target for window.postMessage, to allow the Persona web application to communicate with the Persona iframe.Defaults to 'window.location.origin'. | |
| parent | Allows specifying a custom mount point for the Persona iframe.Defaults to document.body. If document.body does not exist, the first child of document is used. |
Resuming an inquiry
To resume an existing inquiry instead of creating a new one, use the inquiryId parameter. Do not pass a templateId or templateVersionId when resuming the inquiry. The other attributes and callbacks specified above can still be used.
If the inquiry already has submitted verifications, you need to specify a sessionToken as well. You can generate a token with the /api/v1/inquiries/<inquiry-id>/resume endpoint. The token will be accessible as meta['session-token'].
| Parameter | Required | Description |
|---|---|---|
| inquiryId | Required | Specify an inquiry ID to resume an existing inquiry. The sessionToken parameter is required if the inquiry's status is pending. |
| sessionToken | When resuming an inquiry with a pending status, you must also generate a session token from the /api/v1/inquiries/<inquiry-id>/resume endpoint. |
Updated about 2 years ago