US KYB V1

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 jurisdiction state ) 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 v1' \\ \ 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>" ] } } }'curl location 'https //api signzy us/api/v3/global kyb/us v1' \\ \ 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>" ] } } }' request body parameters parameter type description required topn string number of top matching results to return each returned match will have a match confidence at least as high as the provided matchthreshold recommended to keep between 1 to 10 the default value is 1 no matchthreshold string similarity threshold for matches (0 0–1 0) the default value is 0 5 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 200 cases { "result" { "responseid" "\<responseid>", "risksummary" { "legalexistenceriskrating" "\<legalexistenceriskrating>", "activityriskrating" "\<activityriskrating>", "tasks" \[ { "taskname" "\<taskname>", "status" "\<status>", "result" "\<result>", "reason" "\<reason>" } ] }, "data" { "bestmatch" { "matchconfidence" "\<matchconfidence>", "matchedfields" { "name" "\<name>", "address" { "state" "\<state>" } } }, "legalentities" \[ { "legalentitytype" "\<legalentitytype>", "signzyid" "\<signzyid>", "formationdate" "\<formationdate>", "matchconfidence" "\<matchconfidence>", "matchedfields" { "name" "\<name>", "address" { "state" "\<state>" } }, "registrations" \[ { "issuedate" "\<issuedate>", "filenumber" "\<filenumber>", "registrationstate" "\<registrationstate>", "registeredname" "\<registeredname>", "persons" \[ { "name" "\<name>", "titles" \[ "\<title1>" ] } ], "addresses" \[ { "streetaddress1" "\<streetaddress1>", "streetaddress2" "\<streetaddress2>", "city" "\<city>", "state" "\<state>", "postalcode" "\<postalcode>", "country" "\<country>", "type" "\<type>" } ] } ] } ], "brands" \[ { "signzyid" "\<signzyid>", "matchconfidence" "\<matchconfidence>", "matchedfields" { "name" "\<name>", "person" "\<person>", "address" { "streetaddress1" "\<streetaddress1>", "city" "\<city>", "state" "\<state>", "postalcode" "\<postalcode>" } }, "datasources" \[ "\<datasource1>" ], "activities" { "compliancerisklevel" "\<compliancerisklevel>", "activitytypes" \[ "\<activitytype1>" ] }, "names" \[ { "name" "\<name>" } ], "addresses" \[ { "streetaddress1" "\<streetaddress1>", "streetaddress2" "\<streetaddress2>", "city" "\<city>", "state" "\<state>", "postalcode" "\<postalcode>", "country" "\<country>", "type" "\<type>" } ], "websites" \[ "\<website1>" ], "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 risksummary object aggregated risk assessment including existence/activity and verification tasks data object core matched entity and brand data risksummary details field type description legalexistenceriskrating string risk rating indicating confidence that the entity legally exists activityriskrating string risk rating for the entity’s observable activity (e g , compliance concerns) tasks array of objects individual verification steps (equivalent to prior verificationtasks) risksummary tasks details field type description taskname string name of the verification step the unique identifier for the task status string outcome status of that task (e g , success, failure) result string specific result type (e g , exact match, approximate match) reason string explanation or rationale for the result data details field type description bestmatch object top candidate match found for the input legalentities array of objects matched legal entity records brands array of objects matched brand level records associated with the entity bestmatch details field type description matchconfidence number confidence score for the best match matchedfields object input fields that contributed to the match bestmatch matchedfields details field type description name string matched entity name address state string state component of the matched address person string matched person associated with the best match legalentities details field type description legalentitytype string category/type of legal entity (e g , corporation, llc, etc ) signzyid string internal identifier for the legal entity formationdate string iso formatted formation/incorporation date matchconfidence number confidence score for this entity being the correct match matchedfields object input fields that matched this entity registrations array of objects registration filings associated with the entity legalentities matchedfields details field type description name string matched name for that legal entity address state string state in the matched address person string matched person linked to that entity legalentities registrations details field type description issuedate string issue date of the corporate registration filing filenumber string file number of the corporate registration filing of the business registrationstate string two letter state code of the us state where the corporate registration was filed registeredname string business name as filed on the corporate registration filing persons array of objects people (officers, agents, etc ) on that filing addresses array of objects addresses associated with that registration legalentities registrations persons details field type description name string person’s name titles array of strings roles or titles held in that record legalentities registrations addresses details field type description streetaddress1 string primary street address line streetaddress2 string secondary street address line city string city of the address state string state of the address postalcode string postal or zip code country string country (if provided) type string address type (e g , headquarters, registered agent, officer) brands details field type description signzyid string internal identifier for the brand matchconfidence number confidence score for the brand match matchedfields object input fields that contributed to the brand match datasources array of strings sources used to derive brand information activities object compliance/activity metadata for the brand names array of objects alternate or recorded brand names addresses array of objects addresses tied to the brand websites array of strings domains or urls associated with the brand industries array of objects industry classification entries for the brand brands matchedfields details field type description name string matched brand name person string person associated with the brand match address streetaddress1 string street line of the matched address address city string city of the matched address address state string state of the matched address address postalcode string postal code of the 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 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!