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. Create Inquiries via API

Creating Inquiries via API restricts end users from arbitrarily creating Inquiries. See Creating Inquiries via API for more information.

2. 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.

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

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.

1
import requests
2
3
reference_id = "your reference ID here"
4
inquiry_template_id = "your Inquiry template ID here"
5
api_key = "your API key here"
6
7
url = f"https://api.withpersona.com/api/v1/inquiries?filter[reference-id]={reference_id}"
8
9
headers = {
10
    "accept": "application/json",
11
    "Persona-Version": "<api version>",
12
    "Authorization": f"Bearer {api_key}"
13
}
14
15
response = requests.get(url, headers=headers)
16
inquiries = response.json()["data"]
17
18
# Filter for your specific Inquiry template
19
template_property = "template" if inquiry_template_id.startswith("tmpl_") else "inquiry-template"
20
relevant_inquiries = list(
21
    filter(lambda inquiry: inquiry["relationships"][template_property]["data"]["id"] == inquiry_template_id, inquiries))

4. Decide how to proceed based on the user’s existing Inquiries

1
if len(relevant_inquiries) == 0:
2
    createNewInquiry()
3
4
else:
5
    # If you have multiple created Inquiries under this template, 
6
		# you may want to look at all of their statuses and decide how to proceed
7
    existing_inquiry = relevant_inquiries[0]
8
    existing_inquiry_status = existing_inquiry["attributes"]["status"]
9
10
    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.

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

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

We recommend you first check to see if the existing Inquiry’s template version (a string beginning with itmplv_) is the same as the Inquiry template’s current version, to ensure the Inquiry your user is going through has the most up-to-date configuration. In order to do so, you should first retrieve this inquiry, and then you should resume the Inquiry if the two versions match (which will allow the user to pick up where they left off), and create a new Inquiry if the versions do not match.

1
existing_inquiry_template_version = existing_inquiry["data"]["relationships"]["inquiry-template-version"]["data"]["id"]
2
template_object = list(filter(lambda x: x["type"] == "inquiry-template", existing_inquiry["included"]))[0]
3
current_template_version = template_object["relationships"]["latest-published-version"]["data"]["id"]
4
5
if existing_inquiry_template_version == current_template_version:
6
    resume_inquiry()
7
    
8
else:
9
    create_new_inquiry()

5. Save the user’s Inquiry 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 Inquiry status in your system and query that status when necessary.