/v1/validate-registry

Prev Next
Post
/v1/validate-registry

Validates a national ID number (e.g. social security number (SSN)) with the provided data 

A verification session will be automatically created and submitted. After that, the validation result is sent via webhook. 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 do SSN validation (hereinafter “default /validate-registry"). This endpoint is used by default and uses the API URL //example-base-url/v1/validate-registry.

When using this endpoint, the response returns info only about the request status, and includes some additional session related data. All the info about the person being verified is sent via webhook.

The other option is to use “sync-api /validate-registry” (hereinafter “sync-api /validate-registry”). This returns the info inside the API response payload. It is not available by default, you need to contact Veriff to use the sync-api /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.


Security
API Key: api_key
Header parameter namex-auth-client

Your integration's API key (occasionally referred to the "Token", "API public key" or "Publishable key")

Header parameters
vrf-integration-id
string

Your Integration's ID. Required when the flexible API keys solution is used

Body parameters

Session initalization data

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 Required

Person's social security number (SSN).

Example123456789
fullName
string

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

ExampleJohn Smith
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
dateOfBirth
string (YYYY-MM-DD)

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

Example1990-01-01
phoneNumber
string

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

Example+123 456 789
address
object

Data about the address of the person being verified

fullAddress
string | null

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

Example123, Main Street, My County, Anytown 12345
street
string | null

Street. Required if fullAddress is not provided

ExampleMain Street
houseNumber
string | null

House number. Required if fullAddress is not provided

Example123
postcode
string | null

Postal code. Required if fullAddress is not provided

Example12345
city
string | null

City

ExampleAnytown
state
string | null

State

ExampleMy County
unit
string | null

Apartment number

Example1
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

Example1234567890
Responses
200

Created session

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

object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleValidation failed
401

Unauthorized

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

Internal server error

object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleSomething went wrong



Document Versioning

Article Versioning

Date

Description

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

Enter your description here