Identity Verify
Introduction
The "Identity Verification" API is used to validate and verify the accuracy of user-provided identity information, such as first name, last name, address, and more. This API can be called standalone to verify the user identity and also after the "Prefill" API to check if any changes have occurred in the provided data as part of the workflow. By utilizing this API, you can ensure the integrity of the user's identity information and make informed decisions based on the verification results.
How to call the API
You must first login before sending the request. The authorization header in the request must include the access token obtained from the login API call.
API Input Guidelines
Need to pass the following information. Atleast one of last4ssn or nationalId is required.
- phoneNumber
- last4ssn
- nationalId
Sample cURL
curl --location 'https://api.signzy.app/api/v3/us-kyc/identity-verification' \
--header 'Content-Type: application/json' \
--header 'Authorization: <Auth Token>' \
--data '{
"requestId": "64664c731a6d0fd89316fbc4",
"consentStatus": "optedIn",
"phoneNumber": "19177253169",
"ssn":"602410869",
"firstName": "Hanson",
"lastName": "Kerner",
"address": "761 Shasta Place",
"city": "Fort Lauderdale",
"postalCode": "33355",
"details": "true"
}'Input Parameters
Key | Type | Mandatory | Description |
|---|---|---|---|
requestId | string | true | Unique identifier associated with this request. Must be unique for each transaction. |
subscriptionCustomerId | string | false | A unique identifier for our customer's subscribers for Identity Manager. |
consentStatus | string | true | The consent status of the phone number. Possible values are: optedIn - The end user has provided consent for the collection of their personal data. optedOut - The end user has refused to allow collection of their personal data. notCollected - No attempt has been made to obtain consent from the end user. unknown - The status of consent collection is unknown. Note: This value must be optedIn in order to access MNO data. |
phoneNumber | string | Either phoneNumber or payfoneAlias is required, not both. | The phone number being queried. Formatted in E.164 formatting for international numbers, including the leading plus sign. |
payfoneAlias | string | Either phoneNumber or payfoneAlias is required, not both. | A persistent ID that uniquely identifies a telephone subscriber. |
firstName | string | For matching at least the First Name or Last Name MUST be submitted in the request. Unless matching on last4 or SSN only. | First name associated with the phone number being queried. |
lastName | string | For matching at least the First Name or Last Name MUST be submitted in the request. Unless matching on last4 or SSN only. | Last name associated with the phone number being queried. |
address | string | false | The address number and street associated with the phone number being queried. |
extendedAddress | string | false | The second line of the address associated with the phone number being queried (e.g., suite 210 or Apt B). |
city | string | false | The city associated with the phone number. |
region | string | false | The region (or state abbreviation) associated with the phone number. |
postalCode | string | false | The postal code associated with the phone number. |
dob | string | false | Date of birth associated with the phone number. Accepts different formats: ISO 8601 (YYYY-MM-DD), month and year (MM/YYYY), or month and day (MM/DD). |
last4 | string | false | The last four digits of the social security number associated with the subscriber. |
ssn | string | false | The social security number associated with the subscriber. |
emailAddress | string | false | Email associated with the phone number. |
details | string | false | Set to "true" to access premium data responses. When set to true, only query parameters with valid string values are returned in the response. If a parameter is not provided in the request, it will be omitted from the response. |
lastVerified | string | false | Date on which the identity behind the phone number was last verified. Must be in ISO 8601 format. If Signzy determines that no changes have occurred since this date, the response will indicate verified as true, and matching will not be completed. |
phoneUpdate | string | false | Set to "true" to include the phoneUpdate object in the response if the phone number being queried has changed since the lastVerified date. Default value is false. |
driversLicenseNumber | string | false | The driver's license number associated with the phone number and person being queried. Special characters such as "-" or "*" can be included and do not affect matching. |
driversLicenseState | string | false | The driver's license state associated with the phone number being queried. Must be in the 2-character postal abbreviation. |
Output parameters
Key | Type | Description |
|---|---|---|
requestId | string | The requestId from the request, reflected back for tracking purposes. |
status | number | The status of the request. A response of 0 indicates success. Any non-0 response is an error indication. |
description | string | A text string that defines the cause of the status code. |
response | object | object An object containing the phone number and associated details. |
transactionId | string | Unique transaction identifier used to identify the results of the request. |
phoneNumber | string | The phone number(s) associated with the individual. |
lineType | string | Line type associated with the phone number. Possible values are: Mobile, Landline, FixedVoIP, NonFixedVoIP. |
carrier | string | The carrier related to the phone number. |
countryCode | string | The country code associated with the phone number. |
verified | boolean | The result of the transaction request indicating whether the identity information is verified. |
address | object | The address object containing address details. |
streetNumber | integer | A score of the address input (minus the extendedAddress); values -1 to 100. 100 indicates an exact match. |
street | boolean | The results of the street name match. |
city | boolean | The results of the city match. |
region | boolean | The results of the region (state abbreviation) match. |
postalCode | boolean | The results of the postal/zip code match. |
distance | float | The distance value—in miles—between the address in input and the normalized address on file. |
addressScore | integer | An overall address score that uses all the address attributes to generate the overall score; values -1 to 100. 100 indicates an exact match. |
name | object | The name object containing name details. |
firstName | integer | A score of the first name match; values -1 to 100. 100 indicates an exact match. |
lastName | integer | A score of the last name match; values -1 to 100. 100 indicates an exact match. |
nameScore | integer | An overall name score that uses both the first and last name scores to generate the overall score. Values -1 to 100. 100 indicates an exact match. |
identifiers | object | The identifiers object containing identifier details. |
last4 | boolean | The results of the last 4 of SSN match. |
dob | boolean | The results of the date of birth match. |
driversLicenseState | boolean | The results of the driver’s license state match. |
driversLicenseNumber | boolean | The results of the driver’s license number match. |
object | The email object containing email details. | |
emailAddress | boolean | The results of the email match. |
reasonCodes | string[] | An array of indicators providing additional context about the transaction. |
Sample Response
{
"result": {
"requestId": "6466555fa90017ffa26ebba0",
"status": 0,
"description": "Success.",
"response": {
"verified": true,
"transactionId": "12225155440",
"payfoneAlias": "60A37E2C4VKRKKX4D3FD70CEE16C05AFA0MEK1A51JD9P396647CB4C454F4DC26A7202BA66E04E2F9F6G30F557A4CD71D054FB417EE475B03404D02BF",
"phoneNumber": "19177253169",
"lineType": "Mobile",
"carrier": "T-Mobile USA",
"countryCode": "US",
"name": {
"firstName": 100,
"lastName": 100,
"nameScore": 100
},
"address": {
"streetNumber": 100,
"street": false,
"city": true,
"postalCode": true,
"distance": 0,
"addressScore": 100
},
"identifiers": {
"ssn": true
},
"cipConfidence": "high",
"reasonCodes": [
"OU",
"P5",
"PT",
"RM",
"UV"
]
}
}
}Sample Error
{
"error": {
"name": "error",
"message": "..message..",
"status": 400,
"reason": "BadRequest",
"type": "OK",
"statusCode": 200
}
}Response Parameter
PARAMETER NAME | DESCRIPTION |
|---|---|
error | This parameter contains the error. |
error.name | the name of the error |
error.message | the error message |
error.status | status of the api |
error.reason | Reason for error |
error.type | Type of the error |
error.statusCode | Request Status code from Signzy |
Getting help
Please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better.
You can reach out to us at [email protected].