Social Security Number (SSN) Verification

SSN lookup API

To perform verification on a United States Social Security Number (SSN), make a POST request to the SSN lookup endpoint;

https://api.korapay.com/merchant/api/v1/identities/us/ssn

The request body should have the following parameters:

{
  "id": "765439022",
  "first_name": "John",
  "last_name": "Smith",
  "phone": "+12109041086",
  "date_of_birth": "1995-01-23",
  "verification_consent": true
}

Field	Data Type	Description
`id`	string	Required - 9-digit SSN
`first_name`	string	Required - First name of the SSN holder
`last_name`	string	Required - Last name of the SSN holder
`phone`	string	Required - US phone number with country code (e.g. +1XXXXXXXXXX)
`date_of_birth`	string	Required - Date of birth (YYYY-MM-DD)
`verification_consent`	string	Required - Indicate subject has given consent. Must be true
`requester`	object	Optional - { "first_name": "...", "last_name": "..." }

SSN response (initial)

{
  "status": true,
  "message": "SSN verification initiated successfully",
  "data": {
    "reference": "VR-abc123xyz",
    "id": "123456789",
    "id_type": "us_ssn",
    "status": "processing",
    "requested_by": "API User"
  }
}

SSN verification is processed asynchronously. When verification is complete, a webhook notification is sent to your application with the final result. You can also query the verification using the verification reference via the Query endpoint.

Completed SSN verification response (via webhook or query) includes address history:

reference
id
id_type
first_name
last_name
middle_name
date_of_birth
phone_number
addresses
status
{
    "status": true,
    "message": "Verification retrieved successfully",
    "data": {
        "reference": "VR-tZmfSmVs4qHgKKrkz",
        "full_name": "John Smith",
        "id_type": "us_ssn",
        "first_name": "John",
        "last_name": "Smith",
        "date_of_birth": "1995-01-23",
        "phone_number": "12109041086",
        "addresses": [
            {
                "street": "6 Jenna Plaza",
                "state": "NY",
                "town": "New York City",
                "post_code": "10009",
                "country": "USA",
                "formatted_address": "6 Jenna Plaza, New York City, New York, United States of America, 10009"
            }
        ],
        "id": "765439022",
        "masked_id": "******022",
        "type": "kyc",
        "class": "id_lookup",
        "identity_type": "us_ssn",
        "country": "us",
        "requested_by": "API User",
        "status": "found",
        "date_created": "2026-04-24T08:58:21.126Z"
    }
}