> ## 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 registry > ### Validates a national ID number (for example a Social Security Number (SSN)) with the provided data #### When to use this endpoint - Use this endpoint when your integration needs the **registry validation result in the same request**, without setting up or waiting on a webhook. - 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. - **This API response returns the validation result (person data) directly in the payload**. - Media upload is not used for registry verification. #### Default vs sync-api versions - This is the sync-api `/validate-registry` version. It is served from the separate `https://sync-api.veriff.me` base URL and returns the validation result directly in the API response payload. - Not available by default. Contact your Solutions Engineer to have this endpoint enabled for your integration. - There is also a default [`/v1/validate-registry` endpoint](https://devdocs.veriff.com/apidocs/v1validate-registry), which uses the standard public API base URL and delivers the result through a decision webhook instead. #### Required data combinations - `idNumber` - `fullName` OR `firstName` + `lastName` - `dateOfBirth` OR `address` data - If `address` data is provided, send EITHER the `fullAddress` value OR the `street` + `houseNumber` + `postcode` values #### Implementation notes - Optional fields `phoneNumber`, `vendorData`, and `endUserId` are strongly recommended for improved fraud prevention. - Always 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 shown 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. ## OpenAPI ````json POST /v1/validate-registry { "openapi": "3.0.0", "info": { "title": "Public Sync API", "version": "1.0.0" }, "servers": [ { "url": "https://sync-api.veriff.me" } ], "paths": { "/v1/validate-registry": { "post": { "summary": "Validate registry", "description": "### Validates a national ID number (for example a Social Security Number (SSN)) with the provided data\n\n#### When to use this endpoint\n\n- Use this endpoint when your integration needs the **registry validation result in the same request**,\n without setting up or waiting on a webhook.\n- Common use cases include:\n - Validating US Social Security Numbers (SSN) against national databases.\n - Verifying person data matches government records.\n - Performing registry-based identity checks for regulatory compliance.\n - Quick identity validation without document capture.\n\n#### How this endpoint works\n\n- When you call this endpoint:\n - A verification session is automatically created and submitted.\n - **This API response returns the validation result (person data) directly in the payload**.\n - Media upload is not used for registry verification.\n\n#### Default vs sync-api versions\n\n- This is the sync-api `/validate-registry` version. It is served from the separate\n `https://sync-api.veriff.me` base URL and returns the validation result directly in the API\n response payload.\n- Not available by default. Contact your Solutions Engineer to have this endpoint enabled for your\n integration.\n- There is also a default [`/v1/validate-registry` endpoint](https://devdocs.veriff.com/apidocs/v1validate-registry),\n which uses the standard public API base URL and delivers the result through a decision webhook\n instead.\n\n#### Required data combinations\n\n- `idNumber`\n- `fullName` OR `firstName` + `lastName`\n- `dateOfBirth` OR `address` data\n- If `address` data is provided, send EITHER the `fullAddress` value OR the `street` + `houseNumber`\n + `postcode` values\n\n#### Implementation notes\n\n- Optional fields `phoneNumber`, `vendorData`, and `endUserId` are strongly recommended for improved\n fraud prevention.\n- Always use the correct API URL to send requests. See the\n [API URL section](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#api-url) for more info.\n- The order of parameters in the real API response can differ from the order shown in this\n documentation. This is expected and part of the\n [Backwards compatible changes](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#backwards-compatible-changes)\n requirements.\n", "parameters": [ { "name": "X-AUTH-CLIENT", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your integration's API key. Required to identify the request sender. Occasionally referred to as the\n\"API token\".\n" }, { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your integration's API key, required to access this endpoint. This is a separate credential\nfrom X-AUTH-CLIENT, issued per integration.\n" }, { "name": "X-HMAC-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Request body signed with the shared secret key. Validated only when present." }, { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "verification" ], "properties": { "verification": { "type": "object", "description": "Verification object.", "required": [ "person" ], "properties": { "callback": { "type": "string", "description": "The callback URL to where the end-user is redirected after the verification session is completed.\nDefault is visible in the Veriff Customer Portal > Settings. Changing the value in this request body\nwill overwrite the default callback URL, but it will not change the callback URL that is visible in\nthe Customer Portal.\n" }, "person": { "type": "object", "description": "Data about the person being verified.", "required": [ "idNumber" ], "properties": { "idNumber": { "type": "string", "description": "Person's national ID number (SSN).", "example": "123456789" }, "firstName": { "type": "string", "description": "Person's first name. Required if `fullName` is not provided.\n", "example": "John" }, "lastName": { "type": "string", "description": "Person's last name. Required if `fullName` is not provided.", "example": "Smith" }, "fullName": { "type": "string", "description": "Person's full name. Required if `firstName` + `lastName` is not provided.\n" }, "phoneNumber": { "type": "string", "description": "Person's phone number, can include numbers, whitespaces and the \"+\" sign in front.\n", "example": "+00 123 456 789" }, "dateOfBirth": { "type": "string", "format": "date", "description": "Person's date of birth, in YYYY-MM-DD format. Required if `address` is not provided.\n", "example": "1980-03-06" } } }, "address": { "type": "object", "description": "Data about the address of the person being verified.", "properties": { "fullAddress": { "type": "string", "description": "Full address. Required if `street` + `houseNumber` + `postcode` are not provided.\n", "example": "3, 123, Main Street, My County, Anytown, 12345" }, "street": { "type": "string", "description": "Street name. Required if `fullAddress` is not provided.", "example": "Main Street" }, "houseNumber": { "type": "string", "description": "House number. Required if `fullAddress` is not provided.", "example": "123" }, "postcode": { "type": "string", "description": "Postal code. Required if `fullAddress` is not provided.", "example": "12345" }, "city": { "type": "string", "description": "Any human settlement, including cities, towns, villages, hamlets, localities, etc.\n", "example": "AnyCity" }, "state": { "type": "string", "description": "A first-level administrative division. For example, Scotland, Northern Ireland, Wales, and England\nin the UK are mapped to \"state\" as well (convention used in OSM, GeoPlanet, etc.).\n", "example": "AnyState" }, "unit": { "type": "string", "description": "An apartment, unit, office, lot, or other secondary unit designator.\n", "example": "3" } } }, "vendorData": { "type": "string", "description": "The unique identifier that you created for your end-user. It can be max 1,000 characters long and\ncontain only non-semantic data that can not be resolved or used outside your systems or\nenvironments. Veriff returns it unmodified in webhooks and API response payloads, or as `null` if\nnot provided.\n", "example": "11111111" }, "endUserId": { "type": "string", "description": "End-user-specific UUID created by the customer to identify the end-user. Returned unmodified in\nwebhooks and public API calls, or as `null` if not provided.\n", "example": "fa820aba-019f-455a-ae81-cfca8075bc3f" } } } } }, "examples": { "fullName_with_dateOfBirth": { "description": "`idNumber` + `fullName` + `dateOfBirth`.\n\nNote that `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly\nrecommended for improved fraud prevention.\n", "value": { "verification": { "callback": "https://example.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": { "description": "`idNumber` + `fullName` + `fullAddress`.\n\nNote that `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly\nrecommended for improved fraud prevention.\n", "value": { "verification": { "callback": "https://example.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": { "description": "`idNumber` + `fullName` + structured `address` (`street` + `houseNumber` + `postcode`).\n\nNote that `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly\nrecommended for improved fraud prevention.\n", "value": { "verification": { "callback": "https://example.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": { "description": "`idNumber` + `firstName` + `lastName` + `dateOfBirth`.\n\nNote that `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly\nrecommended for improved fraud prevention.\n", "value": { "verification": { "callback": "https://example.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": { "description": "`idNumber` + `firstName` + `lastName` + `fullAddress`.\n\nNote that `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly\nrecommended for improved fraud prevention.\n", "value": { "verification": { "callback": "https://example.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": { "description": "`idNumber` + `firstName` + `lastName` + structured `address` (`street` + `houseNumber` + `postcode`).\n\nNote that `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly\nrecommended for improved fraud prevention.\n", "value": { "verification": { "callback": "https://example.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" } } } } } } }, "responses": { "200": { "description": "Successful response", "headers": { "X-AUTH-CLIENT": { "description": "Your integration's API key. Required to identify the response sender. Occasionally referred to as\nthe \"API token\".\n", "schema": { "type": "string" } }, "X-API-KEY": { "description": "Your integration's API key.", "schema": { "type": "string" } }, "X-HMAC-SIGNATURE": { "description": "Response body signed with the shared secret key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the response.", "example": "success" }, "verification": { "type": "object", "nullable": true, "description": "Verification request decision object. `null` if decision is not available yet.\n", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID v4 which identifies the verification session.", "example": "09551b48-4d7c-4a30-8437-5301223953fa" }, "code": { "type": "integer", "enum": [ 9001, 9102, 9103, 9104, 9121 ], "description": "Verification response code.", "example": 9001 }, "status": { "type": "string", "description": "Verification session status.", "enum": [ "approved", "declined", "resubmission_requested", "expired", "abandoned", "review" ], "example": "approved" }, "person": { "type": "object", "description": "Verified person.", "properties": { "firstName": { "type": "string", "nullable": true, "description": "Person's first name.", "example": "JOHN" }, "lastName": { "type": "string", "nullable": true, "description": "Person's last name.", "example": "SMITH" }, "idNumber": { "type": "string", "nullable": true, "description": "National identification number.", "example": "123456789" }, "dateOfBirth": { "type": "string", "format": "date", "nullable": true, "description": "Person's date of birth, in YYYY-MM-DD format.", "example": "1980-03-06" }, "yearOfBirth": { "type": "string", "nullable": true, "description": "Person's year of birth, in YYYY format.", "example": "1980" }, "placeOfBirth": { "type": "string", "nullable": true, "description": "Person's place of birth.", "example": "ANYTOWN" }, "addresses": { "type": "array", "nullable": true, "description": "Address data from the document as an array of strings.", "items": { "type": "object", "properties": { "fullAddress": { "type": "string", "nullable": true, "description": "Address as a single string.", "example": "3, 123, Main Street, My County, Anytown, 12345" } } } } } }, "reason": { "type": "string", "nullable": true, "description": "Reason of failed verification. `null` when not applicable.\n" }, "reasonCode": { "type": "integer", "nullable": true, "description": "Reason code of failed verification. `null` when not applicable.\n" }, "comments": { "type": "array", "deprecated": true, "description": "Always returns an empty array.", "items": { "type": "string" }, "example": [] }, "document": { "type": "object", "description": "Verified document.", "properties": { "type": { "type": "string", "nullable": true, "description": "Document type. Always returns `null`." }, "number": { "type": "string", "nullable": true, "description": "Document number. Always returns `null`." }, "country": { "type": "string", "nullable": true, "description": "ISO-2 document country. Always returns `null`." }, "validFrom": { "type": "string", "nullable": true, "description": "Document valid-from date. Always returns `null`." }, "validUntil": { "type": "string", "nullable": true, "description": "Document valid-until date. Always returns `null`." } } }, "vendorData": { "type": "string", "nullable": true, "description": "Unique identifier created by the customer to identify the end-user. Returned unmodified in webhooks\nand public API calls, or as `null` if not provided.\n" }, "endUserId": { "type": "string", "nullable": true, "description": "End-user-specific UUID created by the customer to identify the end-user. Returned unmodified in\nwebhooks and public API calls, or as `null` if not provided.\n", "example": "fa820aba-019f-455a-ae81-cfca8075bc3f" }, "decisionTime": { "type": "string", "format": "date-time", "description": "Timestamp of the decision. Combined ISO 8601 date and time in UTC, ending in Z. Format:\nYYYY-MM-DDTHH:MM:SS.sssZ.\n", "example": "2023-11-06T07:18:36.916Z" }, "acceptanceTime": { "type": "string", "format": "date-time", "description": "Timestamp of the session generation. Combined ISO 8601 date and time in UTC, ending in Z. Format:\nYYYY-MM-DDTHH:MM:SS.sssZ.\n", "example": "2023-11-06T07:15:27Z" }, "additionalVerifiedData": { "type": "object", "description": "Data which has been optionally verified for the session.", "properties": { "failedValidation": { "type": "string", "nullable": true, "description": "Message for the failed validation." } } } } }, "technicalData": { "type": "object", "description": "Technical data object.", "properties": { "ip": { "type": "string", "nullable": true, "description": "IP of the device from which the verification was made. `null` when not available.\n" } } } } }, "example": { "status": "success", "verification": { "id": "09551b48-4d7c-4a30-8437-5301223953fa", "code": 9001, "status": "approved", "person": { "firstName": "JOHN", "lastName": "SMITH", "idNumber": "123456789", "dateOfBirth": "1980-03-06", "yearOfBirth": "1980", "placeOfBirth": "ANYTOWN", "addresses": [ { "fullAddress": "3, 123, Main Street, My County, Anytown, 12345" } ] }, "reason": null, "reasonCode": null, "comments": [], "document": { "type": null, "number": null, "country": null, "validFrom": null, "validUntil": null }, "vendorData": null, "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f", "decisionTime": "2023-11-06T07:18:36.916Z", "acceptanceTime": "2023-11-06T07:15:27Z", "additionalVerifiedData": { "failedValidation": null } }, "technicalData": { "ip": null } } } } }, "400": { "description": "Bad request - missing or invalid required fields.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail" ], "description": "Status of the request.", "example": "fail" }, "message": { "type": "string", "description": "Explanation of why the request failed." }, "code": { "type": "integer", "description": "Error code.", "example": 1102 } } }, "examples": { "verification_object_missing": { "description": "The `verification` object is missing or empty.", "value": { "status": "fail", "message": "Bad Request", "code": 1102 } }, "name_data_missing": { "description": "Required field `fullName` or (`firstName` + `lastName`) not provided.\n", "value": { "status": "fail", "message": "Request person is missing required field fullName or (firstName + lastName)", "code": 1102 } }, "dateOfBirth_or_address_missing": { "description": "Required field `dateOfBirth` or `address` not provided.", "value": { "status": "fail", "message": "Request is missing required field dateOfBirth or address", "code": 1102 } }, "address_data_missing": { "description": "Required field `fullAddress` or (`street` + `houseNumber`) not provided. Note: although the message\nalso names `postcode`, `postcode` is not actually required by this check.\n", "value": { "status": "fail", "message": "Request address is missing required field fullAddress or (street + houseNumber + postcode)", "code": 1102 } }, "idNumber_missing": { "description": "Required field `idNumber` not provided.", "value": { "status": "fail", "message": "Request is missing required field idNumber", "code": 1102 } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail" ], "description": "Status of the request.", "example": "fail" }, "message": { "type": "string", "description": "Explanation of why the request failed." }, "code": { "type": "integer", "description": "Error code." } } }, "examples": { "auth_client_missing": { "description": "The X-AUTH-CLIENT header was not provided.", "value": { "status": "fail", "message": "Unauthorized", "code": 1102 } }, "invalid_hmac_signature": { "description": "X-HMAC-SIGNATURE validation failed.", "value": { "status": "fail", "message": "Signature {invalid-hmac-signature value} is not a valid SHA256 hash.", "code": 1812 } } } } } }, "408": { "description": "The request timed out while waiting for a decision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message.", "example": "Request has timed out" } } } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message." } } } } } } }, "x-d360-narrative-responses": "



Changelog

Date

Description

Nov 10, 2026

Some layout and formatting updates, no new info added

Jan 8, 2026

Request and response payload examples added

Oct 2, 2025

vrf- headers removed from response

Sep 17, 2025

vrf-auth-client and vrf-hmac-signature headers removed from response

Sep 16, 2025

vrf-integration-id header removed from request
Header names changed to lower case

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 endpoint

May 29, 2025

Minor updates to format

Apr 30, 2025

New header vrf-integration-id added to support the Flexible API keys solution

Apr 3, 2025

\"Required\" tags removed from x-hmac-signature and content-type headers

Mar 12, 2025

Documentation published

" } } } } ````