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