US Database Verification

This solution allows you to streamline identity verification by performing a lightweight check of end-user’s basic data (name, address, phone number), enhance fraud detection with an additional security layer, or validate comprehensive identity Social Security Number (SSN) and Drivers’ Licences (DLs). It is flexible, meaning you are in control of which data points are prioritized in the decision making.

US Database Verification can be:

• an add-on to your document + selfie IDV or document-only IDV, or

• used separately as a stand-alone check.

It is available over native SDKs, web SDKs (aka webflow), and via API.

You set it up using the Workflows in Veriff Customer Portal.

Prerequisites

• You have an integration set up with Veriff

• The database check is configured for that integration by your Solutions Engineer

• You have configured the decision webhook to get responses from Veriff  (see the how-to in webhooks’ Set up webhooks section)

• If using the API, you are ready to collect and send Veriff your end-user’s data

End-user data sources

The checks are performed on end-user’s data, which can come from two data sources: document data and initData.

Irrespective of the data source and the purpose for the database check, firstName and lastName are always required

The minimum data combinations to run a successful check are:

• First Name + Last Name + Date of Birth

• First Name + Last Name + Full Address

• First Name + Last Name + SSN and/or Drivers License

• First Name + Last Name + Phone

Document data

This means that the checks are completed using the data extracted from the end-user’s document. Fields extracted from the document and applicable for database check:

• Person’s first name, last name, date of birth and ID number

• Person’s document number

• Person’s address data

initData

This means that the checks completed using the data you input during the session creation, i.e. the parameters you specify in the POST /sessions request. Parameters you can define in the request:

In verification.person object:

• firstName

• lastName

• dateOfBirth

• phoneNumber

In verification.document object:

• number for SSN check

In verification.address object:

• fullAddress

Address data guidelines

To improve match rates, provide the address data in the following format: [House Number] [Street Name] [City] [State] [ZIP Code]

Include all the required parts and any optional details you have. Use spaces between each main part (house number, street name, city, state, ZIP). For units (e.g., "Apt 2307"), a space or comma before the unit works fine.

Guidelines

1. House Number: Start with your house or building number (e.g., "123"). If there’s a suffix like "A" or "1/2", add it after a comma (e.g., "123, A").

2. Street Name: Include the full street name (e.g., "Main St"). If you have a unit like "Apt 4B" or "Suite 100", add it after a space or comma (e.g., "Main St Apt 4B" or "Main St, Apt 4B").

3. City: Provide the city name (e.g., "Austin").

4. State: Use the two-letter state abbreviation (e.g., "TX").

5. ZIP Code: Include your 5-digit ZIP code (e.g., "78701") or 9-digit ZIP (e.g., "78701-1234").

Note: do not worry if you are missing some details, just include what you have. As an expected result, around 50% of matches for Addresses are Partial Matches, and Veriff sends the data broken down into City, State and Zip code besides the Address line.

Select decision parameter(s)

In the Veriff Customer Portal > workflows UI, you can choose which parameters will be part of the decision-making.

• Always required: firstName, lastName

• document.number required only for the SSN validation

• Optional: dateOfBirth, fullAddress and phoneNumber

Select input source priority

In the Veriff Customer Portal > workflows UI, you can customize the decision-making even further by choosing which data source (document data or initData) takes priority when the decision is made. It means that the match level of the prioritised source data will have a higher impact on the session decision than other data.

This also means that if there are two values present for a piece of data (because it was sent with initData and could be extracted from document data) the data source priority determines which value is used.

Flow overview

The flow is a bit different depending on the purpose you are doing the US Database Verification check for.

Light KYC

Can be used to quickly verify basic data about the end-user, e.g., name, date of birth, address, phone.

Light KYC can be done using only the document data source (data is extracted from document images) or only the initData source (data is input during session creation), or with a combination of both

• Required: firstName, lastName

• Optional: dateOfBirth, phoneNumber, fullAddress

Flow (SDK/API)

The database check can be a stand-alone feature or integrated seamlessly to the IDV flow. In the latter case, the end-users pass through the verification flow as usual, the database checks are completed in the background.

POST /sessions payload

With initData

curl -X POST \
  --url '/v1/sessions/' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-KEY' \
  -d '{
    "verification": {
        "callback": "https://veriff.com",
        "person": {
            "firstName": "John",
            "lastName": "Smith",
            "dateOfBirth": "1980-01-01",
            "phoneNumber": "88888888888",
        },
        "address": {
            "fullAddress": "Lorem Ipsum 30, 13612 Tallinn, Estonia"
        },
    }
}'

Flow diagrams

Driver’s Licence check

In this case, the document data source must be used, meaning that the data needs to be extracted from end-user’s driver’s licence and checked against the data in the database. initData source cannot be used to pass additional data.

Flow (SDK/API)

→ See the Create verification session article for examples of minimal POST /session payloads for SDK and API

Flow diagrams

SSN check

In this case you need to collect and send Veriff the end-user’s SSN number (9 digits). You must use the initData source to pass the SSN number, but you can enhance the depth of verification with the document data source and send Veriff end-user’s document image(s).

• Required: document.number (= SSN), firstName and lastName

• Optional: dateOfBirth

Note that for the US Database Verification, the SSN must be passed via verification.document.number parameter. The system will assume that the value in document.number field is the SSN.

Flow (SDK/API)

POST /sessions payload

With mandatory and optional initData.

curl -X POST \
  --url '/v1/sessions/' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-KEY' \
  -d '{
    "verification": {
        "callback": "https://veriff.com",
        "person": {
            "firstName": "John",
            "lastName": "Smith",
            "dateOfBirth": "1980-01-01"
        },
        "document": {
            "number": "123456789"
        },
    }
}'

Flow diagrams

Find session and/or decision related info

All the end-user data that had been input or extracted and that was matched against the database is returned in additionalVerifiedData.validationResults .

During the check, all the info from document data and initData sources are simply matched with info in the database. No additional analysis is performed. This means that the response indicates if the data was:

• match

• partial_match

• no_match

• invalid (there was an error in input data format)

• no_input (the initData did not contain any info)

• no_data (no data could be extracted from source)

Webhook payload

Below are a sample and an explanation of a decision webhook payload for the check.

Depending on your solution, the payload may contain additional parameters. To find more info about it, see the decision webhook documentation.

Sample request

{
  "status": "success",
  "verification": {
    "acceptanceTime": "2025-04-02T13:12:32.520216Z",
    "decisionTime": "2025-04-02T13:12:43.125995Z",
    "code": 9001,
    "id": "2919ea7b-fbdf-4f54-b9e4-fbdf53e54f54",
    "vendorData": null,
    "endUserId": null,
    "status": "approved",
    ...
    "additionalVerifiedData": {
      "validationResults": [
        {
          "registryName": "USA - Credit + US Identity Graph (US15)",
          "firstName": "MATCH",
          "lastName": "MATCH",
          "dateOfBirth": "NO_INPUT",
          "address": "PARTIAL_MATCH",
          "city": "MATCH",
          "state": "MATCH",
          "zip": "MATCH",
          "idNumber": "NO_DATA"
        }
      ]
    },
    "attemptId": "1fa9e995-b9e4-46fe-90fa-efd6f2b1e995"
  },
  "technicalData": {
    "ip": null
  }
}

Request properties explained

*Always sent, irrespective of solution’s configuration

• status: string* Status of the response

• verification: object* Verification request decision object. null if decision is not available yet

  • id: string* UUID v4 which identifies the verification session

  • attemptId: string* UUID v4 of the attempt which received a status (as shown in verification.status field)

  • vendorData: string | null* The unique identifier that you created for your end-user. null if not specified

  • endUserId: string | null* The UUID that you created for your end-user. null if not specified

  • status: string* Verification status, one of approved, declined, resubmission_requested, review, expired, abandoned

  • decisionTime: string* Timestamp of the decision, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

  • acceptanceTime: string* Timestamp of the session generation, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

  • …

  • additionalVerifiedData: array Data that has been optionally verified for the session, depending on the integration. Empty if no additional data was verified

    • registryName: string Name of the registry

    • firstName: string Indicates the match level of person’s first name data

    • lastName: string Indicates the match level of person’s last name data

    • dateOfBirth: string Indicates the match level of person’s date of birth data

    • address: string Indicates the match level of person’s address data

    • city: string Indicates the match level of person’s address data, specifically city

    • state: string Indicates the match level of person’s address data, specifically state

    • zip: string Indicates the match level of person’s address data, specifically zip code (post code)

    • idNumber: string Indicates the match level of person’s identity number or SNN number data

• technicalData: object* Technical data object

• ip: string | null IP of the device from which the verification was made

API call

Below are a sample and an explanation of a GET /decison call payload for the check.

Depending on your solution, the payload may contain additional parameters. To find more info about it, see the GET sessions/{sessionId}/decision[↗] documentation.

Sample request

{
  "status": "success",
  "verification": {
    "acceptanceTime": "2025-04-02T13:12:32.520216Z",
    "decisionTime": "2025-04-02T13:12:43.125995Z",
    "code": 9001,
    "id": "2919ea7b-fbdf-4f54-b9e4-fbdf53e54f54",
    "vendorData": null,
    "endUserId": null,
    "status": "approved",
    ...
    "additionalVerifiedData": {
      "validationResults": [
        {
          "registryName": "USA - Credit + US Identity Graph (US15)",
          "firstName": "MATCH",
          "lastName": "MATCH",
          "dateOfBirth": "NO_INPUT",
          "address": "PARTIAL_MATCH",
          "city": "MATCH",
          "state": "MATCH",
          "zip": "MATCH",
          "idNumber": "NO_DATA"
        }
      ]
    },
    "attemptId": "1fa9e995-b9e4-46fe-90fa-efd6f2b1e995"
  },
  "technicalData": {
    "ip": null
  }
}

Request properties explained

*Always sent, irrespective of solution’s configuration

• status: string Status of the response

• verification: object Verification request decision object. null if decision is not available yet

  • id: string UUID v4 which identifies the verification session

  • attemptId: string UUID v4 of the attempt which received a status (as shown in verification.status field)

  • vendorData: string | null The unique identifier that you created for your end-user. null if not specified

  • endUserId: string | null The UUID that you created for your end-user. null if not specified

  • status: string Verification status, one of approved, declined, resubmission_requested, review, expired, abandoned

  • decisionTime: string Timestamp of the decision, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

  • acceptanceTime: string Timestamp of the session generation, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

  • …

  • additionalVerifiedData: array Data that has been optionally verified for the session, depending on the integration. Empty if no additional data was verified

    • registryName: string Name of the registry

    • firstName: string Indicates the match level of person’s first name data

    • lastName: string Indicates the match level of person’s last name data

    • dateOfBirth: string Indicates the match level of person’s date of birth data

    • address: string Indicates the match level of person’s address data

    • city: string Indicates the match level of person’s address data, specifically city

    • state: string Indicates the match level of person’s address data, specifically state

    • zip: string Indicates the match level of person’s address data, specifically zip code (post code)

    • idNumber: string Indicates the match level of person’s identity number or SSN number data

• technicalData: object Technical data object

• ip: string | null IP of the device from which the verification was made

Veriff Customer Portal

You can find the verification session related info, including the decision, in the Veriff Customer Portal, under the Webhooks tab.

Article versioning