--- title: "/v1/validate-registry" slug: "v1validate-registry" updated: 2026-04-24T06:52:13Z published: 2026-04-24T06:52:13Z --- > ## 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. # Validate national ID number Post/v1/validate-registry ### Validates a national ID number (e.g., Social Security Number) with the provided data #### When to use this endpoint - Use this endpoint to validate national ID numbers (such as Social Security Numbers) against official government databases without requiring document uploads or end-user interaction - Common use cases include: - Validating US Social Security Numbers (SSN) against national databases - Verifying person data matches government records - Performing registry-based identity checks for regulatory compliance - Quick identity validation without document capture #### How this endpoint works - When you call this endpoint: - A verification session is automatically created and submitted - The API response returns only the request status and basic session data - Validation results (person data) are sent via [decision webhook](https://devdocs.veriff.com/docs/decision-webhook) - Media upload is NOT used for registry verification #### Default vs sync-api versions - This is the **default /validate-registry** endpoint. It uses the standard API URL `https://example-base-url/v1/validate-registry` and delivers person data via webhook. - There is also a **sync-api /validate-registry** version that returns person data directly in the API response payload. - The sync-api version is not available by default - contact Veriff to enable it see its [API documentation](https://devdocs.veriff.com/apidocs/validate-registry-3) for more info. #### Required data combinations - To perform SSN validation, you must provide: - `idNumber` (SSN) - REQUIRED - `fullName` OR (`firstName` + `lastName`) - REQUIRED (one combination) - `dateOfBirth` OR `address` data - REQUIRED (one combination) - If providing `address` data, send EITHER: - `fullAddress` (full address as single string), OR - `street` + `houseNumber` + `postcode` (structured address components) - Click on the "Show example" button in the "Body parameters" section to see some example request payloads. #### Implementation notes - Validation results are sent via decision webhook - Optional fields `phoneNumber`, `vendorData`, and `endUserId` are strongly recommended for improved fraud prevention - Always ensure that you use the correct API URL to send requests. See the [API URL section](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#api-url) for more info - The order of parameters in the real API response can differ from the order you see in this documentation. This is expected and part of the [Backwards compatible changes](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#backwards-compatible-changes) requirements Header parametersX-AUTH-CLIENTstringRequired Your integration's API key (occasionally referred to as the "Token", "API public key" or "Publishable key"). Required for all API requests. You can find your API key in the Veriff Customer Portal > Settings > API keys. Exampleyour-api-public-key Content-TypestringRequired Must be application/json Valid values[ "application/json" ]Exampleapplication/json Body parametersfullName_with_dateOfBirth Validates using `idNumber` + `fullName` + `dateOfBirth`. Note: `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for improved fraud prevention. ```json { "verification": { "callback": "https://exampleURL.com/callback", "person": { "idNumber": "123456789", "fullName": "John Smith", "dateOfBirth": "1980-03-06", "phoneNumber": "+00 123 456 789" }, "vendorData": "11111111", "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f" } } ``` fullName_with_fullAddress Validates using `idNumber` + `fullName` + `fullAddress`. Note: `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for improved fraud prevention. ```json { "verification": { "callback": "https://exampleURL.com/callback", "person": { "idNumber": "123456789", "fullName": "John Smith", "phoneNumber": "+00 123 456 789" }, "address": { "fullAddress": "3, 123, Main Street, My County, Anytown, 12345" }, "vendorData": "11111111", "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f" } } ``` fullName_with_structured_address Validates using `idNumber` + `fullName` + structured `address` (`street` + `houseNumber` + `postcode`). Note: `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for improved fraud prevention. ```json { "verification": { "callback": "https://exampleURL.com/callback", "person": { "idNumber": "123456789", "fullName": "John Smith", "phoneNumber": "+00 123 456 789" }, "address": { "street": "Main Street", "houseNumber": "123", "postcode": "12345" }, "vendorData": "11111111", "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f" } } ``` firstName_lastName_with_dateOfBirth Validates using `idNumber` + `firstName` + `lastName` + `dateOfBirth`. Note: `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for improved fraud prevention. ```json { "verification": { "callback": "https://exampleURL.com/callback", "person": { "idNumber": "123456789", "firstName": "John", "lastName": "Smith", "dateOfBirth": "1980-03-06", "phoneNumber": "+00 123 456 789" }, "vendorData": "11111111", "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f" } } ``` firstName_lastName_with_fullAddress Validates using `idNumber` + `firstName` + `lastName` + `fullAddress`. Note: `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for improved fraud prevention. ```json { "verification": { "callback": "https://exampleURL.com/callback", "person": { "idNumber": "123456789", "firstName": "John", "lastName": "Smith", "phoneNumber": "+00 123 456 789" }, "address": { "fullAddress": "3, 123, Main Street, My County, Anytown, 12345" }, "vendorData": "11111111", "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f" } } ``` firstName_lastName_with_structured_address Validates using `idNumber` + `firstName` + `lastName` + structured `address` (`street` + `houseNumber` + `postcode`). Note: `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for improved fraud prevention. ```json { "verification": { "callback": "https://exampleURL.com/callback", "person": { "idNumber": "123456789", "firstName": "John", "lastName": "Smith", "phoneNumber": "+00 123 456 789" }, "address": { "street": "Main Street", "houseNumber": "123", "postcode": "12345" }, "vendorData": "11111111", "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f" } } ``` minimal_required_only Minimal payload with only required fields. Warning: Without optional fraud prevention fields (`phoneNumber`, `vendorData`, `endUserId`), fraud detection may be limited. ```json { "verification": { "person": { "idNumber": "123456789", "fullName": "John Smith", "dateOfBirth": "1980-03-06" } } } ``` Expand Allobject verificationobject Required Verification object callbackstring The callback URL to where the end-user is redirected after the verification session is completed. Default is visible in the Veriff Customer Portal > Settings. Changing the value in this request body will overwrite the default callback URL, but it will not change the callback URL that is visible in the Customer Portal. Examplehttps://exampleURL.com/callback personobject Required Data about the person being verified. idNumberstring Required Person's national ID number (SSN). Example123456789 firstNamestring Person's first name. Required if `fullName` is not provided. ExampleJohn lastNamestring Person's last name. Required if `fullName` is not provided. ExampleSmith fullNamestring Person's full name. Required if `firstName` + `lastName` is not provided. ExampleJohn Smith phoneNumberstring Person's phone number, can include numbers, whitespaces and the "+" sign in front. Example+00 123 456 789 dateOfBirthstring (date) Person's date of birth in YYYY-MM-DD format. Required if `address` is not provided. Example1980-03-06 addressobject Data about the address of the person being verified. fullAddressstring Full address. Required if `street` + `houseNumber` + `postcode` are not provided. Example3, 123, Main Street, My County, Anytown, 12345 streetstring Street name. Required if `fullAddress` is not provided. ExampleMain Street houseNumberstring House number. Required if `fullAddress` is not provided. Example123 postcodestring Postal code. Required if `fullAddress` is not provided. Example12345 citystring Any human settlement, including cities, towns, villages, hamlets, localities, etc. ExampleAnyCity statestring A first-level administrative division. For example, Scotland, Northern Ireland, Wales, and England in the UK are mapped to "state" as well (convention used in OSM, GeoPlanet, etc.) ExampleAnyState unitstring An apartment, unit, office, lot, or other secondary unit designator. Example3 vendorDatastring The unique identifier that you created for your end-user. It can be max 1,000 characters long and contain only non-semantic data that can not be resolved or used outside your systems or environments. Veriff returns it unmodified in webhooks and API response payloads, or as `null` if not provided. Example11111111 endUserIdstring (uuid) End-user-specific UUID created by the customer to identify the end-user. Returned unmodified in webhooks and public API calls, or as `null` if not provided. Examplefa820aba-019f-455a-ae81-cfca8075bc3f Responses200 Session created successfully HeadersX-AUTH-CLIENTstringAPI key echoed back in response. X-HMAC-SIGNATUREstringResponse body signed with the shared secret key. Required to authenticate the response sender. Content-TypestringResponse content type.Exampleapplication/json session_created Registry validation session created successfully. The session will be automatically submitted for validation, and results will be sent via decision webhook. ```json { "status": "success", "verification": { "id": "f8b2c4d6-1a3e-4f9b-8c2d-5e7a9b1c3d4f", "vendorData": "1234567890", "status": "created", "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiZjhiMmM0ZDYtMWEzZS00ZjliLThjMmQtNWU3YTliMWMzZDRmIn0..." } } ``` Expand Allobject statusstring API request status. Examplesuccess verificationobject Verification object. idstring UUID v4 which identifies the verification session. Example123e4567-e89b-12d3-a456-426614174000 vendorDatastring | null The unique identifier that you created for your end-user. It can be max 1,000 characters long and contain only non-semantic data that can not be resolved or used outside your systems or environments. Veriff returns it unmodified in webhooks and API response payloads, or as `null` if not provided. Example1234567890 statusstring Verification session status. Examplecreated sessionTokenstring Session-specific token of the verification. ExampleeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... 400 Bad request - missing or invalid required fields HeadersX-AUTH-CLIENTstringAPI key echoed back in response. X-HMAC-SIGNATUREstringResponse body signed with the shared secret key. Required to authenticate the response sender. Content-TypestringResponse content type.Valid values[ "application/json" ] missing_name_data Missing name data - Required field `fullName` or (`firstName` + `lastName`) not provided ```json { "status": "failed", "code": "1102", "message": "Request person is missing required field fullName or (firstName + lastName)" } ``` missing_dateOfBirth_or_address Missing date of birth OR address - Required field `dateOfBirth` or `address` not provided ```json { "status": "failed", "code": "1102", "message": "Request is missing required field 'dateOfBirth' or 'address'" } ``` missing_address_components Missing address components - Required field `fullAddress` or (`street` + `houseNumber` + `postcode`) not provided ```json { "status": "failed", "code": "1102", "message": "Request address is missing required field fullAddress or (street + houseNumber + postcode)" } ``` missing_idNumber Missing ID number - Required field `idNumber` not provided ```json { "status": "failed", "code": "1102", "message": "Request is missing required field idNumber" } ``` object statusstring Valid values[ "fail" ]Examplefail codestring Example1101 messagestring ExampleValidation failed 401 Unauthorized - HMAC signature validation failed HeadersX-AUTH-CLIENTstringAPI key echoed back in response. X-HMAC-SIGNATUREstringResponse body signed with the shared secret key. Required to authenticate the response sender. Content-TypestringResponse content type.Valid values[ "application/json" ] ```json { "status": "failed", "code": "1812", "message": "Signature a1b2c3d4e5f6 is not a valid SHA256 hash" } ``` object statusstring Valid values[ "fail" ]Examplefail codestring Example1101 messagestring ExampleMandatory X-AUTH-CLIENT header containing the API key is missing from the request. Changelog **Changelog** | Date | Description | | --- | --- | | Apr 24, 2026 | Headers capitalization harmonized | | Mar 9, 2026 | Documentation updated: parent categories rearranged, intro section expanded, request and response examples added | | Oct 2, 2025 | `vrf-` headers removed from response headers | | Sep 16, 2025 | `vrf-integration-id` header removed from request headers | | Aug 6, 2025 | Response headers added | | Jul 11, 2025 | Endpoint description updated to clarify the difference between /v1/validate-registry and sync-api/validate registry endpoints | | Apr 30, 2025 | New header `vrf-integration-id` added to support the new Flexible API keys solution | | Mar 12, 2025 | Documentation published |