Validate registry

Updated on Jan 8, 2026
Published on Mar 3, 2025

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 (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 for more info.

Note: always ensure that you use the correct API URL to send requests. See the API URL section for more info.

Header parameters

x-auth-client

stringRequired

Your integration's API key. Required to identify the request sender. Occasionally referred to as the "API token".

x-api-key

stringRequired

Your integration's API key.

x-hmac-signature

string

Request body signed with the shared secret key. Required to authenticate the request sender.

content-type

string

Exampleapplication/json

Body parameters

fullName_with_dateOfBirth

idNumber + fullName + dateOfBirth.

Note that phoneNumber, vendorData, and endUserId are optional but strongly recommended for improved fraud prevention.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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 All

object

verification

object Required

Verification object

callback

string

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.

person

object Required

Data about the person being verified

idNumber

string

Person's national ID number (SSN)

Example123456789

firstName

string

Person's first name. Required if fullName is not provided

ExampleJohn

lastName

string

Person's last name. Required if fullName is not provided

ExampleSmith

fullName

string

Person's full name. Required if firstName + lastName is not provided

phoneNumber

string

Person's phone number, can include numbers, whitespaces and the "+" sign in front

Example+00 123 456 789

dateOfBirth

string (YYYY-MM-DD)

Person's date of birth. Required if address is not provided

Example1980-03-06

address

object Required

Data about the address of the person being verified

fullAddress

string

Full address. Required if street + houseNumber + postcode are not provided

Example3, 123, Main Street, My County, Anytown, 12345

street

string

Street name. Required if fullAddress is not provided

ExampleMain Street

houseNumber

string

House number. Required if fullAddress is not provided

Example123

postcode

string

Postal code. Required if fullAddress is not provided

Example12345

city

string

Any human settlement, including cities, towns, villages, hamlets, localities, etc.

ExampleAnyCity

state

string

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

unit

string

An apartment, unit, office, lot, or other secondary unit designator

Example3

vendorData

string

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

endUserId

string

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

Responses

200

Successful response

Headers

x-auth-client

string

Your integration's API key. Required to identify the response sender. Occasionally referred to as the "API token".

x-api-key

string

Your integration's API key.

x-hmac-signature

string

Response body signed with the shared secret key. Required to authenticate the response sender.

{
  "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 All

object

status

string

Status of the response

Examplesuccess

verification

object

Verification request decision object. null if decision is not available yet

id

string (uuid)

UUID v4 which identifies the verification session

Example09551b48-4d7c-4a30-8437-5301223953fa

code

integer

Verification response code

Valid values[ 9001, 9102, 9103, 9104, 9121 ]

Example9001

status

string

Verification session status

Valid values[ "approved", "declined", "resubmission_requested", "abandoned", "expired" ]

Exampleapproved

person

object

Verified person

firstName

string | null

Person's first name

ExampleJOHN

lastName

string | null

Person's last name

ExampleSMITH

idNumber

string | null

National identification number

Example123456789

dateOfBirth

string | null

Person's date of birth. YYYY-MM-DD

Example1980-03-06

yearOfBirth

string | null

Person's year of birth. YYYY

Example1980

placeOfBirth

string | null

Person's place of birth

ExampleANYTOWN

addresses

Array of object | null

Address data from the document as array of strings

object

fullAddress

string | null

Address as single string

Example3, 123, Main Street, My County, Anytown, 12345

reason

string | null

Reason of failed verification

Example

reasonCode

integer | null

Reason code of failed verification

Example

comments

Array Deprecated

Example[]

document

object

Verified document

type

string | null

Document type. Always returns null

Example

number

string | null

Document number. Always returns null

Example

country

string | null

ISO-2 Document country. Always returns null

Example

validFrom

string | null

Document is valid from date. Always returns null

Example

validUntil

string | null

Document is valid until date. Always returns null

Example

vendorData

string | 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

endUserId

string

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

decisionTime

string (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

acceptanceTime

string (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

additionalVerifiedData

object

Data which has been optionally verified for session

failedValidation

string

Message for the failed validation

technicalData

object

Technical data object

ip

string | 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

{
  "status": "failed",
  "code": "1102",
  "message": "Request address is missing required field fullAddress or (street + houseNumber + postcode)"
}

object

status

string

Status of the request

Examplefailed

code

string

Status code

Example1102

message

string

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

{
  "status": "failed",
  "code": "1102",
  "message": "Request is missing required field 'dateOfBirth' or 'address'"
}

object

status

string

Status of the request

Examplefailed

code

string

Status code

Example1102

message

string

Explanation why the verification failed

ExampleRequest is missing required field 'dateOfBirth' or 'address'

400 ID number data missing

Required field idNumber not provided

{
  "status": "failed",
  "code": "1102",
  "message": "Request is missing required field idNumber"
}

object

status

string

Status of the request

Examplefailed

code

string

Status code

Example1102

message

string

Explanation why the verification failed

ExampleRequest is missing required field idNumber

400 Name data missing

Required field fullName or (firstName + lastName) not provided

{
  "status": "failed",
  "code": "1102",
  "message": "Request person is missing required field fullName or (firstName + lastName)"
}

object

status

string

Status of the request

Examplefailed

code

string

Status code

Example1102

message

string

Explanation why the verification failed

ExampleRequest person is missing required field fullName or (firstName + lastName)

401

X-HMAC-SIGNATURE validation failed

object

status

string

Status of the request

Examplefailed

code

string

Status code

Example1812

message

string

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

Was this article helpful?