--- title: "Social Security Number Verification" slug: "us-database-verification" description: "Streamline identity verification in US with flexible checks on SSN, driver's licenses, and more, enhancing fraud detection." tags: ["Drivers' Licence validation", "SSN validation", "US Database Verification"] updated: 2026-05-25T10:38:08Z published: 2026-05-25T10:38:08Z --- > ## 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. # Social Security Number Verification | Available via API | Available via SDK | Needs configuration on Veriff's side | Needs a separate integration | Needs a separate webhook | | --- | --- | --- | --- | --- | | ✅ | ✅ | ✅ | ✅ | ❌ | 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. > [!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 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** --- ## End-user data sources The checks are performed on end-user’s data, which can come from two data sources: **document data** and **initData**. > [!NOTE] > 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. > [!NOTE] > Light KYC can be done using only the [document data source](/v1/docs/us-database-verification#document-data) (data is extracted from document images) or only the [initData source](/v1/docs/us-database-verification#initdata) (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. SDKAPI 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) 1. You can pass the `firstName`, `lastName`, `dateOfBirth`, `phoneNumber`, `fullAddress` 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 1. Send the end-user through the verification flow to capture the images (using the preferred [Veriff SDK](/v1/docs/sdk-guide)) 2. 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](/v1/docs/decision-webhook) 1. Generate a verification session using the a `API keys` and the `baseURL` of your integration (see the [API Documentation and API Reference](https://devdocs.veriff.com/apidocs)[↗] how to find these) 1. Make sure to pass the mandatory `firstName` and `lastName` 2. You can pass the optional `dateOfBirth`, `phoneNumber` and `fullAddress` info 2. If you have decided to use also the document data source, send the end-user’s document images: 1. Use your image-capturing method, or prepare previously collected images 2. Upload the end-user's media via [POST /sessions/{sessionId}/media](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsidmedia-3)[↗] call 3. 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) 3. Patch session status to `submitted` status using [PATCH /sessions/{sessionId}](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsid-2)[↗] call 4. If you sent images, end-user’s data is extracted 5. Database checks are run 6. Check the decision data and/or session related info from the [decision webhook](/v1/docs/decision-webhook) and/or query the data from the [GET sessions/{sessionId}/decision](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsiddecision-1)[↗] endpoint #### POST /sessions payload With initData ```curl 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 SDKAPI ![Flowchart illustrating user verification process involving end-user, customer, and Veriff.](https://cdn.document360.io/5c26138b-b1e9-404e-a2e4-c83a49245be7/Images/Documentation/US%20DB_LightKYC_SDKs.png) ![Flowchart illustrating the verification process involving end-user, customer, and Veriff.](https://cdn.document360.io/5c26138b-b1e9-404e-a2e4-c83a49245be7/Images/Documentation/US%20DB_LightKYC_diagram_API.png) ### 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) SDKAPI 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) 2. Capture end-user’s document and selfie images with Veriff’s SDKs 1. Send the end-user through the verification flow to capture the images (using the preferred [Veriff SDK](/v1/docs/sdk-guide)) 2. 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](/v1/docs/decision-webhook) 1. Generate a verification session using the a `API keys` and the `baseURL` of your integration (see the [API Documentation and API Reference](https://devdocs.veriff.com/apidocs)[↗] how to find these) 2. Use your image-capturing method, or prepare previously collected end-user’s images 3. Upload the end-user's media via [POST /sessions/{sessionId}/media](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsidmedia-3)[↗] call 1. 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) 4. Patch session status to `submitted` status using [PATCH /sessions/{sessionId}](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsid-2)[↗] call 5. End-user’s data is extracted 6. Database checks are run 7. Check the decision data and/or session related info from the [decision webhook](/v1/docs/decision-webhook) and/or query the data from the [GET sessions/{sessionId}/decision](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsiddecision-1)[↗] endpoint *→ See the*[*Create verification session*](/v1/docs/how-to-generate-sessions-manually)*article for examples of minimal POST /session payloads for SDK and API* #### Flow diagrams SDKAPI ![Flowchart illustrating user verification process involving end-user, customer, and Veriff.](https://cdn.document360.io/5c26138b-b1e9-404e-a2e4-c83a49245be7/Images/Documentation/US_DB_DriversLicense_diagram_SDK.png) ![Flowchart illustrating the verification process involving end-user, customer, and Veriff.](https://cdn.document360.io/5c26138b-b1e9-404e-a2e4-c83a49245be7/Images/Documentation/US%20DB_DriversLicence_diagram_API.png) ### 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] > 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) SDKAPI 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) 1. Make sure to send `document.number` parameter 2. Capture end-user’s document and selfie images with Veriff’s SDKs 1. Send the end-user through the verification flow to capture the images (using the preferred [Veriff SDK](/v1/docs/sdk-guide)) 2. 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](/v1/docs/decision-webhook) 1. Generate a verification session using the a `API keys` and the `baseURL` of your integration (see the [API Documentation and API Reference](https://devdocs.veriff.com/apidocs)[↗] how to find these) 1. Make sure to pass `document.number`, `firstName` and `lastName` parameters 2. You can define `dateOfBirth` as optional data 2. If you have decided to use also the document data source, send the end-user’s document images: 1. Use your image-capturing method, or prepare previously collected end-user’s images 2. Upload the end-user's media via [POST /sessions/{sessionId}/media](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsidmedia-3)[↗] call 3. 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) 3. Patch session status to `submitted` status using [PATCH /sessions/{sessionId}](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsid-2)[↗] call 4. If you sent images, end-user’s data is extracted 5. Database checks are run 6. Check the decision data and/or session related info from the [decision webhook](/v1/docs/decision-webhook) and/or query the data from the [GET sessions/{sessionId}/decision](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsiddecision-1)[↗] endpoint #### POST /sessions payload With mandatory and optional initData. ```Custom 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 SDKAPI ![Flowchart illustrating the verification process for end-users, customers, and Veriff.](https://cdn.document360.io/5c26138b-b1e9-404e-a2e4-c83a49245be7/Images/Documentation/US%20DB_SSN_SDKs.png) ![Flowchart illustrating the user verification process involving end-user, customer, and Veriff.](https://cdn.document360.io/5c26138b-b1e9-404e-a2e4-c83a49245be7/Images/Documentation/US%20DB_SSN_diagram_API.png) --- ## 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 > [!NOTE] > 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](/v1/docs/decision-webhook)documentation. #### Sample request ```json {  "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 | null`* 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 > [!NOTE] > 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](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsiddecision-1)[↗] documentation. #### Sample request ```json {  "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. → *See*[*Review verification in Veriff Customer Portal*](/v1/docs/how-to-review-verification-in-veriff-customer-portal)*about how to view the session info in the Veriff Customer portal* --- ## Changelog | Date | Description | | --- | --- | | May 25, 2026 | Article title and intro text updated Availability matrix added | | Jul 18, 2025 | `decisionTime` updated in webhook section, to indicate that it can also be `null` | | Jun 6, 2025 | Heading “Article versioning” changed to “Changelog” | | Apr 12, 2025 | Documentation published | 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. 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**. ## Related - [Decision webhook](/decision-webhook.md) - [Document-only IDV](/document-only-idv.md) - [Document + Selfie IDV](/document-selfie-idv.md) - [Intro to the SDK](/quick-guide-of-idv-using-the-sdks-1.md) - [Intro to the API](/quick-guide-of-idv-using-the-api.md) - [Create verification session](/how-to-generate-sessions-manually.md)