Using Reference IDs

A Reference ID is a string unique to every user that is used to identify their Persona account in a way that makes sense to your business. Persona recommends using the same user ID that uniquely represents the user in your internal system.

Inquiries created with the same Reference ID will all get automatically associated with the same account, which will

• Make it easy to know the status of all interactions between this user and Persona
• Allow for easier re-verification of the user
• Help with Preventing Users From Creating Multiple Inquiries

How to do it

• Server API: (recommended) Pass in the user's reference-id as an attribute
• SDK: pass the field in the builder
• Hosted: at the end of the URL (&reference-id=abc)
• If your user has no reference-id, you can Update their existing account with one

We recommend using UIDs instead of potentially sensitive information such as email addresses. Persona does not treat Reference IDs as PII.

Prefilling inquiry fields

If you already have information you’ve collected on your user, you can pre-populate their inquiry with this information at creation time. This will allow you to

• Streamline the user experience— if the user has already given you this information, there’s no need to have them type it again into Persona. You can prefill the inquiry and just have the user confirm everything is correct.
• Have an extra level of assurance that the user’s information is valid. For example, if you pass through a name and birthdate, you can configure your template to check that the information extracted from the user’s Government ID matches what was prefilled.

How to do it

• Server API: (recommended) Pass in the desired fields upon creation of the inquiry via API call. This is Persona's recommended method.
• SDK: When implementing with one of Persona’s SDKs and creating the inquiry on-the-fly, you can send the fields over in the builder.
• Hosted: You can add fields to the URL when using a generic inquiry template link.

Using webhooks to fetch the inquiry status

Persona recommends setting up Webhooks to listen for any relevant inquiry statuses. Webhooks are sent immediately upon the event firing and eliminate the need to continuously poll an inquiry for updates.

Webhooks vs Polling

Although we recommend implementing a webhook listener if possible, it may be sufficient to poll the API directly for the inquiry decision if you are:

• Blocking the user from the next step in your flow based on the inquiry decision
• Unable to support infrastructure to handle webhooks (e.g. do not have a server actively listening for webhooks)
• Unlikely to hit any API rate limits
• Not marking many inquiries for manual review (where you might be polling for a long time before the inquiry is decisioned)

How to do it

See our Webhooks documentation.

Avoid using Client Callbacks to fetch the inquiry status

Persona’s SDK client callbacks are intended to allow taking action on start, iframe load, complete, and additional client-only events; for example, they can be used to open the widget once the Inquiry has loaded. The callbacks do not guarantee that the included Inquiry data is the most up-to-date representation of the Inquiry. You should leverage callbacks for UI-only elements to adjust the visual user experience and should not use the callback to inform you of the inquiry’s status.

Client callbacks cannot be used reliably to fetch inquiry status if you are utilizing any post-inquiry features (workflows or manual review). As they are meant only to tell you that the inquiry itself has finished, the status retrieved may be non-deterministic if there is any post-inquiry processing done.

Note: If your only option is to use the client callback for status and you are not implementing any post-inquiry logic, you can disregard the next section on utilizing inquiry decisioning statuses.

Ensure you’re actioning on the correct inquiry statuses

Inquiries will reach a completed or failed status depending on the status of the required verification checks. If your implementation includes any post-inquiry processing (e.g report runs, manual review, or other business logic), you'll want to utilize the inquiry's decisioning statuses to determine how to proceed. These statuses are: approved, declined, and needs-review.

See the Inquiry Model Lifecycle for more details.

Future-proofing your implementation

We recommend setting up a basic workflow triggered on the inquiry.completed event to approve the inquiry. After this is done, you can disregard the completed status and only use the approved status to signify that you can proceed with the user on your platform.

Similarly, you can set up another workflow triggered on inquiry.failed to automatically decline the inquiry so you can disregard the failed status.

Making both of these changes upfront means that any decisions to add post-inquiry processing in the future will not require additional developer resources, because the integration will already be utilizing the correct statuses to know how to proceed.

Resuming inquiries

Resuming an inquiry (rather than creating a brand new inquiry) may enhance user experience-- if your user has already completed part of the inquiry, resuming the inquiry will allow them to pick up where they left off.

We recommend resuming an inquiry if not too much time has passed (e.g one week) since the inquiry was created, and creating a brand new inquiry otherwise, to reflect any updates you've made to the inquiry template in the meantime.

How to do it

• See our Resuming Inquiries documentation.