--- title: "Validate registry (sync-api)" slug: "validate-registry-3" description: "Validate national ID numbers with our API. Data about the session is sent in API response." updated: 2026-01-08T14:13:28Z published: 2026-01-08T14:13:28Z --- > ## 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 Post/v1/validate-registry **Validates a national ID number (e.g. social security number (SSN)) with the provided data** You will need a separate integration to do this verification, ask your Solutions Engineer to set it up.**** A verification session will be automatically created and submitted. After that, the validation result is sent in API response payload. **Media upload** is **not used** for registry verification. In order to perform a social security number (SSN) validation the following fields **must be provided**: - `idNumber` - `fullname` OR `firstName` + `lastName` - `dateofBirth` OR `address` data - If `address` data is provided, then send EITHER `fullAddress` value OR the `street` + `houseNumber` + `postcode` values **Additional info** This is one of the two endpoints used to to SSN validation, hereinafter “sync-api /validate-registry”. **This endpoint is not available by default**! The **default endpoint for SSN validation is**[**POST /v1/validate-registry**](https://devdocs.veriff.com/apidocs/v1validate-registry) (hereinafter “default /validate-registry"). The difference between the default /validate-registry and sync-api /validate-registry is that default /validate-registry returns the data about person and/or document via webhook, but sync-api /validate-registry returns the data inside the API response payload. If you need to use the “sync-api /validate-registry” endpoint, contact your Solutions Engineer or Veriff Customer Support, who can help set it up for you. When using this endpoint, make sure to use the API URL //sync-api.veriff.me/v1/validate-registry. See the [API FAQ section](https://devdocs.veriff.com/apidocs/api-faq#what-is-the-difference-between-post-v1validateregistry-and-post-syncapiv1validateregistry) for more info. Note: 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. Header parametersx-auth-clientstringRequired Your integration's API key. Required to identify the request sender. Occasionally referred to as the "API token". x-api-keystringRequired Your integration's API key. x-hmac-signaturestring Request body signed with the shared secret key. Required to authenticate the request sender. content-typestringExampleapplication/json Body parametersfullName_with_dateOfBirth `idNumber` + `fullName` + `dateOfBirth`. Note that `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for improved fraud prevention. ```json { "verification": { "callback": "https://example.com/callback", "person": { "idNumber": 123456789, "fullName": "John Smith", "dateOfBirth": "1980-03-06T00:00:00Z", "phoneNumber": "+00 123 456 789" }, "vendorData": 11111111, "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f" } } ``` fullName_with_fullAddress `idNumber` + `fullName` + `fullAddress`. Note that `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for improved fraud prevention. ```json { "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 `idNumber` + `fullName` + structured `address` (`street` + `houseNumber` + `postcode`). Note that `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for improved fraud prevention. ```json { "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 `idNumber` + `firstName` + `lastName` + `dateOfBirth`. Note that `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for improved fraud prevention. ```json { "verification": { "callback": "https://example.com/callback", "person": { "idNumber": 123456789, "firstName": "John", "lastName": "Smith", "dateOfBirth": "1980-03-06T00:00:00Z", "phoneNumber": "+00 123 456 789" }, "vendorData": 11111111, "endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f" } } ``` firstName_lastName_with_fullAddress `idNumber` + `firstName` + `lastName` + `fullAddress`. Note that `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for improved fraud prevention. ```json { "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 `idNumber` + `firstName` + `lastName` + structured `address` (`street` + `houseNumber` + `postcode`). Note that `phoneNumber`, `vendorData`, and `endUserId` are optional but strongly recommended for improved fraud prevention. ```json { "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" } } ``` 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. personobject Required Data about the person being verified idNumberstring 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 phoneNumberstring Person's phone number, can include numbers, whitespaces and the "+" sign in front Example+00 123 456 789 dateOfBirthstring (YYYY-MM-DD) Person's date of birth. Required if `address` is not provided Example1980-03-06 addressobject Required 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 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 Successful response Headersx-auth-clientstringYour integration's API key. Required to identify the response sender. Occasionally referred to as the "API token". x-api-keystringYour integration's API key. x-hmac-signaturestringResponse body signed with the shared secret key. Required to authenticate the response sender. ```json { "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 } } ``` Expand Allobject statusstring Status of the response Examplesuccess verificationobject Verification request decision object. `null` if decision is not available yet idstring (uuid) UUID v4 which identifies the verification session Example09551b48-4d7c-4a30-8437-5301223953fa codeinteger Verification response code Valid values[ 9001, 9102, 9103, 9104, 9121 ]Example9001 statusstring Verification session status Valid values[ "approved", "declined", "resubmission_requested", "abandoned", "expired" ]Exampleapproved personobject Verified person firstNamestring | null Person's first name ExampleJOHN lastNamestring | null Person's last name ExampleSMITH idNumberstring | null National identification number Example123456789 dateOfBirthstring | null Person's date of birth. YYYY-MM-DD Example1980-03-06 yearOfBirthstring | null Person's year of birth. YYYY Example1980 placeOfBirthstring | null Person's place of birth ExampleANYTOWN addresses Array of object | null Address data from the document as array of strings object fullAddressstring | null Address as single string Example3, 123, Main Street, My County, Anytown, 12345 reasonstring | null Reason of failed verification Example reasonCodeinteger | null Reason code of failed verification Example comments Array Deprecated Example[] documentobject Verified document typestring | null Document type. Always returns `null` Example numberstring | null Document number. Always returns `null` Example countrystring | null ISO-2 Document country. Always returns `null` Example validFromstring | null Document is valid from date. Always returns `null` Example validUntilstring | null Document is valid until date. Always returns `null` Example vendorDatastring | null Unique identifier created by the customer to identify the end-user. Returned unmodified in webhooks and public API calls, or as `null` if not provided endUserIdstring 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 decisionTimestring (date-time) Timestamp of the decision. Combined ISO 8601 date and time in UTC YYYY-MM-DDTHH:MM:SSS+Timezone Offset Example2023-11-06T07:18:36.916Z acceptanceTimestring (date-time) Timestamp of the session generation. Combined ISO 8601 date and time in UTC YYYY-MM-DDTHH:MM:SSS+Timezone Offset Example2023-11-06T07:15:27Z additionalVerifiedDataobject Data which has been optionally verified for session failedValidationstring Message for the failed validation technicalDataobject Technical data object ipstring | null IP of the device from which the verification was made Example 400 Address data missing 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)" } ``` object statusstring Status of the request Examplefailed codestring Status code Example1102 messagestring Explanation why the verification failed ExampleRequest address is missing required field fullAddress or (street + houseNumber + postcode) 400 Date of birth OR address data missing Required field `dateOfBirth` or `address` not provided ```json { "status": "failed", "code": "1102", "message": "Request is missing required field 'dateOfBirth' or 'address'" } ``` object statusstring Status of the request Examplefailed codestring Status code Example1102 messagestring Explanation why the verification failed ExampleRequest is missing required field 'dateOfBirth' or 'address' 400 ID number data missing Required field `idNumber` not provided ```json { "status": "failed", "code": "1102", "message": "Request is missing required field idNumber" } ``` object statusstring Status of the request Examplefailed codestring Status code Example1102 messagestring Explanation why the verification failed ExampleRequest is missing required field idNumber 400 Name data missing Required field `fullName` or (`firstName` + `lastName`) not provided ```json { "status": "failed", "code": "1102", "message": "Request person is missing required field fullName or (firstName + lastName)" } ``` object statusstring Status of the request Examplefailed codestring Status code Example1102 messagestring Explanation why the verification failed ExampleRequest person is missing required field fullName or (firstName + lastName) 401 X-HMAC-SIGNATURE validation failed object statusstring Status of the request Examplefailed codestring Status code Example1812 messagestring Explanation why the verification failed ExampleSignature {invalid-hmac-signature value} is not a valid SHA256 hash. Document Versioning **Changelog** | **Date** | **Description** | | --- | --- | | 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 |