Identity Fetch

9 min

Introduction

The "Identity Fetch" API allows you to retrieve Personally Identifiable Information (PII) data associated with a phone number, based on the provided consent and additional details. This API provides access to valuable information such as the subscriber's name, address, email addresses, social security number (SSN), and more. By integrating this API into your system, you can enhance your KYC processes and make informed decisions based on the retrieved PII data.

How to call the API

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.

API Input Guidelines

Need to pass the following information. Atleast one of last4ssn or nationalId is required.

phoneNumber
last4ssn
nationalId
scopedFields

Sample cURL

Production

curl --location --request POST 'https://api.signzy.app/api/v3/idv/ssn-fetch' \
--header 'Authorization: <auth-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "phoneNumber": "<phone number>",
    "last4ssn":"<last 4 digits of ssn>",
    "nationalId":"<national ID>",
    "scopedFields": [
        "address",
        "firstName"
    ]
}'

Input Parameters

Key	Type	Mandatory	Description
requestId	string	true	Unique identifier associated with this request. This identifier must be unique for each transaction.
consentStatus	string	true	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	true	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, partial SSN, or full SSN.	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, partial SSN, or full SSN.	Last four digits of the social security number associated with the phone number.
numberOfAddresses	string	false	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	false	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	false	Internal use only: When set to "true", the Trust Score is called.

Response Parameter

Key	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	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.
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"
    }
  }
}

Sample Error

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

PARAMETER NAME	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].