Identity Verify - Advance
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, full SSN (or last four digits of SSN), date of birth (DOB), and driver's license number and state.
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.
Identity Verify provides phone ownership verification using the phone number status + the name & address information, or SSN, 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.
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.
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 | Either phoneNumber or payfoneAlias is required, not both. | The phone number being queried. (without leading plus sign & country code) |
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 | 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 | CountryCode for which details are being verified. Possible values for now includes "US" & "CA". |
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). |
last4 | string | Optional | The last four digits of the social security number associated with the subscriber. |
ssn | string | Optional | The social security number associated with the subscriber. |
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. |
driversLicenseNumber | string | Optional | 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 | Optional | The driver's license state associated with the phone number being queried. Must be in the 2-character postal abbreviation. |
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 (last4 of SSN, full SSN, date of birth, driver's license number, and state)
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
- either
to return a successful response; otherwise, an error is returned. However, the more fields included for name, address, and SSN, 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 equal to 100 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.
SSN and Last4 Matching If a ssn (or last4) was submitted, but neither name field was submitted, the name and address matching is not enabled, and matching is performed only using the SSN/last 4 with the following logic:
- If the ssn/last4 submitted matches the data found, verified returns true
- If the ssn/last4 submitted information does not match the data found, verified returns false
See the Identity Verify Flows section for diagrams of each situation.
The rest of the request and response parameters (date of birth, driver's license, 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.
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. |
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. |
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.
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.
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.
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 |
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). |
XD | No driver's license data is available to match to submitted driver's license 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!