Match Database Verifications

New
  • Updated on Dec 3, 2025
  • Published on Dec 3, 2025
Prev Next

Available

via API

Available

via SDK

Needs configuration

on Veriff’s side

Needs a

separate integration

Needs a

separate webhook

✅

✅

✅

❌/✅*

❌

Match Database Verification solution that validates end-user’s personal information against official databases. The personal data (name, address, date of birth, etc.) is cross-referenced directly with trusted registries to confirm identity without requiring document uploads. The solution provides match status results (match, partial match, no match, no Input, no data) for submitted data fields to help prevent fraud and enhance identity verification accuracy.

*This solution can be:

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

  • used separately as a stand-alone check. In this case the whole flow is done over the API and you need to input all the data in initData.

All session-related info is returned via decision webhook and can be polled from different API endpoints. The results of the verification can also be viewed in the Veriff Customer Portal, in the webhook payload in the Webhook tab.

If any data was extracted from the document, this data is provided in the decision webhook payload and GET /decision endpoint’s response payload.

Contact your solutions engineer for info and configuration.

Prerequisites

  • You have an integration set up with Veriff

  • The match 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

Irrespective of the country or the database, firstName and lastName are always required.

Some databases require you send additional data about the end-user, check regional databases’ documentation for the exact list of fields.

End-user data sources

The “end-user data sources” refer to different origins from which the end-user’s information can be collected for database verification. There are two data sources: document data and initData.

This is data that is extracted from the end-user’s document. Includes information like names, date of birth, ID numbers or addresses extracted from ID cards, passports, driver's licenses, etc.

This is data that you provide when creating a verification session, i.e. the parameters you specify in the POST /sessions request. Includes information like names, date of birth, address, phone number, ID number, gender etc.

Irrespective of the database, firstName and lastName are always required in verification.person parameter.

Parameters used to send initData:

  • first name via person.firstName

  • last name via person.lastName

  • date of birth via person.dateOfBirth

  • phone number via person.phoneNumber

  • gender via person.gender

  • address via address.fullAddress

  • ID number via document.number

Flow overview

Database flow

Match Database Verifications follows a simple flow.

Step 1: you input end-user’s data (initData or document)

Step 2: system queries the appropriate database(s) based on country/region

Step 3: match analysis

Field-by-field comparison between input data and registry data, leading to match confidence scoring and validation of multiple data points (name, DOB, address, etc.)

Step 4: match confidence decision

Returns one of the following:

  • MATCH: data confirmed in registry, session is successful

  • PARTIAL_MATCH: some fields match, others do not. This requires review, the partial mismatch may be due to error in data.

  • NO_MATCH: data not found or does not match, can indicate potential fraud, data error or outdated registry. You should create flows to fallback to an alternative method.

  • NO_INPUT: required data not provided via document or initData data source, meaning this field cannot be verified

  • NO_DATA: registry unavailable or no data returned, meaning either there is an issue contacting the database, or the end-user’s data is missing in database

Step 5: webhook is sent

The webhooks contains:

  • Match conclusion per field sent and supported by registry

  • Info about decision influence based on selected compared fields

Contact your Solutions Engineer for more information about the match confidence scoring and fields comparing setup.

Session flow

In Match Database Verification sessions, person’s ID number is always sent in document.number field.

Use via SDK

  1. Generate a verification session using the API keys and the baseURL of your integration (see the API Documentation and API Reference[↗] how to find these)

    • You can pass the firstName, lastName and other parameters in the session creation request (e.g., if that particular info is missing from the document). Check each database’s documentation to see which parameters are required and allowed.

  2. Capture end-user’s document (and selfie) images with Veriff’s SDKs

    • Send the end-user through the verification flow to capture the images (using the preferred Veriff SDK)

    • You need the session URL generated in step 1 to use the SDKs (found in response payload as verification.url)

  3. Session will be submitted automatically once the end-user takes and submits necessary images

  4. End-user’s data is extracted

  5. Database checks are run

  6. Receive the results from Veriff via decision webhook or poll them from GET /decision endpoint. Check each database’s documentation to see and example of the webhook and API response payload.

Use via API

  1. Generate a verification session using the API keys and the baseURL of your integration (see the API Documentation and API Reference[↗] how to find these)

    • Make sure to pass the mandatory firstName and lastName

    • You can pass other parameters in the session creation request. Check each database’s documentation to see and example of suitable session start payload.

  1. OPTIONAL: if you have decided to use also the document data source, send the end-user’s document images:

Sample request payload

curl -X POST /v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/media \
  -H "Content-Type: application/json" \
  -H "X-AUTH-CLIENT: cd938f72-72c8-4a7b-b5c6-2f1b6d5a9c8e" \
  -H "X-HMAC-SIGNATURE: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53" \
  -d '{
    "image": {
      "context": "document-front",
      "content": "base64-encoded-selfie-data",
      "timestamp": "2024-01-15T10:31:00Z"
    }
  }'

  1. Patch session status to submitted status using PATCH /sessions/{sessionId}[↗] call

Sample request payload

curl -X PATCH /v1/sessions/fd5c1563-1d23-4b1a-ae46-7ba429927ed8 \
  -H "Content-Type: application/json" \
  -H "X-AUTH-CLIENT: API-KEY" \
  -H "X-HMAC-SIGNATURE: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53" \
  -d '{"status": "submitted"}'

  1. If you sent images, end-user’s data is extracted

  2. Database checks are run

  3. Check the decision data and/or session related info from the decision webhook and/or query the data from the GET /decisions endpoint. Check each database’s documentation to see and example of the webhook and API response payload.

Databases by regions

North America

LATAM

EMEA

APAC

North America

USA 🇺🇸

Source

Input parameters

POST /sessions example

Credit Database (US15)

Mandatory:

  • first name via person.firstName

  • last name via person.lastName

Optional:

  • date of birth via person.dateOfBirth

  • phone number via person.phoneNumber

  • address via address.fullAddress

  • ID number (SSN/DLS) via document.number

{
 "verification": {
   "person": {
     "firstName": "John",
     "lastName": "Smith",
     "dateOfBirth": "1990-01-01",
     "phoneNumber": "8888888888"
   },
   "document": {
     "number": "123456789"
   },
   "address": {
     "fullAddress": "123, Main Street, Your County, Anytown 12345"
   } 
}

 

Sample response payload

The following info can be found in decision webhook payload and GET /decision endpoint’s payload, in verifications.additionalVerifiedData object. Note that the payloads contain more parameters, to find info about them see the decision webhook and GET /decision endpoint’s documentation.

{...
  "additionalVerifiedData": {
     "validationResults": [
        {
           "registryName": "USA - Credit + US Identity Graph (US15)",
           "firstName": "MATCH",
           "lastName": "MATCH",
           "dateOfBirth": "NO_DATA",
           "address": "PARTIAL_MATCH",
           "idNumber": "MATCH",
           "phoneNumber": "PARTIAL_MATCH"
         }
     ]
  }
}

LATAM

Argentina 🇦🇷

Source

Input parameters

POST /sessions example

Renaper (AR9)

Mandatory:

  • first name via person.firstName

  • last name via person.lastName

Optional:

  • date of birth via person.dateOfBirth

  • gender via person.gender

  • address via address.fullAddress

  • ID number (DNI/CUIL) via document.number

{
 "verification": {
   "person": {
     "firstName": "John",
     "lastName": "Smith",
     "dateOfBirth": "1990-01-01",
     "gender": "M"
   },
   "document": {
     "number": "123456789"
   },
   "address": {
     "fullAddress": "123, Main Street, Your County, Anytown 12345"
   } 
}

Sample webhook

The following info can be found in decision webhook payload and GET /decision endpoint’s payload, in verifications.additionalVerifiedData object. Note that the payloads contain more parameters, to find info about them see the decision webhook and GET /decision endpoint’s documentation.

{...
  "additionalVerifiedData": {
     "validationResults": [
        {
           "registryName": "Argentina - Renaper (AR9)",
           "firstName": "MATCH",
           "lastName": "MATCH",
           "dateOfBirth": "MATCH",
           "address": "PARTIAL_MATCH",
           "idNumber": "MATCH",
           "gender": "NO_DATA"
         }
     ]
  }
}

Peru 🇵🇪

Source

Input parameters

POST /sessions example

Official Voter Register (PE1)

Mandatory:

  • first name via person.firstName

  • last name via person.lastName

  • address via address.fullAddress (city is required)

Optional:

  • date of birth via person.dateOfBirth

  • gender via person.gender

  • ID number via document.number

{
 "verification": {
   "person": {
     "firstName": "John",
     "lastName": "Smith",
     "dateOfBirth": "1990-01-01",
     "gender": "M"
   },
   "document": {
     "number": "123456789"
   },
   "address": {
     "fullAddress": "Anytown"
   } 
}

Sample webhook

The following info can be found in decision webhook payload and GET /decision endpoint’s payload, in verifications.additionalVerifiedData object. Note that the payloads contain more parameters, to find info about them see the decision webhook and GET /decision endpoint’s documentation.

{...
  "additionalVerifiedData": {
     "validationResults": [
        {
           "registryName": "Peru - Official Voter Register (PE1)",
           "firstName": "MATCH",
           "lastName": "MATCH",
           "dateOfBirth": "MATCH",
           "address": "PARTIAL_MATCH",
           "idNumber": "MATCH"
           "gender": "NO_DATA"
         }
     ]
  }
}

EMEA

Germany 🇩🇪

Source

Input parameters

POST /sessions example

Civil Register & Credit (DE8)

Mandatory:

  • first name via person.firstName

  • last name via person.lastName

Optional:

  • date of birth via person.dateOfBirth

  • phone number via person.phoneNumber

  • address via address.fullAddress

{
 "verification": {
   "person": {
     "firstName": "John",
     "lastName": "Smith",
     "dateOfBirth": "1990-01-01",
     "phoneNumber": "8888888888"
   },
   "address": {
     "fullAddress": "123, Main Street, Your County, Anytown 12345"
   } 
}

Sample response payload

The following info can be found in decision webhook payload and GET /decision endpoint’s payload, in verifications.additionalVerifiedData object. Note that the payloads contain more parameters, to find info about them see the decision webhook and GET /decision endpoint’s documentation.

{...
  "additionalVerifiedData": {
     "validationResults": [
        {
           "registryName": "Germany - Civil Register & Credit (DE8)",
           "firstName": "MATCH",
           "lastName": "MATCH",
           "dateOfBirth": "MATCH",
           "address": "PARTIAL_MATCH",
           "phoneNumber": "PARTIAL_MATCH"
         }
     ]
  }
}

Greece 🇬🇷

Source

Input parameters

POST /sessions example

Voter Register & Credit (GR1)

Mandatory:

  • first name via person.firstName

  • last name via person.lastName

Optional:

  • date of birth via person.dateOfBirth

  • phone number via person.phoneNumber

  • gender via person.gender

  • address via address.fullAddress

  • ID number via document.number

{
 "verification": {
   "person": {
     "firstName": "John",
     "lastName": "Smith",
     "dateOfBirth": "1990-01-01",
     "phoneNumber": "8888888888",
     "gender": "M"
   },
   "document": {
     "number": "123456789"
   },
   "address": {
     "fullAddress": "Anytown"
   } 
}

Sample response payload

The following info can be found in decision webhook payload and GET /decision endpoint’s payload, in verifications.additionalVerifiedData object. Note that the payloads contain more parameters, to find info about them see the decision webhook and GET /decision endpoint’s documentation.

{...
  "additionalVerifiedData": {
     "validationResults": [
        {
           "registryName": "Greece - Voter Register & Credit (GR1)",
           "firstName": "MATCH",
           "lastName": "MATCH",
           "dateOfBirth": "MATCH",
           "address": "PARTIAL_MATCH",
           "idNumber": "MATCH",
           "phoneNumber": "PARTIAL_MATCH",
           "gender": "NO_DATA"
         }
     ]
  }
}

Morocco 🇲🇦

Source

Input parameters

POST /sessions example

Mobile Phone Register (MA1)

Mandatory:

  • first name via person.firstName

  • last name via person.lastName

Optional:

  • date of birth via person.dateOfBirth

  • phone number via person.phoneNumber

  • gender via person.gender

  • address via address.fullAddress (city is required)

{
 "verification": {
   "person": {
     "firstName": "John",
     "lastName": "Smith",
     "dateOfBirth": "1990-01-01",
     "phoneNumber": "8888888888",
     "gender": "M"
   },
   "address": {
     "fullAddress": "Anytown"
   } 
}

Sample response payload

The following info can be found in decision webhook payload and GET /decision endpoint’s payload, in verifications.additionalVerifiedData object. Note that the payloads contain more parameters, to find info about them see the decision webhook and GET /decision endpoint’s documentation.

{...
  "additionalVerifiedData": {
     "validationResults": [
        {
           "registryName": "Morocco - Mobile Phone Register (MA1)",
           "firstName": "MATCH",
           "lastName": "MATCH",
           "dateOfBirth": "MATCH",
           "address": "PARTIAL_MATCH",
           "phoneNumber": "PARTIAL_MATCH",
           "gender": "MATCH"
         }
     ]
  }
}

Romania 🇷🇴

Source

Input parameters

POST /sessions example

Official Voter Register (RO4)

Mandatory:

  • first name via person.firstName

  • last name via person.lastName

Optional:

  • date of birth via person.dateOfBirth

  • gender via person.gender

  • address via address.fullAddress

{
 "verification": {
   "person": {
     "firstName": "John",
     "lastName": "Smith",
     "dateOfBirth": "1990-01-01",
     "gender": "M"
   },
   "address": {
     "fullAddress": "123, Main Street, Your County, Anytown 12345"
   } 
}

Sample response payload

The following info can be found in decision webhook payload and GET /decision endpoint’s payload, in verifications.additionalVerifiedData object. Note that the payloads contain more parameters, to find info about them see the decision webhook and GET /decision endpoint’s documentation.

{...
  "additionalVerifiedData": {
     "validationResults": [
        {
           "registryName": "Romania - Official Voter Register (RO4)",
           "firstName": "MATCH",
           "lastName": "MATCH",
           "dateOfBirth": "PARTIAL_MATCH",
           "address": "PARTIAL_MATCH",
           "gender": "MATCH"
         }
     ]
  }
}

Spain 🇪🇸

Source

Input parameters

POST /sessions example

Census & Utility Services (ES2)

Mandatory:

  • first name via person.firstName

  • last name via person.lastName

Optional:

  • date of birth via person.dateOfBirth

  • phone number via person.phoneNumber

  • address via address.fullAddress

  • ID number (national ID) via document.number

{
 "verification": {
   "person": {
     "firstName": "John",
     "lastName": "Smith",
     "dateOfBirth": "1990-01-01",
     "phoneNumber": "888888888"
   },
   "document": {
     "number": "123456789"
   },
   "address": {
     "fullAddress": "123, Main Street, Your County, Anytown 12345"
   } 
}

Sample response payload

The following info can be found in decision webhook payload and GET /decision endpoint’s payload, in verifications.additionalVerifiedData object. Note that the payloads contain more parameters, to find info about them see the decision webhook and GET /decision endpoint’s documentation.

{...
  "additionalVerifiedData": {
     "validationResults": [
        {
           "registryName": "Spain - Census & Utility Services (ES2)",
           "firstName": "MATCH",
           "lastName": "MATCH",
           "dateOfBirth": "NO_DATA",
           "address": "PARTIAL_MATCH",
           "idNumber": "MATCH",
           "phoneNumber": "PARTIAL_MATCH"
         }
     ]
  }
}

Turkey 🇹🇷

Source

Input parameters

POST /sessions example

Official Voter Register (TR1)

Mandatory:

  • first name via person.firstName

  • last name via person.lastName

Optional:

  • date of birth via person.dateOfBirth

  • phone number via person.phoneNumber

  • gender via person.gender

  • address via address.fullAddress

  • ID number via document.number

{
 "verification": {
   "person": {
     "firstName": "John",
     "lastName": "Smith",
     "dateOfBirth": "1990-01-01",
     "phoneNumber": "8888888888",
     "gender": "M"
   },
   "document": {
     "number": "123456789"
   },
   "address": {
     "fullAddress": "Any State"
   } 
}

Sample response payload

The following info can be found in decision webhook payload and GET /decision endpoint’s payload, in verifications.additionalVerifiedData object. Note that the payloads contain more parameters, to find info about them see the decision webhook and GET /decision endpoint’s documentation.

{...
  "additionalVerifiedData": {
     "validationResults": [
        {
           "registryName": "Turkey - Official Voter Register (TR1)",
           "firstName": "MATCH",
           "lastName": "MATCH",
           "dateOfBirth": "MATCH",
           "address": "PARTIAL_MATCH",
           "idNumber": "MATCH",
           "phoneNumber": "PARTIAL_MATCH",
           "gender": "NO_DATA"
         }
     ]
  }
}

United Kingdom 🇬🇧

Source

Input parameters

POST /sessions example

Official Voter Register (GB2)

Mandatory:

  • first name via person.firstName

  • last name via person.lastName

Optional:

  • date of birth via person.dateOfBirth

  • phone number via person.phoneNumber

  • gender via person.gender

  • address via address.fullAddress

{
 "verification": {
   "person": {
     "firstName": "John",
     "lastName": "Smith",
     "dateOfBirth": "1990-01-01",
     "phoneNumber": "8888888888",
     "gender": "M"
   },
   "address": {
     "fullAddress": "123, Main Street, Your County, Anytown 12345"
   } 
}

Sample response payload

The following info can be found in decision webhook payload and GET /decision endpoint’s payload, in verifications.additionalVerifiedData object. Note that the payloads contain more parameters, to find info about them see the decision webhook and GET /decision endpoint’s documentation.

{...
  "additionalVerifiedData": {
     "validationResults": [
        {
           "registryName": "UK - Official Voter Register (GB2)",
           "firstName": "MATCH",
           "lastName": "MATCH",
           "dateOfBirth": "MATCH",
           "address": "PARTIAL_MATCH",
           "phoneNumber": "PARTIAL_MATCH",
           "gender": "MATCH"
         }
     ]
  }
}

APAC

Singapore 🇸🇬

Source

Input parameters

POST /sessions example

Sample response payload

The following info can be found in decision webhook payload and GET /decision endpoint’s payload, in verifications.additionalVerifiedData object. Note that the payloads contain more parameters, to find info about them see the decision webhook and GET /decision endpoint’s documentation.

"additionalVerifiedData": {
   "validationResults": [
      {
         "registryName": "Singapore - Utility Phone Register (SG1)",
         "firstName": "MATCH",
         "lastName": "MATCH",
         "dateOfBirth": "NO_INPUT",
         "address": "PARTIAL_MATCH",
         "phoneNumber": "MATCH",
         "gender": "NO_INPUT"
       }
   ]
},

Status and reason codes

For an approved session, see:

  • verification.code about verification session decision code, one of 9001, 9102, 9103, 9104, 9121.

  • verification.status about verification status, one of approved, declined, resubmission_requested, expired, abandoned.

If the Match Database Verification session was declined or resubmission_requested, you can find additional information by checking:

  1. verification.reason for the reason why the verification failed.

  2. verification.reasonCode for reason code of the failed verification and cross-reference it with Granular reason codes (table).

verification.status

verification.reasonCode

verification.reason

What does it mean?

declined

123

Unable to pass registry checks

The person could not be found in the database

declined

529

Unable to validate National Id data

The expected identification number could not be verified

declined

566

Registry provider error occurred while connecting to the registry

Technical error during database communication

The table above aims to list the most common reasons why you may see the decline or resubmission _requested reason for a Match Database Verification session. However, the session may be declined due to a reason that is not inherently related to this solution’s flow (e.g. uploaded document’s quality is low). In that case, to find info about the codes you are seeing, refer to:

Additional data

Best practices

  1. In API flow, ensure that initData is present, especially the mandatory fields.

  2. Ensure correct data formats to reduce the possibility of session going to resubmission_requested .

  3. Document image quality: ensure that end-user’s document image is of good quality. This will reduce the possibility of session going to resubmission_requested .

  4. Person’s ID number is always sent it in document.number parameter (not person.idNumber ).

  5. Error handling: implement proper error handling for all possible validation results.

  6. Session declined due to third-party provider issues: implement proper session handling flow when possibly legitimate end-user’s session is declined due to the third-party service provider having issues, as indicated by session code 566.

  7. Webhook security: secure your webhook endpoint and verify request signatures.

  8. User experience: provide clear feedback to users about validation results.

  9. Ensure backwards compatibility for webhooks and API connections.

FAQ

What are common use cases for Match Database Verification?

Match Database Verifications enables businesses to:

  • Validate identity data against official voter registers, civil registers, and commercial databases

  • Verify addresses using utility services, phone registers, and census data

  • Confirm identity for KYC/AML compliance without document collection

  • Reduce friction in user onboarding with faster, document-free verification

  • Enhance fraud detection by cross-referencing multiple data points

When should I prefer the standalone version and when the add-on to my IDV solution?

Standalone via API, using initData

This solution is fast, does not require document uploads, but you need to input data manually and no document authenticity verification is done.

Best suitable for: low risk use-cases, address changes, returning customers, periodic KYC updates.

Add-on to existing document or document+selfie IDV solution

This version provides higher assurance as the document authenticity is also validated, and document data capture is done automatically. This does require a document upload (API) or document capture (SDK) step, and takes slightly longer to process.

Best suitable for: new customer onboarding, high-risk transactions, compliance requirements.

Changelog

Date

Description

Dec 3, 2025

Documentation published