Identity Fetch

Introduction

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.

Features

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.

Fields that Signzy can Autofill

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.

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/ssn-fetch' \
--header 'Content-Type: application/json' \
--header 'Authorization: <auth-token>' \
--data '{
 "consentStatus": "optedIn",
    "phoneNumber": "<phone number>", 
    "dob": "<date of birth>", 
    "numberOfAddresses": "<number of addresses>", 
    "numberOfEmails": "<number of emails>", 
    "ssn": "<ssn>", 
    "last4": "<last 4 digits of ssn>", 
    "trustScore": "<trust score>"
}'

curl --location --request POST 'https://api-preproduction.signzy.us/api/v3/us-kyc/ssn-fetch' \
--header 'Authorization: <auth-token>' \
--header 'Content-Type: application/json' \
--data '{
 "consentStatus": "optedIn",
    "phoneNumber": "<phone number>", 
    "dob": "<date of birth>", 
    "numberOfAddresses": "<number of addresses>", 
    "numberOfEmails": "<number of emails>", 
    "ssn": "<ssn>", 
    "last4": "<last 4 digits of ssn>", 
    "trustScore": "<trust score>"
}'

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

Response Body Parameters

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.

Sample Response

{
  "requestId": "7f83-b0c4-90e0-90b3-11e10800200c9a66",
  "status": 0,
  "description": "Success.",
  "response": {
    "transactionId": "163657716",
    "phoneNumber": "13478035027",
    "lineType": "Mobile",
    "carrier": "Verizon",
    "countryCode": "US",
    "reasonCodes": [
      "PT"
    ],
    "individual": {
      "firstName": "Jack",
      "lastName": "Frost",
      "addresses": [
        {
          "address": "123 Main Street",
          "extendedAddress": "Apt. 2B",
          "city": "San Francisco",
          "region": "CA",
          "postalCode": "94015-2645"
        }
      ],
      "emailAddresses": [
        "[email protected]"
      ],
      "ssn": "1234567890",
      "dob": "1981-06-27"
    }
  }
}

Reason Codes

Reason Code	Description
AC	The normalized address was used to complete empty address fields before the match.
AU	The address was classified as undeliverable.
BA	The address was a business address.
BL	The number is associated with a business line.
C2	2 identities that have OS or OV reason codes. OS or OV indicates short ownership tenure.
C3	3 identities that have OS or OV reason codes. OS or OV indicates short ownership tenure.
C4	4 identities that have OS or OV reason codes. OS or OV indicates short ownership tenure.
C5	5 or more identities that have OS or OV reason codes. OS or OV indicates short ownership tenure.
CA	Common addresses appearing across multiple seemingly unrelated identities associated with the phone number. This may indicate an increased risk of fraudulent activity.
CF	The address matches the address of a U.S. correctional facility.
CN	The first and last names were combined in one field.
DA	The address was found to have a dual address (Ex: 123 Main St PO Box 99).
DI	The data returned a death indicator.
DT	The data retrieval timed out.
FN	Family name found and used in matching.
HR	High-rise; the address contains apartment or building sub-units.
IA	Inactive address, such as new developments having addresses but being inactive until somebody moves in. Or, after Hurricane Katrina, addresses in the affected area were marked as inactive for a time.
LA	This address was classified as a low-tenure address.
MA	The address in the request was associated with multiple active addresses.
MI	The address was classified as a military address.
NA	The address was valid and normalized before calculating the match score.
NC	Name and address information was not available.
ND	Network Status information was not available.
NM	The line type was not mobile.
NN	Nickname found and used in matching. For example, Bill matches with William.
NO	The input identity was verified (verified=true). Newer ownership (identity) was recently associated with the phone number used in establishing the verification.
NP	The line was classified as non-personal.
NS	The first and last names were swapped.
NU	The phone number was updated.
OD	The ownership of the phone number was found before a disconnect date.
OL	Ownership tenure is greater than 45 days.
OO	Input identity was verified (verified=true). The connection of the ownership or association to this phone number was not recent (greater than five years). However, no known newer ownership or association was found (“older” ownership).
OS	Short ownership tenure (8–45 days).
OU	Ownership tenure was unknown; date attributes associated with the phone number were unavailable.
OV	Ownership tenure is less than seven days.
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. Applicable to Canadian phone numbers only.
P9	The postal code submitted matched the first nine digits.
PM	The address was associated with a private mailbox operator (Ex: UPS Store).
PN	The phone number was not active.
PO	The address was classified as a PO Box.
PT	The phone number was in a ported state (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 exceeded the suggested limit, which may indicate higher fraud risk.
RA	The raw address matched better than the normalized address.
RL	The phone number was associated with a high-risk line type (Non-Fixed VoIP or Prepaid).
RM	Matching used only raw data.
S1	Synthetic identity: multiple unique SSNs. May indicate higher risk of synthetic identity.
S2	Synthetic identity: multiple DOB records. May indicate higher risk of synthetic identity.
S3	Synthetic identity: high number of relatives with same/similar name. May indicate higher risk of synthetic identity.
S4	Synthetic identity: SSN issued before submitted DOB or identity’s DOB. May indicate higher risk of synthetic identity.
UV	The address could not be verified.
VA	The address was vacant (unoccupied in the past 90 days).
XD	No driver’s license data was available to match the submitted parameters.
KA	Ownership tenure is between 8 and 14 days.
KB	Ownership tenure is between 15 and 21 days.
KC	Ownership tenure is between 22 and 30 days.
KD	Ownership tenure is between 31 and 45 days.
KE	Ownership tenure is between 46 and 60 days.
KF	Ownership tenure is between 61 and 90 days.
KG	Ownership tenure is between 91 and 120 days.
KH	Ownership tenure is between 121 and 150 days.
KI	Ownership tenure is between 151 and 180 days.
KJ	Ownership tenure is between 181 and 365 days.
KK	Ownership tenure is between 366 and 730 days.
KL	Ownership tenure is between 731 and 1095 days.
KM	Ownership tenure is between 1096 and 1460 days.
KN	Ownership tenure is between 1461 and 1825 days.
KO	Ownership tenure is greater than 1826 days.

Sample Error

{
  "error": {
     "name": "error",
     "message": "Bad Input and description ",
     "status": 400,
     "reason": "VALIDATION_ERROR",
     "type": "Bad Request",
     "statusCode": 400
  }
}

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

Error Response Parameters

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!