--- title: US KYB V2 slug: us-apis/us-kyb-v2 description: Learn about the importance of an Employer Identification Numbers (EIN) for businesses and organizations in the US. Discover the EIN Verification API, a tool that validates the accuracy of EINs against official records. Explore practical examples of its ap docTags: createdAt: 2023-09-01T07:10:06.587Z --- ## 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 ::::Tabs :::Tab{title="Pre-Production"} ```curl 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": "", "matchThreshold": "", "data": { "names": [ "", "" ], "addresses": [ { "streetAddress1": "", "streetAddress2": "", "city": "", "state": "", "postalCode": "" }, { "streetAddress1": "", "streetAddress2": "", "city": "", "state": "", "postalCode": "" } ], "persons": [ { "firstName": "", "lastName": "" } ], "websites": [ "" ], "callbackUrl": "callBackUrl", "reportRequest": "true"/"false" } } }' ``` ::: :::Tab{title="Production"} ```curl curl --location 'https://api.signzy.us/api/v3/global-kyb/us-v2' \ --header 'Authorization: <----Auth Token---->' \ --header 'Content-Type: application/json' \ --data-raw '{ { "topN": "", "matchThreshold": "", "data": { "names": [ "", "" ], "addresses": [ { "streetAddress1": "", "streetAddress2": "", "city": "", "state": "", "postalCode": "" }, { "streetAddress1": "", "streetAddress2": "", "city": "", "state": "", "postalCode": "" } ], "persons": [ { "firstName": "", "lastName": "" } ], "websites": [ "" ], "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 | :::CodeblockTabs 200 cases ```json { "result": { "responseID": "", "legalExistenceRiskRating": "", "activityRiskRating": "", "verificationTasks": [ { "taskName": "", "status": "", "result": "", "reason": "" } ], "bestMatch": { "matchConfidence": "", "matchedFields": { "name": "", "address": { "state": "" }, "person": "" } }, "legalEntities": [ { "signzyID": "", "formationDate": "", "legalEntityType": "", "matchConfidence": "", "matchedFields": { "name": "", "address": { "state": "" }, "person": "" }, "dataSources": ["", ""], "registrations": [ { "issueDate": "", "fileNumber": "", "registrationState": "", "registeredName": "", "jurisdictionType": "", "homeJurisdictionState": "", "standardizedStatus": "", "registrationStatus": "", "status": { "status": "", "subStatus": "", "statusDetail": "" }, "persons": [ { "name": "", "titles": ["", ""] } ], "addresses": [ { "streetAddress1": "", "streetAddress2": "", "city": "", "state": "", "postalCode": "", "country": "", "type": "" } ] } ] } ], "brands": [ { "brandID": "", "matchConfidence": "", "matchedFields": { "name": "", "person": "", "address": { "street_address1": "", "city": "", "state": "", "postal_code": "" } }, "dataSources": ["", ""], "activities": { "complianceRiskLevel": "", "activityTypes": ["", ""] }, "names": [ { "name": "" } ], "addresses": [ { "streetAddress1": "", "streetAddress2": "", "city": "", "state": "", "postalCode": "", "country": "", "type": "" } ], "websites": [""], "industries": [ { "classificationType": "", "classificationCode": "", "classificationDescription": "" } ] } ] }, "reason": "", "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) : ::::Tabs :::Tab{title="Pre-Production"} ```curl curl --location 'https://api-preproduction.signzy.us/api/v3/us-kyb-v2/report-status' \ --header 'Authorization:' \ --header 'Content-Type: application/json' \ --data '{"responseId":""}' ``` ::: :::Tab{title="Production"} ```curl curl --location 'https://api.signzy.us/api/v3/us-kyb-v2/report-status' \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{"responseId":""}' ``` ::: :::: ### CallBack/Get Curl Response : :::CodeblockTabs 200 cases ```json { "result": { "reportUrl": "", "responseID": "" }, "code": "", "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. :::CodeblockTabs Example ```json "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. :::CodeblockTabs Example ```json "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 :::CodeblockTabs Malformatted RequestId E001 ```json { "result": {}, "reason": "Bad Request: Bad Request. is invalid.", "status": "failure", "code": "E001" } ``` requestId Not Found E401 ```json { "result": {}, "reason": "Upstream error", "status": "failure", "code": "E401" } ``` ::: ### Error Response Parameters | **Parameter** | **Description** | | ------------- | ---------------------- | | result | Empty result object | | reason | Reason for error | | status | Status of the api | | code | 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 | :::hint{type="info"} ### 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! :::