US KYB V2

introduction signzy's kyb apis are built to perform a know your business (kyb) check on a business it queries dataset of legal entities, which are based on authoritative business data sets, including official state records kyb and identity attributes are a family of attributes that are used to help financial institutions onboard and monitor their clients over time to meet know your business (kyb) regulations methodology and match precision the kyb endpoint has industry leading registration filing fill rates this is because signzy is able to successfully resolve operating names and addresses with legal names and addresses, tying websites, legal entity information, and operating information together this enables accurate, high coverage registration filing return rates because any combination of inputs can be combined to return a high match rate typically, signzy automatically surfaces registration filings on over 80% of customer sample records signzy covers registrations for all 52 states and jurisdictions (including washington d c and puerto rico) as of august 2024, signzy has information on more than 114 million registration filings, including 48 million known active registrations packages choose from two packages for the attributes you need to confidently transact with new customers us kyb v1 for validating basic business identity information to reduce risk when onboarding new customers if a user selects the "v1" package, they will receive the following child attributes from the registration file number, registered name, addresses, persons, issue date, and registration state (i e , all child attributes except status related attributes and jurisdiction type / home jurisdictionstate ) us kyb v2 for verifying businesses to satisfy more roubst know your business (kyb) requirements when onboarding new customers if a user selects the "v2" package, they will receive all child attributes for the registration the inputs (e g business name, address, etc ) to make a request to the api are the same for the two packages api details request body curl location 'https //api preproduction signzy us/api/v3/global kyb/us v2' \\ \ header 'authorization < auth token >' \\ \ header 'content type application/json' \\ \ data raw '{ { "topn" "\<topn>", "matchthreshold" "\<matchthreshold>", "data" { "names" \[ "\<name1>", "\<name2>" ], "addresses" \[ { "streetaddress1" "\<streetaddress1 1>", "streetaddress2" "\<streetaddress2 1>", "city" "\<city 1>", "state" "\<state 1>", "postalcode" "\<postalcode 1>" }, { "streetaddress1" "\<streetaddress1 2>", "streetaddress2" "\<streetaddress2 2>", "city" "\<city 2>", "state" "\<state 2>", "postalcode" "\<postalcode 2>" } ], "persons" \[ { "firstname" "\<firstname>", "lastname" "\<lastname>" } ], "websites" \[ "\<website1>" ], "callbackurl" "callbackurl", "reportrequest" "true"/"false" } } }'curl location 'https //api signzy us/api/v3/global kyb/us v2' \\ \ header 'authorization < auth token >' \\ \ header 'content type application/json' \\ \ data raw '{ { "topn" "\<topn>", "matchthreshold" "\<matchthreshold>", "data" { "names" \[ "\<name1>", "\<name2>" ], "addresses" \[ { "streetaddress1" "\<streetaddress1 1>", "streetaddress2" "\<streetaddress2 1>", "city" "\<city 1>", "state" "\<state 1>", "postalcode" "\<postalcode 1>" }, { "streetaddress1" "\<streetaddress1 2>", "streetaddress2" "\<streetaddress2 2>", "city" "\<city 2>", "state" "\<state 2>", "postalcode" "\<postalcode 2>" } ], "persons" \[ { "firstname" "\<firstname>", "lastname" "\<lastname>" } ], "websites" \[ "\<website1>" ], "callbackurl" "callbackurl", "reportrequest" "true"/"false" } } }' request body parameters parameter type description required topn string number of top matching results to return no matchthreshold string similarity threshold for matches (0 0–1 0) no data names array\[string] alternate or alias company names to include in matching yes data addresses array\[object] known addresses to help disambiguate ; state is required no data addresses\[] streetaddress1 string primary street address no data addresses\[] streetaddress2 string secondary address line (suite, apt, etc ) no data addresses\[] city string city of the address no data addresses\[] state string state of the address yes data addresses\[] postalcode string postal code no data persons array\[object] associated person(s) to bias the match no data persons\[] firstname string person's first name no data persons\[] lastname string person's last name; no data websites array\[string] related website(s) or domains for context no data callbackurl string the url to which the system sends the report/notification after processing conditional — required only if reportrequest = "true" datareportrequest string ("true" / "false") indicates whether a report should be generated and sent requires callbackurl when "true" no 200 cases { "result" { "responseid" "\<responseid>", "legalexistenceriskrating" "\<legalexistenceriskrating>", "activityriskrating" "\<activityriskrating>", "verificationtasks" \[ { "taskname" "\<taskname>", "status" "\<status>", "result" "\<result>", "reason" "\<reason>" } ], "bestmatch" { "matchconfidence" "\<matchconfidence>", "matchedfields" { "name" "\<name>", "address" { "state" "\<state>" }, "person" "\<person>" } }, "legalentities" \[ { "signzyid" "\<signzyid>", "formationdate" "\<formationdate>", "legalentitytype" "\<legalentitytype>", "matchconfidence" "\<matchconfidence>", "matchedfields" { "name" "\<name>", "address" { "state" "\<state>" }, "person" "\<person>" }, "datasources" \["\<datasource1>", "\<datasource2>"], "registrations" \[ { "issuedate" "\<issuedate>", "filenumber" "\<filenumber>", "registrationstate" "\<registrationstate>", "registeredname" "\<registeredname>", "jurisdictiontype" "\<jurisdictiontype>", "homejurisdictionstate" "\<homejurisdictionstate>", "standardizedstatus" "\<standardizedstatus>", "registrationstatus" "\<registrationstatus>", "status" { "status" "\<status>", "substatus" "\<substatus>", "statusdetail" "\<statusdetail>" }, "persons" \[ { "name" "\<personname>", "titles" \["\<title1>", "\<title2>"] } ], "addresses" \[ { "streetaddress1" "\<streetaddress1>", "streetaddress2" "\<streetaddress2>", "city" "\<city>", "state" "\<state>", "postalcode" "\<postalcode>", "country" "\<country>", "type" "\<type>" } ] } ] } ], "brands" \[ { "brandid" "\<brandid>", "matchconfidence" "\<matchconfidence>", "matchedfields" { "name" "\<name>", "person" "\<person>", "address" { "street address1" "\<street address1>", "city" "\<city>", "state" "\<state>", "postal code" "\<postal code>" } }, "datasources" \["\<datasource1>", "\<datasource2>"], "activities" { "compliancerisklevel" "\<compliancerisklevel>", "activitytypes" \["\<activitytype1>", "\<activitytype2>"] }, "names" \[ { "name" "\<name>" } ], "addresses" \[ { "streetaddress1" "\<streetaddress1>", "streetaddress2" "\<streetaddress2>", "city" "\<city>", "state" "\<state>", "postalcode" "\<postalcode>", "country" "\<country>", "type" "\<type>" } ], "websites" \["\<website>"], "industries" \[ { "classificationtype" "\<classificationtype>", "classificationcode" "\<classificationcode>", "classificationdescription" "\<classificationdescription>" } ] } ] }, "reason" "\<reason>", "code" "\<code>" } response body parameters top level result object field type description result object main payload containing lookup results and metadata reason string high level reason or message from the service code string status or error code associated with the response result details field type description responseid string unique identifier for this response/request legalexistenceriskrating string risk rating indicating confidence that the entity legally exists activityriskrating string risk rating for the entity's activities (e g , compliance concerns) verificationtasks array of objects list of individual verification steps performed bestmatch object the top candidate match found for the search legalentities array of objects matched legal entity records brands array of objects matched brand level records associated with the entity verificationtasks details field type description taskname string name of the verification step status string current status of that task (e g , completed, pending) result string outcome of the task (e g , match, no match, partial) reason string explanation or detail for the result bestmatch details field type description matchconfidence number confidence score for the best match matchedfields object which input fields contributed to the match bestmatch matchedfields details field type description name string matched name string address object matched address details address state string state portion of the matched address person string matched person (e g , associated individual) legalentities details field type description signzyid string internal identifier for the legal entity formationdate string date the entity was formed/registered legalentitytype string type of entity (e g , llc, corporation) matchconfidence number confidence score for this entity match matchedfields object input fields that matched this entity datasources array of strings source systems or datasets contributing data registrations array of objects registration records (e g , filings, state registrations) legalentities\[] matchedfields details field type description name string matched legal entity name address object address used in matching address state string state component of the matched address person string person associated in the match context legalentities\[] registrations\[] details field type description issuedate string date the registration was issued filenumber string official file/record number registrationstate string jurisdiction/state of the registration registeredname string name under which the entity is registered jurisdictiontype string status of the corporate registration filing (‘foreign’ if any state other than the business's home state, otherwise 'domestic') homejurisdictionstate string home state jurisdiction for the registration two letter abbreviation for the state jurisdiction of the business standardizedstatus (deprecated) string status field indicating whether the registration filing is active or inactive registrationstatus (deprecated) string if available, the official filing status message provided by the state status object structured status details more details below persons array of objects individuals tied to this registration addresses array of objects addresses associated with this registration legalentities\[] registrations\[] status details field type description status string the current registration filing status the status is normalized by signzy based on sos data possible values are active the business registration is active in that state inactive the business registration is inactive in that state unknown the state does not provide business registration status substatus string if available, the normalized sub status of the business possible values are good standing state explicitly states that business is in good standing not good standing missing payments from the business, other poor behavior pending active in the process of becoming truly active pending inactive businesses that are active, but are pending an inactive status unknown the filing status from the state is not clearly in good or bad standing null the filing status is inactive or there is no sub status provided by the state statusdetail string if available, the official filing status message provided by the state e g "in existence" legalentities\[] registrations\[] persons\[] details field type description name string the full name and title of the person (registered officer) associated with the business titles array of strings titles or roles held by the person (e g , director) legalentities\[] registrations\[] addresses\[] details field type description streetaddress1 string primary street address line streetaddress2 string secondary street address line city string city state string state or region postalcode string zip or postal code country string country type string address type (e g , mailing, physical) brands\[] details field type description brandid string identifier for the brand record matchconfidence string (or number) confidence of brand level match matchedfields object fields from input that matched this brand datasources array of strings sources contributing brand data activities object risk/compliance activity metadata names array of objects variants or names associated with the brand addresses array of objects addresses attributed to the brand websites array of strings brand related website urls/domains industries array of objects industry classification details brands\[] matchedfields address details field type description street address1 string primary address line matched for brand city string city of matched address state string state of matched address postal code string postal code of matched address brands\[] activities details field type description compliancerisklevel string risk level assigned based on activity activitytypes array specific types of activities observed or assessed brands\[] names\[] details field type description name string one of the brand’s known names/aliases brands\[] addresses\[] details field type description streetaddress1 string primary street address line streetaddress2 string secondary address line city string city state string state or region postalcode string zip/postal code country string country type string address type brands\[] industries\[] details field type description classificationtype string type/category of industry classification classificationcode string standard code representing the industry classificationdescription string human readable description of the industry get curl for fetching report (if callback fails) curl location 'https //api preproduction signzy us/api/v3/us kyb v2/report status' \\ \ header 'authorization \<auth key>' \\ \ header 'content type application/json' \\ \ data '{"responseid" ""}'curl location 'https //api signzy us/api/v3/us kyb v2/report status' \\ \ header 'authorization \<auth key>' \\ \ header 'content type application/json' \\ \ data '{"responseid" ""}' callback/get curl response 200 cases { "result" { "reporturl" "\<persist url of report>", "responseid" "\<unique id>" }, "code" "\<status code>", "reason" "\<status reason>" } callback/get curl response parameters field type description responseid string unique identifier for the request/response generated by the system reporturl string url from which the generated report/document can be downloaded (ttl for this url is 1 month) reason string message describing the outcome of the request code string status code representing the result of the request (e g , "s001" for success) tasks information tasks are modular building blocks that can be used in a decision making process when reviewing a business a business can have one or more tasks which explain what signzy found in our kyb evaluation process tasks help you understand whether the submitted business is valid and meets your kyb requirements, or if additional investigation is needed task results are based on the data the api returns this means you will only see tasks which are relevant to the data you requested example "tasks" \[ { "taskname" "address verification", "status" "failure", "result" "address not verified", "reason" "we could not match an input address to any identified address" }, ] business name verification the name verification task compares the queried business name(s) to the business names on any matching records we found, and determines whether or not there is a matching name for business name verification, we recommend a default setting where status='success' if your use case calls for more granular decision making, you can use the result field typically, our clients consider approximate matches to the submitted business name to be verified for compliance programs the most common reason for an approximate name match is when a difference is found in the legal suffix between the submitted name and the name we identified (e g ’signzy technologies’ would be considered an approximate match to ‘signzy technologies inc’) task name status result reason verified match name verification success name exact match an input name and a name we identified match exactly ✅ name verification success name approximate match an input name and a name we identified match approximately ✅ name verification failure name not verified we could not match an input name to any identified name sos business name verification the sos name verification task compares the queried business name(s) to the registered names on any matching secretary of state registrations we found, and determines whether the names match or not for sos business name verification, we recommend a default setting where status='success' if your use case calls for more granular decision making, you can use the result field typically, our clients consider approximate matches to the submitted business name to be verified for compliance programs the most common reason for an approximate name match is when a difference is found in the legal suffix between the submitted name and the name we identified (e g ’signzy technologies’ would be considered an approximate match to ‘signzy technologies inc’) task name status result reason verified match sos name verification success name exact match an input name and a name on an sos record match exactly ✅ sos name verification success name approximate match an input name and a name on an sos record match approximately ✅ sos name verification failure name not verified we could not match an input name to any name on an sos record address verification the address verification task compares the queried address(es) to the addresses on any matching record, and determines whether the addresses match or not for address verification, we recommend a default setting where status='success' if your use case calls for more granular decision making, you can use the result field typically, our clients consider approximate matches to the submitted address to be verified for compliance programs the most common reason for an approximate address match is when the submitted address and the address we identified are the same, except one is simply missing a suite number we've seen that this activity is usually just a typo by the end user task name status result reason verified match address verification success address exact match an input address and an address we identified match exactly ✅ address verification success address approximate match an input address and an address we identified match approximately ✅ address verification failure address not verified we could not match an input address to any identified address sos address verification the sos address verification task compares the queried address(es) to the addresses on any matching secretary of state registrations we found, and determines whether the addresses match or not for address verification, we recommend a default setting where status='success' if your use case calls for more granular decision making, you can use the result field typically, our clients consider approximate matches to the submitted address to be verified for compliance programs the most common reason for an approximate address match is when the submitted address and the address we identified are the same, except one is simply missing a suite number we've seen that this activity is usually just a typo by the end user task name status result reason verified match address verification success address exact match an input address and an address on an sos record match exactly ✅ address verification success address approximate match an input address and an address on an sos record match approximately ✅ address verification failure address not verified we could not match an input address to any address on an sos record domestic registration check the domestic registration checks matched company registrations to see whether or not the queried business has a domestic registration in a u s state, and if so, whether it is active only available when jurisdiction and status attributes are included on legal entities' registrations task name status result reason domestic registration success domestic active active domestic filing found domestic registration success domestic unknown domestic filing found but no status provided by state domestic registration failure domestic inactive inactive domestic filing found domestic registration failure domestic not found we found no domestic filing for the business high risk activities information identifies businesses that engage in activities with a high compliance risk full list of activities is below child attributes (and data file structure) activity type response values refer to high risk categories of business activities compliance risk level is ‘ high ’ for all flagged businesses in signzy kyb, which will expand in future iterations to varying levels of risk example "activities" { "compliancerisklevel" "high", "activitytypes" \[ { "activitytype" "cannabis" } ] } coverage businesses we have classified 750k businesses as having high risk activities this includes online only businesses (those without any identifiable physical address) locations we have classified 850k locations as having high risk activities data sources high risk activities is derived from the list of names, websites, and public web descriptions associated with a business via a set of heuristics names and websites are derived from all of signzy's data sources, from card transactions to legal entity registrations methodology signzy looks for keywords through industry descriptions, names, and website urls associated with businesses signzy does not currently look at the content of a website for example, to classify a business as having a high risk activity of "cannabis", signzy looks for key terms within industry descriptions, names, and website urls cannabis, marijuana, dispensary, cbd, thc, ganja why use signzy kyb’s high risk classification? signzy high risk classification improves automated customer onboarding by identifying businesses that engage in activities with a high compliance risk, allowing those businesses to be reviewed manually or follow additional risk assessment processes before onboarding this increases confidence in your organization’s automated onboarding workflow and ensures you’re only bringing on businesses that meet your desired risk standards high risk categories cannabis brick & mortar or online retail stores that primarily sell cannabis/marijuana and related products (thc, cbd, etc ), cannabis/marijuana growers or distributors, and software providers for the cannabis/marijuana industry tobacco and vaping brick & mortar or online retail stores that primarily sell tobacco and vaping products (cigarettes, cigars, e cigarettes) firearms, weapons and ammunition brick & mortar or online retailers that primarily sell guns, firearms, weapons, and ammunition, shooting ranges, or related location adult entertainment and dating dating (online dating sites and applications), adult entertainment clubs (clubs that are primarily strip clubs, gentlemen’s clubs, sex clubs) but not businesses that are primarily just night clubs, adult entertainment retail stores (e g , sex shops, but not other types of stores like lingerie stores), online adult entertainment sites (pornography sites, pay per view chat sites/apps) gambling and sports betting casinos, online gambling sites, sports betting websites and b\&m retail locations, fantasy sports leagues (but not other sports related businesses), bingo halls payments and money transfer payment processors, pos providers, crowdfunding sites, factoring, lending services multi level marketing multi level marketing, pyramid schemes pawn shops, check cashing and payday loans cryptocurrencies and digital assets cryptocurrencies, blockchain, digital assets, digital wallets, crypto/blockchain related infrastructure investments and financing investment brokers, lending instruments legal finance collections agencies, bail bonds gift cards gift card retailers, retail stores that buy unused gift cards, websites whose primary purpose is selling gift cards health and lifestyle diet centers, supplements/nutraceuticals and other products not regulated by the fda, hair extensions prescription drugs pharmacies likely to sell prescription drugs success codes http status code success code description 200 s001 request successful 200 s002 data in process 200 s003 data not found on source 200 s008 data matching the minimum score wasn’t found, though it exists at the source error code and mapping sample error malformatted requestid e001 { "result" {}, "reason" "bad request bad request \<request> is invalid ", "status" "failure", "code" "e001" } requestid not found e401 { "result" {}, "reason" "upstream error", "status" "failure", "code" "e401" } error response parameters parameter description result empty result object reason reason for error status s tatus of the api c ode error code from signzy error codes http status code error code description 400 e001 bad request 401 e1001 unauthorized access 403 e201 forbidden 404 e301 data not found 409 e401 upstream error 429 e501 rate limit exceeded 500 e601 internal server error 503 e701 service unavailable 504 e801 timeout 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!