Validate registry

Updated on May 29, 2025
Published on Mar 3, 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.

Header parameters

X-AUTH-CLIENT

stringRequired

API key

X-API-Key

stringRequired

API key

X-HMAC-SIGNATURE

string

Request body signed with the shared secret key

VRF-INTEGRATION-ID

string

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

Content-Type

string

Exampleapplication/json

Body parameters

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

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

Expand All

object

status

string

Status of the response

Examplesuccess

verification

object

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

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

person

object

Data about the person verified

gender

string | null

Person's gender. Will always return 'null'

Valid values[ "\"M\"", "\"F\"", "null" ]

Example

idNumber

string | null

Person's national identification number (SSN)

Example123456789

lastName

string | null

Person's last name

ExampleSmith

firstName

string | null

Person's first name

ExampleJohn

dateOfBirth

string (YYYY-MM-DD)

Person's date of birth

Example1980-03-06

yearOfBirth

string | null

Person's year of birth

Example1980

placeOfBirth

string | null

Person's place of birth

Example

pepSanctionsMatch

string | null

Legacy field, may return incorrect result, should be ignored

Example

citizenship

string | null Deprecated

Always returns 'null'

Example

nationality

string | null

Person's nationality. Always returns 'null'

Example

status

string

Verification status

Valid values[ "\"approved\"", "\"declined\"" ]

Exampleapproved

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

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

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

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

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

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