DocumentationAPI Reference
API ChangelogOpenAPI SpecStatus

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


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

name_firstStringtrueFirst Name
name_lastStringtrueLast name
name_middleStringfalseMiddle name. May be used in reports, but not the database verification itself.
birthdateDatetrueBirthdate, in the format of YYYY-MM-DD
address_street_1StringtrueAddress street 1
address_street_2StringfalseAddress street 2
address_cityStringtrueAddress city
address_postal_codeStringtrueAddress postal code
address_subdivisionStringtrueAddress subdivision (state). Abides by ISO 3166-2 standards.
address_country_codeStringtrue2-letter country code. See Persona's list of supported countries in your dashboard.
tax_identification_numberStringtrueTax Identification Number (e.g SSN)
document_numberStringfalseAdditional document number used for certain countries' data sources (e.g AU)
email_addressStringfalseEmail address
phone_numberStringfalsePhone number
debugStringfalseFor 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 -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API KEY>" \
-d '{
  "data": {
    "attributes": {
      "transaction_type_id": "<your transaction ID>",
      "reference_id": "<your internal identifier for the user>",
      "fields": {
        "name_first": "Persona",
        "name_middle": "",
        "name_last": "Test",
        "birthdate": "2000-01-01",
        "address_street_1": "201 Post St",
        "address_street_2": "",
        "address_city": "San+Francisco",
        "address_subdivision": "CA",
        "address_postal_code": "94108",
        "address_country_code": "US",
        "email_address": "[email protected]",
        "phone_number": "4058675309",
        "document_number": "",
        "debug": "passed",

2. Listen for the Transaction status

We recommend listening to the transaction.status-updated webhook (docs) to know when to proceed. You can alternatively make an API call to fetch the transaction (docs)

Transaction statuses

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

Status nameDescription
createdTransaction has been created.
approvedTransaction has been approved: you can proceed with the user.
declinedTransaction has been declined: verification unsuccessful or user otherwise declined.
needs_reviewTransaction is awaiting manual review.
erroredTransaction 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

fallback_inquiry_idStringPersona will create and populate this field with the inquiry ID for you to surface to your user.

Additional statuses

Status nameDescription
pending_fallback_inquiryThe 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.