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://api.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://api.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://api.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://api.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 again
• passed: The verification has passed
• failed: The verification has failed