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

Pre-Production

Production

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

{
  "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.

 "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.

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.

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.

"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

{
    "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

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 [email protected]. 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!