/v1/validate-registry

Updated
  • Updated on Apr 30, 2025
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. 

You will need a separate integration to do this verification, ask your Solutions Engineer to set it up. 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


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


Security
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

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