Validate national ID number

Updated

Updated on Mar 9, 2026
Published on Mar 8, 2026

Post

/v1/validate-registry

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

Header parameters

x-auth-client

stringRequired

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

stringRequired

Must be application/json

Valid values[ "application/json" ]

Exampleapplication/json

Body parameters

fullName_with_dateOfBirth

Validates using idNumber + fullName + dateOfBirth.

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

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

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

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

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

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

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

{
  "verification": {
    "person": {
      "idNumber": "123456789",
      "fullName": "John Smith",
      "dateOfBirth": "1980-03-06"
    }
  }
}

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.

Examplehttps://exampleURL.com/callback

person

object Required

Data about the person being verified.

idNumber

string Required

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.

ExampleJohn Smith

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

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

Responses

200

Session created successfully

Headers

x-auth-client

string

API key echoed back in response.

x-hmac-signature

string

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

Content-Type

string

Response 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.

{
  "status": "success",
  "verification": {
    "id": "f8b2c4d6-1a3e-4f9b-8c2d-5e7a9b1c3d4f",
    "vendorData": "1234567890",
    "status": "created",
    "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiZjhiMmM0ZDYtMWEzZS00ZjliLThjMmQtNWU3YTliMWMzZDRmIn0..."
  }
}

Expand All

object

status

string

API request status.

Examplesuccess

verification

object

Verification object.

id

string

UUID v4 which identifies the verification session.

Example123e4567-e89b-12d3-a456-426614174000

vendorData

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

status

string

Verification session status.

Examplecreated

sessionToken

string

Session-specific token of the verification.

ExampleeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

400

Bad request - missing or invalid required fields

Headers

x-auth-client

string

API key echoed back in response.

x-hmac-signature

string

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

Content-Type

string

Response content type.

Valid values[ "application/json" ]

missing_name_data

Missing name data - Required field fullName or (firstName + lastName) not provided

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

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

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

object

status

string

Valid values[ "fail" ]

Examplefail

code

string

Example1101

message

string

ExampleValidation failed

401

Unauthorized - HMAC signature validation failed

Headers

x-auth-client

string

API key echoed back in response.

x-hmac-signature

string

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

Content-Type

string

Response content type.

Valid values[ "application/json" ]

{
  "status": "failed",
  "code": "1812",
  "message": "Signature a1b2c3d4e5f6 is not a valid SHA256 hash"
}

object

status

string

Valid values[ "fail" ]

Examplefail

code

string

Example1101

message

string

ExampleMandatory X-AUTH-CLIENT header containing the API key is missing from the request.

Changelog

Changelog

Date	Description
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

Was this article helpful?