Call this API to verify a US National ID (SSN) against the credit-bureau database with a pure API integration. The verification compares the submitted identity attributes against the database record.
Prepare a unique bizId for the business transaction
Prepare a unique userId for the user being verified
Set region, numberType, numberValue, and provide data.firstName + data.lastName + data.birthday (required); data.address, data.phoneNumber / data.phone, and data.email are optional
string The unique business ID for the transaction that triggered this verification, such as an order ID. Must be non-empty and no longer than 99 characters.
userId
string The unique user ID for the user performing the verification. Must be non-empty and no longer than 200 characters.
region
string The supported service region. Refer to ISO ALPHA-3 Country Code. For US verification, must be USA.
numberType
string The identity number type. Case-sensitive — must be uppercase. See Supported numberType. Any value not in the supported set (or lowercase such as nationalid) will be rejected with PARAMETER_ERROR / Number type and country are not match.
numberValue
stringRequired. US National ID (SSN). Must be exactly 9 pure digits (\d{9}). Separators such as - or spaces are not accepted and will be rejected with PARAMETER_ERROR / Invalid ID number，please check the format.
data
object Extended data object for additional verification parameters.
data.firstName
stringRequired. Given name.
data.lastName
stringRequired. Family name / surname.
data.birthday
stringRequired. Date of birth in yyyy/MM/dd format.
data.address
string or object(optional) Address. A plain string is treated as street line 1. An object may include: street1 , street2 , city, region , postalCode .
data.phoneNumber
string(optional) Phone number.
data.email
string(optional) Email address.
Supported numberType
numberType
region
numberValue format
Description
NATIONALID
USA
Exactly 9 digits (123456789). No dashes or spaces.
United States National ID (SSN)
Response Description
Parameter
Description
code
Response Code.
transactionId
The request ID of this API call. The max length is 64.
pricingStrategy
Deprecated, always returns FREE.
message
Status Code Explanation.
data
object The business result of the verification.
Response.data
Field
Description
signatureId
The business ID of this verification.
overallResult
Overall verification result. One of PASS or FAIL or INCOMPLETE.
errorCode
Business-level error code when overallResult is not PASS. Returns an empty string when overallResult is PASS. Possible values: INFO_MISMATCH, INVALID_FORMAT, ERROR.
docDatabaseDetail
object Person information returned by the database when overallResult is PASS. Returns null for non-PASS outcomes (mismatch / incomplete / format failure).
Response.data.docDatabaseDetail
Returned only when overallResult is PASS.
Field
Description
firstName
string Given name from the database record.
lastName
string Family name / surname from the database record.
fullName
string Full name. If the vendor does not return it, it may be composed from firstName + lastName.
birthday
string Date of birth, normalized to yyyy/MM/dd.
address
string Address text returned by the database.
postalCode
string Postal / ZIP code.
state
string State code, for example NY.
street
string Street line returned by the database.
Response.code
This API returns two layers of status codes. The top-level code only reflects infrastructure-level or request-level failures. Business verification results, including vendor mismatches and vendor failures, are returned in data.overallResult and data.errorCode when the top-level code is SUCCESS.
Top-level code
Status Code
Message
SUCCESS
OK. The request reached business processing. The actual verification result is returned in data.overallResult and data.errorCode.
PARAMETER_ERROR
BizId is wrong
BizId is too long
UserId is invalid
The userId length cannot exceed 200.
Region is wrong
Number type is empty
Number type is wrong
Number type and country are not match (numberType not in supported set for the region, or not uppercase, or region/numberType combination not allowed for US)
Invalid ID number，please check the format (numberValue is missing, or not exactly 9 digits)
Invalid input，please check the format (data.firstName / data.lastName missing, or birthday/dateOfBirth missing / not yyyy/MM/dd / not a valid calendar date)
IAM_FAILED
IAM check failed
ERROR
Server error
data.errorCode
This section applies only when the top-level code is SUCCESS.
errorCode
overallResult
Description
""
PASS
Database lookup succeeded and the submitted information matches the record. docDatabaseDetail contains the matched person fields.
INFO_MISMATCH
FAIL
Submitted identity attributes do not match the database record (vendor non-match / partial match). docDatabaseDetail is null.
INVALID_FORMAT
FAIL
Downstream rejected the payload as invalid format / empty required fields after the request passed local parameter checks. docDatabaseDetail is null.
ERROR
INCOMPLETE
The vendor call failed, timed out, or returned an unhandled / processing status (e.g. registry unavailable). docDatabaseDetail is null.
{
"code": "PARAMETER_ERROR",
"message": "Number type is empty",
"data": null,
"extra": null,
"transactionId": "a1b2c3d4e5f6g7h8",
"pricingStrategy": "FREE"
}
numberType is wrong
{
"code": "PARAMETER_ERROR",
"message": "Number type is wrong",
"data": null,
"extra": null,
"transactionId": "a1b2c3d4e5f6g7h8",
"pricingStrategy": "FREE"
}
number type and country are not match
{
"code": "PARAMETER_ERROR",
"message": "Number type and country are not match",
"data": null,
"extra": null,
"transactionId": "a1b2c3d4e5f6g7h8",
"pricingStrategy": "FREE"
}
