Identity Verify - Advance

introduction the identity verify api (“identity verify”) enables you to verify an individual consumer’s identity using a phone first approach that validates consumer provided personal identifying information (pii) and confirms ownership of their phone number using authoritative data, including device and phone number tenure data this is a critical step in ensuring your important consumer interactions are with the phone number owner and information, helping eliminate bad actors and prevent fraudulent accounts signzy performs ownership verifications without ever storing your consumers' pii ownership verification goes beyond just matching a person's name and address; inputs that can be included for matching in the api request are name, address, full ssn (or last four digits of ssn), date of birth (dob), and driver's license number and state the api's verified flag and matching details can help with customer onboarding (acquisitions, originations, registrations, etc ) and servicing (e g , your customer adds a new phone number to their profile) and enhances user experience `` by utilizing this api, you can ensure the integrity of the user's identity information and make informed decisions based on the verification results features phone number ownership verification identity verify provides phone ownership verification using the phone number status + the name & address information, or ssn, to then determine a verified status of true or false you start by querying the phone number, locating the relevant information associated with the identity recognized behind the phone number, and then matching appropriate fields against your consumer's submitted data 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/idv advance' \\ \ header 'content type application/json' \\ \ header 'authorization \<auth token>' \\ \ data '{ "consentstatus" "optedin", "phonenumber" "19177253169", "ssn" "602410869", "firstname" "hanson", "lastname" "kerner", "address" "761 shasta place", "city" "fort lauderdale", "region" "il" "postalcode" "33355", "countrycode" "us", "dob" "1990 02 21", "emailaddress" "abc\@gmail com", "driverslicensenumber" "123abc", "driverslicensestate" "il" "details" "true" }'curl location 'https //api preproduction signzy us/api/v3/us kyc/idv advance' \\ \ header 'content type application/json' \\ \ header 'authorization \<auth token>' \\ \ data '{ "consentstatus" "optedin", "phonenumber" "19177253169", "ssn" "602410869", "firstname" "hanson", "lastname" "kerner", "address" "761 shasta place", "city" "fort lauderdale", "region" "il" "postalcode" "33355", "countrycode" "us", "dob" "1990 02 21", "emailaddress" "abc\@gmail com", "driverslicensenumber" "123abc", "driverslicensestate" "il" "details" "true" }' request body parameters parameter data type required description consentstatus string required 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 required the phone number being queried (without leading plus sign & country code) firstname string required first name associated with the phone number being queried lastname string required last name associated with the phone number being queried address string optional the address number and street associated with the phone number being queried city string optional the city associated with the phone number region string optional the region (or state abbreviation) associated with the phone number postalcode string optional the postal code associated with the phone number countrycode string required countrycode for which details are being verified possible values for now includes "us" & "ca" dob string optional date of birth associated with the phone number accepts different formats iso 8601 (yyyy mm dd), month and year (mm/yyyy), or month and day (mm/dd) last4 string optional the last four digits of the social security number associated with the subscriber ssn string optional the social security number associated with the subscriber emailaddress string optional email associated with the phone number details string optional set to "true" to access premium data responses when set to true, only query parameters with valid string values are returned in the response if a parameter is not provided in the request, it will be omitted from the response driverslicensenumber string optional the driver's license number associated with the phone number and person being queried special characters such as " " or " " can be included and do not affect matching driverslicensestate string optional the driver's license state associated with the phone number being queried must be in the 2 character postal abbreviation consumer input parameters regardless of whether details are returned or not, a match score is generated for the following pii data elements name (first name, last name, name score) address (street number, street, city, region, postal code, distance, address score) boolean values can be generated for the following pii data elements identifiers (last4 of ssn, full ssn, date of birth, driver's license number, and state) the fields you implement for your identity verify calls should reflect the typical personal information you request from your consumers at minimum , however, the request needs to include the phone number either to return a successful response; otherwise, an error is returned however, the more fields included for name, address, and ssn, the more reliable the verification result when the api request is sent, if signzy finds no data for the person, verified returns false, and a reason code of nc is returned, indicating no name and address information associated with the phone number the consumer should then be put through your organization's step up procedure if data is found for the person, the data matching process is enabled and performed for the available fields as outlined in the scoring and matching framework section below score and matching framework signzy checks the information submitted through the identity verify api, only matching information submitted using our proprietary logic you're able to see the details of the resulting matching and scores in your responses by including the details parameter as true in the request name and address matching match results for the name and address fields are calculated with weighted algorithms to generate a score for each; the weight applied is influenced by how much variance was found between submitted data and queried data (e g , which fields returned true/false, etc ) these calculations then return a unique total score for the name matching and (if the information is submitted) a unique total score for the address matching; each can fall between 0–100 these scores contribute to the verification of the end user with the following logic either a namescore greater than or equal to 70 or an addressscore equal to 100 contributes to verified returing true both name and address scores failing the above thresholds contribute to verified returning false name and address matching notes name matching takes into account nicknames first/last name transposition name contained within those with changed last name due to marriage mother and father's name concatenated or split within middle and last name fields fuzzy match logic extended address data can be submitted to support the many address forms with additional lines for apartment numbers, etc , but this data is not factored into address matching logic reason codes are returned when these matching elements come into play ssn and last4 matching if a ssn (or last4) was submitted, but neither name field was submitted, the name and address matching is not enabled, and matching is performed only using the ssn/last 4 with the following logic if the ssn/last4 submitted matches the data found, verified returns true if the ssn/last4 submitted information does not match the data found, verified returns false see the identity verify flows section for diagrams of each situation the rest of the request and response parameters (date of birth, driver's license, etc ) are simply informational, returning true or false (if details is set to true, see the detailed response section) to help you confirm submitted data and not contribute to the verified response identity verify flows response body parameters parameter data 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 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(s) associated with the individual 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 verified boolean the result of the transaction request indicating whether the identity information is verified address object the address object containing address details streetnumber integer a score of the address input (minus the extendedaddress); values 1 to 100 100 indicates an exact match street boolean the results of the street name match city boolean the results of the city match region boolean the results of the region (state abbreviation) match postalcode boolean the results of the postal/zip code match distance float the distance value—in miles—between the address in input and the normalized address on file addressscore integer an overall address score that uses all the address attributes to generate the overall score; values 1 to 100 100 indicates an exact match name object the name object containing name details firstname integer a score of the first name match; values 1 to 100 100 indicates an exact match lastname integer a score of the last name match; values 1 to 100 100 indicates an exact match namescore integer an overall name score that uses both the first and last name scores to generate the overall score values 1 to 100 100 indicates an exact match identifiers object the identifiers object containing identifier details last4 boolean the results of the last 4 of ssn match dob boolean the results of the date of birth match driverslicensestate boolean the results of the driver’s license state match driverslicensenumber boolean the results of the driver’s license number match email object the email object containing email details emailaddress boolean the results of the email match reasoncodes string\[] an array of indicators providing additional context about the transaction if a death indicator was found in the matching data for the person submitted, verified returns false, and a di reason code is returned in the response as well see the reason codes section for more information on identity verify reason codes detailed response there is a critical query parameter to explain first details it's set by default to false, but if you determine you want to receive the matching outcome for the various pii inputs of your consumer, it should be set to true the api response then includes a field level breakdown of the matching and score results, which can add visibility to the verification decision when left to false, you only receive the overall verified result sample response (details = true) { "result" { "requestid" "6466555fa90017ffa26ebba0", "status" 0, "description" "success ", "response" { "verified" true, "transactionid" "12225155440", "payfonealias" "60a37e2c4vkrkkx4d3fd70cee16c05afa0mek1a51jd9p396647cb4c454f4dc26a7202ba66e04e2f9f6g30f557a4cd71d054fb417ee475b03404d02bf", "phonenumber" "19177253169", "linetype" "mobile", "carrier" "t mobile usa", "countrycode" "us", "name" { "firstname" 100, "lastname" 100, "namescore" 100 }, "address" { "streetnumber" 100, "street" false, "city" true, "postalcode" true, "distance" 0, "addressscore" 100 }, "identifiers" { "ssn" true }, "identifiers" { "dob" true }, "reasoncodes" \[ "ou", "p5", "pt", "rm", "uv" ] } } } sample response (details = false) { "result" { "requestid" "6466555fa90017ffa26ebba0", "status" 0, "description" "success ", "response" { "verified" true, "transactionid" "12225155440", "payfonealias" "60a37e2c4vkrkkx4d3fd70cee16c05afa0mek1a51jd9p396647cb4c454f4dc26a7202ba66e04e2f9f6g30f557a4cd71d054fb417ee475b03404d02bf", "phonenumber" "19177253169", "linetype" "mobile", "carrier" "t mobile usa", "countrycode" "us", "dob" "1990 02 21", "reasoncodes" \[ "ou", "p5", "pt", "rm", "uv" ] } } only parameters submitted in the request return in a detailed response for example, if city was not included in the address fields for the request, there is no matching performed for that field, and that field is excluded from the response reason codes along with the scores, signzy supplies reason code(s) in the response that gives further insight into why a particular score was returned or indicates the risk associated with the identity this is to assist you in making informed decisions for managing your risk the following reason codes can be returned for all versions of the identity verify api reason code description ac the normalized address was used to complete empty address fields before the match au address undeliverable ba business address cf the address matches the address of a u s correctional facility cn first and last names (or multiple names) combined in one field da dual address (ex 123 main st po box 99) di death indicator found on data dt data retrieval timeout fn the family name is considered in the overall calculation hr high rise; address contains apartment or building sub units ia inactive address (examples new developments may have addresses but will be "inactive" until somebody moves in or, after hurricane katrina, addresses in the affected area were marked inactive for a time ) la low tenure address ma the address submitted in the request is associated with multiple active addresses; e g , the address might be missing a suite or apartment number to specify the necessary active address mi military address na the address is valid and has been normalized before calculating the match score nc name and address information is not available nd phone number network status information is not available while this may mean no data is available, this may not necessarily indicate risk nm not a mobile line type it may not indicate risk but is intended to filter mobiles from non mobile line types nn nickname found and used in matching for example, bill matches with william no input identity has been verified (verified=true) newer ownership or association has recently been connected to the phone number see also reason code oo np non personal line; could signify a business or government phone line ns names were swapped (first/last) nu the phone number has been updated 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 input identity has been verified (verified=true) 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 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 p9 the postal code submitted matched the first nine digits pm the address associated with a private mailbox operator (ex ups store) pn mobile phone number is not active the phone number provided is either suspended or deactivated – it cannot place or receive voice calls or sms text messages transmitted over a cell tower po the address is a po box pt the phone number is currently in a ported state any number not currently on its original home carrier will have a pt reason code this is 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 has exceeded signzy's suggested limit this could be an indication of a higher risk of fraudulent activity ra raw address (address entered by the consumer) matched better than normalized address rl phone number is associated with a high risk line type (non fixed voip or prepaid mvno) rm matching used only raw data (data submitted by the consumer and submitted in the call) s1 synthetic identity reason code one – the person identity matched has multiple unique ssns this can indicate a higher risk of the identity being synthetic s2 synthetic identity reason code two – the person identity matched has multiple dob records this can indicate a higher risk of the identity being synthetic s3 synthetic identity reason code three – the person identity matched has many relatives with the same/similar name this may indicate the identity is synthetic s4 synthetic identity reason code four – the person identity matched has an ssn issued before either the submitted dob or—if no dob was submitted—the selected person identity's dob this can indicate a higher risk of the identity being synthetic uv unable to verify address va the address is vacant (unoccupied in the past 90 days) xd no driver's license data is available to match to submitted driver's license parameters sample error { "error" { "name" "error", "message" " message ", "status" 400, "reason" "badrequest", "type" "ok", "statuscode" 200 } } error response parameters parameters 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 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!