DocumentationAPI Reference
DocumentationAPI ReferenceStatus

Prevent Users From Creating Multiple Inquiries

Some Persona inquiry templates are only meant to be finished once per user. For example, you might have an onboarding template where, if the user passes verification, they gain access to your site. If they fail, they should be denied access.

You will want to prevent your users from creating multiple inquiries on these templates for the following reasons:

  • Fraud vector: Allowing a user to create multiple inquiries on the same template can effectively give them unlimited attempts to try and pass Persona’s verifications
  • Increased user friction: your users may be confused why they’re being asked to verify their identity multiple times

Best practice for preventing multiple inquiries per user

1. Assign each user a Reference ID upon inquiry creation

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

Inquiries created with the same Reference ID will all get associated with the same account, which is how you can tell if a user has already gone through the Persona flow.

2. Before loading the Persona widget, check to see if the user has already gone through Persona Verification

👍

Ideally, you will have saved the user's verification status in your internal systems and can route the user accordingly without querying Persona for previous inquiries.

If you don't have this implemented, please read on.

You will want to check if there are existing inquiries with your user's Reference ID

  1. Make a call to List all Inquiries and filter on the account’s Reference ID.
  2. Filter the inquiries returned on the specific template you’re checking for.
import requests

reference_id = "your reference ID here"
inquiry_template_id = "your inquiry template ID here"
api_key = "your API key here"

url = f"https://withpersona.com/api/v1/inquiries?filter[reference-id]={reference_id}"

headers = {
    "accept": "application/json",
    "Persona-Version": "2022-09-01",
    "Authorization": f"Bearer {api_key}"
}

response = requests.get(url, headers=headers)
inquiries = response.json()["data"]

# Filter for your specific inquiry template
template_property = "template" if inquiry_template_id.startswith("tmpl_") else "inquiry-template"
relevant_inquiries = list(
    filter(lambda inquiry: inquiry["relationships"][template_property]["data"]["id"] == inquiry_template_id, inquiries))

3. Decide how to proceed based on the user’s existing inquiries

if len(relevant_inquiries) == 0:
    createNewInquiry()

else:
    # If you have multiple created inquiries under this template, 
        # you may want to look at all of their statuses and decide how to proceed
    existing_inquiry = relevant_inquiries[0]
    existing_inquiry_status = existing_inquiry["attributes"]["status"]

    handleExistingInquiry(existing_inquiry_status)
  1. If there is an existing inquiry that has already successfully finished (where the status is completed or approved), there may be no need to create a new inquiry and you can let the user onto your system.

  2. If there is an existing inquiry that has unsuccessfully finished (where the status is failed, declined, or marked-for-review), you may want to actively prevent the user from creating a new inquiry, as they have previously failed Persona verification.

  3. If there is an existing inquiry with a status of expired, you can
    i. Resume this inquiry
    ii. Create a new inquiry with the same Reference ID

How you proceed here should be determined by your internal business logic (for example: if too long of time has passed since the last expired inquiry, for security reasons you might want to create a new inquiry).

🚧

The “correct” status to search for will depend on your Persona setup as well as your usage of Persona workflows. Refer to this document for an explanation of statuses.

4. Save the user’s Persona verification status into your internal system

To avoid having to look up a user’s inquiries in this fashion every time they access your site, you can save their verification status in your system and query that status when necessary.