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

Sample Error

{
    "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!