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 p ossession–confirm possession of the phone with “something you have” authentication r eputation–screen for risk to ensure the phone being used to authenticate is not compromised or used by a bad actor o wnership–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 docid\ xh0ih8sp9lyz2dqkl7ra1 & check link status docid\ ykkmvx0mczcype urtyhm 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 docid\ bs96ldc 5qhahajfgampo 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 docid\ xh0ih8sp9lyz2dqkl7ra1 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 docid\ fy0n2qiekgxxltw0vnfuy 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 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" \[ "test\@test1 com" ], "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 400 (bad request) { "error" { "name" "error", "message" "bad input and description ", "status" 400, "reason" "validation error", "type" "bad request", "statuscode" 400 } } 401(unauthorized) { "error" { "name" "error", "message" "invalid authentication credentials", "status" 401, "reason" "authentication error", "type" "bad request", "statuscode" 401 } } 403 (forbidden) { "error" { "name" "error", "message" "forbidden", "reason" "error", "type" "bad request", "statuscode" "403" } } 500 (internal server error) { "error" { "name" "error", "message" "internal server error", "status" 500, "reason" "error", "type" "bad request", "statuscode" 500 } } 409(upstream down { "error" { "name" "error", "message" "upstream down", "status" 409, "reason" "error", "type" "bad request", "statuscode" 409 } } { "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 help\@signzy com 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!