Tutorial: API-based database verifications
This integration guide will show you how to create and submit a database verification via Persona's server APIs.
Template setup required
This guide assumes you have a template (
tmpl_
) specifically configured for database verifications. Please contact your Persona support team if you need a template.
1. Create an inquiry
Make a POST call to create the inquiry
API_KEY=<YOUR_API_KEY_HERE>
curl -X POST https://withpersona.com/api/v1/inquiries \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $API_KEY" \
-d'{
"data": {
"attributes": {
"template-id": "{TEMPLATE_ID}",
"reference-id": "test-reference-id"
}
}
}'
From the response body, you should grab the newly created Inquiry ID to pass to the verifications endpoint in Step 2. It is nested under response['data']['id']
.
The inquiry will use the specified template to determine what verifications are required. The reference-id
token is an optional reference token that should map to your internal user id. It allows you to uniquely identify individual users. For more details on creating inquiries, see the document here.
2. Create the verification
Now you'll create a database verification. In the sandbox environment, specifying the "meta: debug-forced-status
parameter allows you to test the passed
and failed
statuses. In the production environment, this parameter is ignored.
This example shows all the possible fields that can be passed through for a database verification. Most likely you will only be passing through a subset of these fields. You'll work with your Persona team to determine your business requirements for database verification.
INQUIRY_ID="{inquiry_id_retrieved_on_step_1}"
curl -X POST https://withpersona.com/api/v1/verification/databases \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $API_KEY" \
-d'{
"data": {
"type": "verification/database",
"attributes": {
"inquiry-id": "{INQUIRY_ID}",
"name-first": "Alexander",
"name-last": "Sample",
"birthdate": "1970-01-20",
"address-street-1": "123 Main St",
"address-street-2": "Apt 1",
"address_subdivision": "California",
"address-city": "San Francisco",
"address-postal-code": "123455",
"identification-number": "123-12-1234",
"phone-number": "1234567890",
"country-code": "US"
}
},
"meta": {
"debug-forced-status": "passed"
}
}'
From the response body, grab the newly created verification ID to pass to the submit endpoint in Step 3. It will be nested under response['data']['id']
.
3. Submit the verification
Submit the verification for processing
VERIFICATION_ID="{VERIFICATION_ID FROM STEP 2}"
curl -X POST https://withpersona.com/api/v1/verification/databases/$VERIFICATION_ID/submit \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $API_KEY"
Verifications processing execute asynchronously. You can listen to webhooks or poll the verification until the status changes to passed or failed.
4. (Optional) Retrieve the verification
curl https://withpersona.com/api/v1/verification/databases/$VERIFICATION_ID \
-H "Authorization: Bearer $API_KEY"
You'll find the verification's status in response["data"]["attributes"]["status"]
. Applicable statuses are:
submitted
: The verification is still processing and you may need to poll the status againpassed
: The verification has passedfailed
: The verification has failed
Updated 9 months ago