Identity Verify

9 min

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

Production

Pre-production

curl --location 'https://api-preproduction.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"
}'

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.
email	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].