Integration Guide: Database Verification via API

Solution overview

Silently orchestrates a database verification on an individual
Can be configured to support a variety of countries

Pre-integration

Make sure your organization is set up with the requisite transaction and workflows! Reach out to your Persona team for support with this.
For each country you want to support, review the match requirements with your Persona team
Think about any additional post-verification business logic you want to apply to your users in the Persona Workflow (report runs, age checks, etc)
Think about if there are any situations that would warrant a manual review of the user, using Persona Cases.

Integration Steps

1. Create the Transaction

Please ensure you’re including the reference_id property under the attributes object: this will be the value you use to identify the user’s Persona account
Use your Production API key to create Production transactions, and your Sandbox API key to create Sandbox transactions

Transaction fields

Whether or not these fields are required will depend on your configuration of required and non-required inputs for each country.

Field	Type	Required?	Description
name_first	String	true	First Name
name_last	String	true	Last name
name_middle	String	false	Middle name. May be used in reports, but not the database verification itself.
birthdate	Date	true	Birthdate, in the format of `YYYY-MM-DD`
address_street_1	String	true	Address street 1
address_street_2	String	false	Address street 2
address_city	String	true	Address city
address_postal_code	String	true	Address postal code
address_subdivision	String	true	Address subdivision (state). Abides by ISO 3166-2 standards.
address_country_code	String	true	2-letter country code. See Persona’s list of supported countries in your dashboard.
tax_identification_number	String	true	Tax Identification Number (e.g SSN)
document_number	String	false	Additional document number used for certain countries’ data sources (e.g AU)
email_address	String	false	Email address
phone_number	String	false	Phone number
debug	String	false	For Sandbox verifications only: set as `passed` to pass the verification or `failed` to force-fail the verification. By default, the verification will pass.

Sample cURL command

curl

1 curl -X POST https://api.withpersona.com/api/v1/transactions \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer <API KEY>" \
4 -d '{
5   "data": {
6     "attributes": {
7       "transaction_type_id": "<your transaction ID>",
8       "reference_id": "<your internal identifier for the user>",
9       "fields": {
10         "name_first": "Persona",
11         "name_middle": "",
12         "name_last": "Test",
13         "birthdate": "2000-01-01",
14         "address_street_1": "201 Post St",
15         "address_street_2": "",
16         "address_city": "San+Francisco",
17         "address_subdivision": "CA",
18         "address_postal_code": "94108",
19         "address_country_code": "US",
20         "email_address": "personatest@withpersona.com",
21         "phone_number": "4058675309",
22         "document_number": "",
23         "debug": "passed",
24         "tax_identification_number":"123"
25       }
26     }
27   }
28 }'

2. Listen for the Transaction status

Listen to the transaction.status-updated webhook (docs) to fetch the information verified and to know how to proceed with the user.

Transaction statuses

To view and edit these statuses, click “… > Custom Statuses” on your transaction type’s page

Status name	Description
`created`	Transaction has been created.
`approved`	Transaction has been approved: you can proceed with the user.
`declined`	Transaction has been declined: verification unsuccessful or user otherwise declined.
`needs_review`	Transaction is awaiting manual review.
`errored`	Transaction has errored.

Fallback inquiry orchestration

If your transaction flow includes a fallback to a Persona UI inquiry (most commonly Government ID and Selfie), you’ll have the following additional fields and statuses.

Additional fields

Field	Type	Description
`fallback_inquiry_id`	String	Persona will create and populate this field with the inquiry ID for you to surface to your user.

Additional statuses

Status name	Description
`pending_fallback_inquiry`	The transaction will reach this status if a fallback inquiry has been created. On receipt of this status update, you will know that `fallback_inquiry_id` has been populated and your next action will be to surface that inquiry.