Identity Fetch
Signzy's Identity Fetch API leverages the power of phones and phone numbers to modernize onboarding experiences by delivering authenticated digital identities and verified data to supercharge application velocity while mitigating identity fraud.
The Identity Fetch workflow utilizes all of our data sources to more accurately and quickly fill out the necessary information for your consumer to complete their application by using the phone number and another consumer identifier (date of birth or SSN(full or last 4 digits)).
By integrating this API into your system, you can enhance your KYC processes and make informed decisions based on the retrieved PII data.
Identity Fetch API Leverages our “PRO” model of identity verification:
- Possession–Confirm possession of the phone with “something-you-have” authentication.
- Reputation–Screen for risk to ensure the phone being used to authenticate is not compromised or used by a bad actor.
- Ownership–Verifying the phone number associated with the rightful owner or actual consumer.
These three steps provide 2-factor authentication (2FA) before Identity Fetch, outlined below.
This API is designed to integrate into whatever user experience you determine, and Signzy does not control the experience or the user interface of your users' screens. The process below simply outlines the Identity Fetch APIs and how they're recommended to fit.
First Factor of Authentication
Possession should first be confirmed using the Send Link & Check Link Status as an authenticator. This is the “something-you-have” check, ensuring the person filling out the form has possession of the phone and is not a bad actor who merely knows the phone number.
Your environment (native app or mobile/web browser) collects the phone number from the consumer (through a web form or your customer records) for an Instant Link authentication, which returns the authentication result in the response.
Once possession has been checked with a successful respone of Instant Link, you should then make a Trust Score call to confirm Reputation & see if that particular phone number is eligible to attempt Pre-Fill. This check will return a Trust Score, a numerical score identifying the trustworthiness of phone numbers based on historical and real-time reputation data parameters like line type and tenure.
You must determine the passing criteria for the Trust Score endpoint to determine if the user is eligible for Indentity Fetch. The scores range from 0 to 1000 with a threshold of 630 or greater being Signzy’s best practice recommendation. For more information, see the reference documentation for more details on input parameters.
Second Factor of Authentication
If the Trust Score passes your required threshold, then Identity Fetch API can be called to fill in the consumer’s identity elements to your form, and the application can then be finished and submitted.
You need to determine when this is the case and which challenge question you’re going to issue to the consumer:
- SSN
- the last four digits of the SSN
- DOB At least one of the above parameters is required to return the full SSN and DOB data in the response and ensure the correct person is auto-filled. You should select which parameter to use based on information typically requested from your consumers.
When Send Link API is used as the possession check, challenge data of the SSN or DOB should be prompted along with the phone number for the initial Instant Link request. That way, that data is already available for the Identity Fetch API call.
If the minimum Trust Score was not met or Identity Fetch API does not return PII (incorrect challenge data, or no data available), you should send the consumer through an exception or manual process (which may include a manual form, review process, doc scan, etc.). You can then use a Identity Verify - Advance API to authenticate submitted PII. If this verification fails as well, a PRO-step-up verification or manual review might be needed.
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 | Yes | The phone number being queried. Formatted in E.164 formatting for international numbers, including the leading plus sign. |
dob | string | In order to access DOB and SSN data for a phone number, you must supply in the request the DOB or SSN (partial or full | Date of birth associated with the phone number. It can be in ISO 8601 format for full DOB (YYYY-MM-DD), month and year (MM/YYYY), or month and day (MM/DD). |
ssn | string | In order to access DOB and SSN data for a phone number, you must supply in the request the DOB, partial SSN, or full SSN. | The social security number associated with the phone number (#########). |
last4 | string | In order to access DOB and SSN data for a phone number, you must supply in the request the DOB or SSN (partial or full) | Last four digits of the social security number associated with the phone number. |
numberOfAddresses | string | Optional | The desired number of addresses to return. The default and recommended amount is 3; requesting more could affect your service level. The maximum possible value is 10. |
numberOfEmails | string | Optional | The desired number of email addresses to return. The default and recommended amount is 3; requesting more could affect your service level. The maximum possible value is 10. |
trustScore | string | Optional | Internal use only: When set to "true", the Trust Score is called.
|
Parameter | Data Type | Description |
|---|---|---|
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 | 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 associated with the subscriber. |
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. |
reasonCodes | string[] | An array of indicators providing additional context about the transaction. See Reason Codes Reference Information for detailed reason codes. |
individual | object | An object representing individual information associated with the phone number. |
firstName | string | The first name of the individual associated with the phone number. |
lastName | string | The last name of the individual associated with the phone number. |
addresses | object[] | An array of objects representing addresses associated with the individual. |
address | string | The primary address line. Usually populated. |
extendedAddress | string | The secondary address line. Populated for suites, apartments, boxes, departments, etc. |
city | string | The city where the address is located. |
region | string | The region or state where the address is located. |
postalCode | string | The postal/zip code of the address. The default is a 9 digit zip code separated by a dash, but it is possible only a 5 digit code will be returned. |
emailAddresses | string[] | An array of email addresses associated with the individual. This is a premium data field; if you are interested in access, please speak with your account manager. |
ssn | string | The social security number associated with the phone number. |
dob | string (YYYY-MM-DD) | The date of birth associated with the phone number in YYYY-MM-DD format. |
Reason Code | Description |
|---|---|
CF | The address matches the address of a U.S. correctional facility. Only returned if one address is returned; if multiple are returned, the reason code doesn’t fire. |
NO | Input identity has been verified (verified=true). Newer ownership (identity) was recently associated with the phone number used in establishing the verification. See also code OO. |
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 | 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. |
Parameter | 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!