--- title: "Match Database Verifications | Veriff.com" slug: "match-database-verifications" description: "Validate end-user’s personal information against official regional databases aggregated by a third-party database aggregator." tags: ["Non-document Verification"] status: "update" updated: 2026-09-18T08:13:52Z published: 2026-09-18T08:13:52Z canonical: "devdocs.veriff.com/match-database-verifications" --- > ## Documentation Index > Fetch the complete documentation index at: https://devdocs.veriff.com/llms.txt > Use this file to discover all available pages before exploring further. # Match Database Verifications | 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**. > [!NOTE] > Contact your **solutions engineer** for info and configuration. --- ## Prerequisites - You have an [integration set up](/v1/docs/how-to-create-an-integration) with Veriff - The match database **check is configured** for that integration **by your Solutions Engineer** - You have configured the [decision webhook](/v1/docs/decision-webhook) to get responses from Veriff (see the how-to in webhooks’ [Set up webhooks](https://devdocs.veriff.com/docs/webhooks-guide#set-up-webhooks) section) - If using the **API**, you are ready to collect and **send** Veriff your **end-user’s data** > [!NOTE] > Irrespective of the country or the database, `firstName` **and** `lastName` **are always required**. --- ## 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: **initData** and **document data**. ### InitData This is **data that you provide** when creating a verification session, i.e. the parameters you specify in the [POST /sessions](https://devdocs.veriff.com/apidocs/v1sessions) 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` #### Document data 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. --- ## Flow overview ### Database flow Match Database Verifications follows a simple flow. **Step 1: you input end-user’s data** ([initData or document](/v1/docs/match-database-verifications#enduser-data-sources)) **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 > [!NOTE] > Contact your Solutions Engineer for more information about the match confidence scoring and fields comparing setup. ### Session flow > [!NOTE] > 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](https://devdocs.veriff.com/apidocs) 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). 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](/v1/docs/sdk-guide)) - 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 #### 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](https://devdocs.veriff.com/apidocs) how to find these) - Make sure to pass the mandatory `firstName` and `lastName` - You can pass other parameters in the session creation request 1. OPTIONAL: if you have decided to use also the document data source, send the end-user’s document images: - Use your image-capturing method, or prepare previously collected images - Upload the end-user's media via [POST /sessions/{sessionId}/media](https://devdocs.veriff.com/apidocs/v1sessionsidmedia-3) call - Specify the `image.context` as appropriate for the image (see [Context types (image, video)](/v1/docs/context-types-image-video-1) for more info about image context types) **Sample request payload** ```bash 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}](https://devdocs.veriff.com/apidocs/v1sessionsid-2) call **Sample request payload** ```bash 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. --- ## USA - Credit Database (US15) | Input parameters | POST /sessions example | | --- | --- | | 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` - social security or driver’s licence number via `document.number` | ```json { "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](https://devdocs.veriff.com/docs/decision-webhook) and [GET /decision endpoint’s](https://devdocs.veriff.com/apidocs/v1sessionsiddecision-1) documentation. ```json {...  "additionalVerifiedData": {     "validationResults": [        {           "registryName": "USA - Credit + US Identity Graph (US15)",           "firstName": "MATCH",           "lastName": "MATCH",           "dateOfBirth": "NO_DATA",           "address": "PARTIAL_MATCH",           "idNumber": "MATCH",           "phoneNumber": "PARTIAL_MATCH"         }     ]  } } ``` --- ## 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)](/v1/docs/granular-reason-codes). | `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: - [Granular reason codes (table)](https://devdocs.veriff.com/v1/docs/granular-reason-codes) - [Verification session status codes (table)](https://devdocs.veriff.com/v1/docs/verification-session-status-codes-table) - [Verification session decision codes (table)](https://devdocs.veriff.com/v1/docs/verification-session-decision-codes-table) --- ## 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**](/v1/docs/backwards-compatible-changes) 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 | | --- | --- | | Sep 18, 2026 | Page updated, US Credit Database (US15) info displayed | | Dec 12, 2025 | Broken links fixed | | Dec 11, 2025 | The initData matrix by countries in [Databases by regions](/v1/docs/match-database-verifications#databases-by-regions) updated | | Dec 3, 2025 | Documentation published | Veriff customer back-office, a dashboard where you can see your end-users' verification data. Depending on your setup, you may be required to access the environment via station.veriff.com or hub.veriff.com. Always **check your sign-up email** and make sure that you **log in via correct address**. A session during which the end-user is verified. It starts when a session is created, it can contain several attempts (i.e. steps of uploading media, sending additional data etc.) and it ends when a conclusive decision (“approved”, “declined”, “expired”/”abandoned”) is granted. Each verification session receives an unique ID, aka the **session ID**, which can be added to the API URL when making API requests. An environment created according to customer's needs to carry out, manage and observe verifications. You can find the list of your integrations in **Veriff Customer Portal** > **All** **Integrations** page (you need to be logged in). This where the end-user is directed to go through the verification flow, and it is **unique for each verification session**. It is a combination of the `base URL` and the `sessionToken`, created as soon as a verification session is created. You can find its value in the response payload of your POST /sessions call, as `verification.url`. The data that you send when you make an API request, or that you receive when you get a response.