Identity Verify - Lite

Introduction

The Identity Verify API (“Identity Verify”) enables you to verify an individual consumer’s identity using a phone-first approach that validates consumer-provided personal identifying information (PII) and confirms ownership of their phone number using authoritative data, including device and phone number tenure data. This is a critical step in ensuring your important consumer interactions are with the phone number owner and information, helping eliminate bad actors and prevent fraudulent accounts.

Signzy performs ownership verifications without ever storing your consumers' PII.

Ownership verification goes beyond just matching a person's name and address; inputs that can be included for matching in the API request are name, address, city, countryCode date of birth (DOB), phone number.

The API's verified flag and matching details can help with customer onboarding (acquisitions, originations, registrations, etc.) and servicing (e.g., your customer adds a new phone number to their profile) and enhances user experience.

By utilizing this API, you can ensure the integrity of the user's identity information and make informed decisions based on the verification results.

Supported Countries :- US & Canada

Features

Phone Number Ownership Verification

Identity Verify provides phone ownership verification using the phone number status + the name & address information to then determine a verified status of true or false. You start by querying the phone number, locating the relevant information associated with the identity recognized behind the phone number, and then matching appropriate fields against your consumer's submitted data.

API Details

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.

Sample cURL

Production

Pre-production

curl --location 'https://api.signzy.us/api/v3/us-kyc/idv-lite' \
--header 'Content-Type: application/json' \
--header 'Authorization: <Auth Token>' \
--data '{
  "consentStatus": "optedIn",
  "phoneNumber": "9177253169",
  "firstName": "Hanson",
  "lastName": "Kerner",
  "address": "761 Shasta Place",
  "city": "Fort Lauderdale",
  "region" : "IL",
  "postalCode": "33355",
  "countryCode": "US",
  "dob": "1990-02-21",
  "emailAddress": "[email protected],
  "details": "true"
}'

curl --location 'https://api-preproduction.signzy.us/api/v3/us-kyc/idv-lite' \
--header 'Content-Type: application/json' \
--header 'Authorization: <Auth Token>' \
--data '{
  "consentStatus": "optedIn",
  "phoneNumber": "2001001686",
  "firstName": "Tod",
  "lastName": "Weedall",
  "address": "39 South Trail",
  "city": "San Antonio",
  "region" : "TX",
  "postalCode": "78285",
  "details": "true",
  "countryCode": "US",
  "dob": "1984-12-10",
  "emailAddress": "[email protected]"
}'

Request Body Parameters

Parameter	Data Type	Required	Description
consentStatus	string	Yes	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	Yes	The phone number being queried. (without leading plus sign & country code)
firstName	string	Yes	First name associated with the phone number being queried.
lastName	string	Yes	Last name associated with the phone number being queried.
address	string	Optional	The address number and street associated with the phone number being queried.
city	string	Optional	The city associated with the phone number.
region	string	Optional	The region (or state abbreviation) associated with the phone number.
postalCode	string	Optional	The postal code associated with the phone number.
countryCode	string	Yes	Country Code of address. Please mention "US" for United States & "CA" for Canada.
dob	string	Optional	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).
emailAddress	string	Optional	Email associated with the phone number.
details	string	Optional	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.

Consumer Input Parameters

Regardless of whether details are returned or not, a match score is generated for the following PII data elements:

Name (first name, last name, name score)
Address (street number, street, city, region, postal code, distance, address score)

Boolean values can be generated for the following PII data elements:

Identifiers (date of birth)

The fields you implement for your Identity Verify calls should reflect the typical personal information you request from your consumers.

At minimum, however, the request needs to include

the phone number
Country Code

to return a successful response; otherwise, an error is returned. However, the more fields included for name, address etc., the more reliable the verification result.

When the API request is sent, if Signzy finds no data for the person, verified returns false, and a reason code of NC is returned, indicating no name and address information associated with the phone number. The consumer should then be put through your organization's step-up procedure. If data is found for the person, the data matching process is enabled and performed for the available fields as outlined in the Scoring and Matching Framework section below.

Score and Matching Framework

Signzy checks the information submitted through the Identity Verify API, only matching information submitted using our proprietary logic. You're able to see the details of the resulting matching and scores in your responses by including the details parameter as true in the request.

Name and Address Matching Match results for the name and address fields are calculated with weighted algorithms to generate a score for each; the weight applied is influenced by how much variance was found between submitted data and queried data (e.g., which fields returned true/false, etc.). These calculations then return a unique total score for the name matching and (if the information is submitted) a unique total score for the address matching; each can fall between 0–100. These scores contribute to the verification of the end user with the following logic:

Either a nameScore greater than or equal to 70 or an addressScore greater than or equal to 70 contributes to verified returing true
Both name and address scores failing the above thresholds contribute to verified returning false.

Name and Address Matching Notes

Name matching takes into account:
- nicknames
- first/last name transposition
- name contained within
- those with changed last name due to marriage
- mother and father's name concatenated or split within middle and last name fields
- fuzzy match logic
Extended address data can be submitted to support the many address forms with additional lines for apartment numbers, etc., but this data is not factored into address matching logic.

Reason codes are returned when these matching elements come into play.

See the Identity Verify Flows section for diagrams of each situation.

The rest of the request and response parameters (date of birth etc.) are simply informational, returning true or false (if details is set to true, see the Detailed Response section) to help you confirm submitted data and not contribute to the verified response.

Response Body Parameters

Parameter	Data 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.
dob	boolean	The results of the date of birth 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.

If a death indicator was found in the matching data for the person submitted, verified returns false, and a DI reason code is returned in the response as well. See the Reason Codes section for more information on Identity Verify reason codes.

Detailed Response

There is a critical query parameter to explain first: details. It's set by default to false, but if you determine you want to receive the matching outcome for the various PII inputs of your consumer, it should be set to true. The API response then includes a field-level breakdown of the matching and score results, which can add visibility to the verification decision. When left to false, you only receive the overall verified result.

Sample Response (Details = true)

{
    "result": {
        "requestId": "64c3d94bde1e7abedb5ca27d",
        "status": 0,
        "description": "Success.",
        "response": {
            "verified": true,
            "transactionId": "16724328134",
            "payfoneAlias": "79510AFC4VK8384926E400823FFFD9FF40MEKGYGSX99P8C87721302E560194D77B5649EA8673ECF5F6G3244CFE2A52A4D84C289E55ED79814E489D3C",
            "phoneNumber": "12245074373",
            "lineType": "Mobile",
            "carrier": "T-Mobile USA",
            "countryCode": "US",
            "name": {
                "firstName": 100,
                "lastName": 100,
                "nameScore": 100
            },
            "address": {
                "streetNumber": 100,
                "street": true,
                "city": true,
                "region": true,
                "postalCode": true,
                "distance": 0,
                "addressScore": 100
            },
              "email": {
                "emailAddress": false
            },
            "identifiers": {
                "dob": true
            },
            "reasonCodes": [
                {
                    "code": "NA",
                    "description": "The address is valid and has been normalized before calculating the match score."
                },
                {
                    "code": "OL",
                    "description": "How long the identity has been associated with a phone number. Long Tenure > 90 days."
                },
                {
                    "code": "P9",
                    "description": "The postal code submitted matched the first nine digits."
                }
            ]
        }
    }
}

Sample Response (Details = false)

{
    "result": {
        "requestId": "64c3d970de1e7abedb5ca27f",
        "status": 0,
        "description": "Success.",
        "response": {
            "verified": true,
            "transactionId": "16724343781",
            "payfoneAlias": "79510AFC4VK8384926E400823FFFD9FF40MEKGYGSX99P8C87721302E560194D77B5649EA8673ECF5F6G3244CFE2A52A4D84C289E55ED79814E489D3C",
            "phoneNumber": "12245074373",
            "lineType": "Mobile",
            "carrier": "T-Mobile USA",
            "countryCode": "US",
            "reasonCodes": [
                {
                    "code": "NA",
                    "description": "The address is valid and has been normalized before calculating the match score."
                },
                {
                    "code": "OL",
                    "description": "How long the identity has been associated with a phone number. Long Tenure > 90 days."
                },
                {
                    "code": "P9",
                    "description": "The postal code submitted matched the first nine digits."
                }
            ]
        }
    }
}

Only parameters submitted in the request return in a detailed response. For example, if city was not included in the address fields for the request, there is no matching performed for that field, and that field is excluded from the response.

Reason Codes

Along with the scores, Signzy supplies reason code(s) in the response that gives further insight into why a particular score was returned or indicates the risk associated with the identity. This is to assist you in making informed decisions for managing your risk. The following reason codes can be returned for all versions of the Identity Verify API:

Reason Code	Description
AC	The normalized address was used to complete empty address fields before the match.
AU	Address undeliverable
BA	Business address
BL	Business line
C2	2 identities that have OS or OV reason codes
C3	3 identities that have OS or OV reason codes
C4	4 identities that have OS or OV reason codes
C5	5 identities that have OS or OV reason codes
CF	The address matches the address of a U.S. correctional facility.
CN	First and last names (or multiple names) combined in one field.
DA	Dual address (Ex: 123 Main St PO Box 99)
DI	Death indicator found on data.
DT	Data retrieval timeout
FN	The family name is considered in the overall calculation.
HR	High-rise; address contains apartment or building sub-units.
IA	Inactive address (examples: new developments may have addresses but will be "inactive" until somebody moves in. Or, after Hurricane Katrina, addresses in the affected area were marked inactive for a time.)
LA	Low tenure address
MA	The address submitted in the request is associated with multiple active addresses; e.g., the address might be missing a suite or apartment number to specify the necessary active address.
MI	Military address
NA	The address is valid and has been normalized before calculating the match score.
NC	Name and address information is not available.
ND	Phone number network status information is not available. While this may mean no data is available, this may not necessarily indicate risk.
NM	Not a mobile line type. It may not indicate risk but is intended to filter mobiles from non-mobile line types.
NN	Nickname found and used in matching. For example, Bill matches with William.
NO	Input identity has been verified (verified=true). Newer ownership or association has recently been connected to the phone number. See also reason code OO.
NP	Non-personal line; could signify a business or government phone line.
NS	Names were swapped (first/last).
NU	The phone number has been updated.
OD	A disconnect date was found after the date of ownership of the phone number (i.e., when the identity was first associated with the phone number). It doesn't matter how long ago either occurred; this reason code returns whenever the disconnect occurs after the ownership date.
OL	Long ownership tenure, which is > 90 days. Ownership tenure is how long the identity has been associated with a phone number, based on when the ownership was first seen. See also OS, OV, and OU.
OO	Input identity has been verified (verified=true). The connection of the ownership or association to this phone number was not recent; however, no known newer ownership or association was found, a.k.a. the ownership is "older". See also reason code NO.
OS	Short ownership tenure, which is eight days–90 days. Ownership tenure is how long the identity has been associated with a phone number, based on when the ownership was first seen. See also OL, OV, and OU.
OU	Ownership tenure is unknown, meaning the date attributes associated with the phone number are unavailable. Ownership tenure is how long the identity has been associated with a phone number, based on when the ownership was first seen. See also OL, OS, and OV.
OV	Very short ownership tenure, which is < 7 days. Ownership tenure is how long the identity has been associated with a phone number, based on when the ownership was first seen. See also OL, OS, and OU.
P3	The postal code submitted matched the first three digits.
P5	The postal code submitted matched the first five digits.
P6	The postal code submitted matched the first six characters.
P9	The postal code submitted matched the first nine digits.
PM	The address associated with a private mailbox operator (Ex: UPS Store).
PN	Mobile phone number is not active*. The phone number provided is either suspended or deactivated – it cannot place or receive voice calls or SMS text messages transmitted over a cell tower.
PO	The address is a PO Box.
PT	The phone number is currently in a ported state. Any number not currently on its original home carrier will have a PT reason code. This is not indicative of a recent carrier port.
PV	A successful person search verification was run.
R1	The number of identities associated with the phone number has exceeded Signzy's suggested limit. This could be an indication of a higher risk of fraudulent activity.
RA	Raw address (address entered by the consumer) matched better than normalized address.
RL	Phone number is associated with a high-risk line type (Non-Fixed VoIP or Prepaid MVNO)*.
RM	Matching used only raw data (data submitted by the consumer and submitted in the call).
S1	Synthetic identity reason code one – the person identity matched has multiple unique SSNs. This can indicate a higher risk of the identity being synthetic.
S2	Synthetic identity reason code two – the person identity matched has multiple DOB records. This can indicate a higher risk of the identity being synthetic.
S3	Synthetic identity reason code three – the person identity matched has many relatives with the same/similar name. This may indicate the identity is synthetic.
S4	Synthetic identity reason code four – the person identity matched has an SSN issued before either the submitted DOB or—if no DOB was submitted—the selected person identity’s DOB. This can indicate a higher risk of the identity being synthetic.
UV	Unable to verify address
VA	The address is vacant (unoccupied in the past 90 days).

Sample Error

{
    "error": {
        "name": "error",
        "message": "..message..",
        "status": 400,
        "reason": "BadRequest",
        "type": "OK",
        "statusCode": 200
    }
}

Error Response Parameters

Parameters	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]. We strive to provide prompt and reliable assistance, ensuring your queries are addressed effectively.

We value your feedback and are committed to making your experience smooth and enjoyable. Our team is dedicated to assisting you with any needs you may have. Thank you for choosing our services. We look forward to helping you!