Hosted Flow (aka verify by link) lets you implement Persona with little to no engineering effort. With Hosted Flow, you send users a URL—for example via email or text—and that URL takes them to your identity verification flow.
As with other integration methods, you can customize this flow to reflect your own brand. See Configuring your Inquiry Template to learn more.
There are two ways to implement Hosted Flow:
- Create Inquiry links via the Hosted Flow link
- Create Inquiry links via the API
Create Inquiry links via Hosted Flow link
Hosted Flow link
For each Inquiry Template in your Persona organization, a Hosted Flow link is automatically created. You can find these Hosted Flow links in your Dashboard.
Whenever you click this Hosted Flow link, it creates a new Inquiry link for that Inquiry Template. Each new Inquiry link enables one end user to go through your Inquiry flow.
Using the Hosted Flow link
There are two main ways you can use the Hosted Flow link:
- You manually create new Inquiry links on behalf of each end user. You—or any member of your team—can quickly generate a new Inquiry link by clicking the Hosted Flow link for the Inquiry Template you want to use. Then, you can send the new Inquiry link to an end user.
End users create their own Inquiry links: You can share the Hosted Flow link directly with end users. Each end user then clicks the Hosted Flow link to generate an Inquiry link for themselves.
- Note: End users may click the Hosted Flow link many times and generate many links by accident. For example, if a user exits the flow partway through and clicks the Hosted Flow link again later, they will create a new Inquiry link instead of resuming their previous one. This can be confusing for the user.
- In general, we recommend you avoid sharing your Hosted Flow link directly with end users. If you choose to share the Hosted Flow link—for example, in an email campaign or mass email—be aware that each end user may generate many links and complete the flow multiple times. Strongly consider prefilling a reference ID. (More on this below.)
Set up a Hosted Flow link
To use a Hosted Flow link:
- Find the Hosted Flow link in the Integration section of your dashboard. If you have more than one template, there will be one link per template.
While you can use each Hosted Flow link as-is, we recommend you include a unique reference ID parameter for each end user. A reference ID is the unique ID you use to identify a user in your own system. By appending a reference ID to the end of your link, you can easily find the associated Inquiry for a given user by searching for reference ID. The reference ID enables you to consolidate all Inquiries for a given user under a single Account.
Example: If your link is:
https://withpersona.com/verify?template-id=tmpl_JAZjHuAT738Q63BdgCuEJQreand you want the Inquiry to be generated with a reference ID for
user_id1, you can append the reference ID to the end of your link by adding
&reference-id=your_user_id1. Your new link will now be:
https://withpersona.com/verify?template-id=tmpl_JAZjHuAT738Q63BdgCuEJQre&reference-id=your_user_id1. When the user clicks into this link, the subsequent inquiry that is created will have
user_id1associated with the Inquiry.
- See our technical documentation for more information on reference IDs and other parameters.
- You can automate passing in parameters by setting up an email template or macro that generates the link with a unique reference ID.
- To personalize your link, you can specify a subdomain name (for example: mycompany.withpersona.com) in the integration page of your dashboard under "Subdomain."
- Once you've created your link, go ahead and try it out in sandbox. On the left hand side of your dashboard, you can toggle to sandbox and find your sandbox link in the integration page. Afterwards, you can view the inquiry on your inquiry page.
- If you want to be notified when a user completes their inquiry, you can set up a webhook or create a queue in your Persona dashboard to be notified of specific inquiry events.
Create Inquiry links via the API
Creating a link via API is a way to get the best of both worlds. You can ensure each user gets one unique Inquiry link, without having to create each link manually.
This approach requires some engineering support, but is the best option if you have a high volume of inquiries to create.
See our developer documentation to learn how to set this up.
As with the Hosted Flow link, we recommend that you pass in a reference ID as an attribute when you create the Inquiry link. A reference ID is the unique ID you use to identify a user in your own system. By passing in a reference ID, you can easily find the associated inquiry for a given user by searching for reference ID.
When do hosted flow links expire?
See: When does a link to an Inquiry expire?
What can I do if a link (or the inquiry) has expired and I want to allow the user to continue in the same inquiry where they left off?
See: Resume an expired Inquiry