- Docs
- Guides
- Build with Enigma
- KYB API
KYB quickstart
Learn how Enigma verifies a business, send your first KYB request, and read the result.
The Enigma KYB API verifies a U.S. business in one request. You describe the business, Enigma matches it to its records and runs a set of verification tasks, and the response returns the matched data with the evidence behind each result. This page takes you from an API key to a result you can act on.
How the KYB API works
Section titled “How the KYB API works”Every KYB request follows the same four steps.
- Describe the business. Send what you know: its name, address, and website, and optionally a person connected to it.
- Enigma finds the match. Enigma resolves your input to the registered entity and brand that most likely describe the business.
- Enigma runs the tasks. Each task checks one fact about the business, usually by comparing your input with the matched data, and reports a result with the evidence behind it.
- You apply your policy. Your application decides what to store, display, approve, decline, or send for review.
Businesses often trade under a name that differs from their legal name. Instacart, for example, is registered as Maplebear Inc. Enigma links the brand (the name customers know) to the registered entity (the legal entity on the Secretary of State registration), so a request with either name finds the business.
These five terms appear throughout the KYB docs.
| Concept | What it means |
|---|---|
| Business input | The JSON body you send: a business name, plus any address, website, or person you have. |
| Match | The registered entity and brand that Enigma returns as the closest records to the business you described. |
| Package | The standard tasks and data a request returns: identify, or verify (the default). |
| Task | One verification check, such as whether your business name appears on a Secretary of State registration. |
| Matched data | The records Enigma matched: registered entities with their registrations, and brands with their operating locations. |
Before you begin
Section titled “Before you begin”You need:
- An Enigma account with API access.
- An API key. In Enigma Console, go to Settings, then Account, then API keys.
- A terminal with
curl.
The API keys page appears after your organization has selected a plan. If you cannot see the API keys page, contact an Enigma representative to confirm your access.
Make your first request
Section titled “Make your first request”-
Store your API key.
Set the key as an environment variable for the current terminal session.
Terminal window export ENIGMA_API_KEY='replace_with_your_api_key' -
Send a request.
This request describes Enigma Technologies by name, website, and street address.
Request curl --request POST 'https://api.enigma.com/v2/kyb/?package=identify&top_n=1' \--header "x-api-key: $ENIGMA_API_KEY" \--header "Content-Type: application/json" \--data '{"name": "Enigma Technologies","website": "https://enigma.com","address": {"street_address1": "245 5th Ave","city": "New York","state": "NY","postal_code": "10016"}}'package=identifyruns the four name and address tasks, so the first response stays short.top_n=1asks for the single best match.- Only a business name is required. Every identifier you add helps Enigma tell apart businesses with similar names.
- Include
street_address1. The address tasks compare street addresses, and without one they always returnaddress_not_verified.
-
Read the response.
Look for three parts:
risk_summary.tasksholds the tasks in the package, one object per task.response_ididentifies this response.dataholds the matched data, inregistered_entitiesandbrands.
The example response below is illustrative and trimmed to the fields this page discusses. A real response includes more fields, and values change as Enigma updates its data.
Example response {"risk_summary": {"tasks": [{"task_name": "address_verification","status": "success","result": "address_match","reason": "An input address matches an address in any of Enigma's records","sources": [{"address": {"street_address1": "245 5TH AVE","street_address2": "FL 17","city": "NEW YORK","state": "NY","postal_code": "10016","type": "headquarters"},"match_entity_type": "registered_entity","match_relationship_type": "registration_address","urls": ["https://example.com/records/ny-5012345"]}]},{"task_name": "sos_address_verification","status": "success","result": "address_match","sources": [{"match_entity_type": "registered_entity","match_relationship_type": "registration_address"}]},{"task_name": "name_verification","status": "success","result": "name_exact_match","sources": [{"name": "ENIGMA TECHNOLOGIES","match_entity_type": "brand","urls": []}]},{"task_name": "sos_name_verification","status": "success","result": "name_match","sources": [{"name": "ENIGMA TECHNOLOGIES, INC.","match_entity_type": "registered_entity"}]}]},"response_id": "2a1b3c4d-5e6f-7890-abcd-ef1234567890","data": {"registered_entities": [{"id": "4dccd7a5-790c-c4d1-0000-108000000000","registered_entity_type": "Corporation","names": [{ "name": "ENIGMA TECHNOLOGIES, INC." }],"brand_ids": ["5f53e079-c66a-487e-8a9d-08efc39652ee"],"registrations": [{"registration_state": "NY","registered_name": "ENIGMA TECHNOLOGIES, INC.","file_number": "5012345"}]}],"brands": [{"id": "5f53e079-c66a-487e-8a9d-08efc39652ee","registered_entity_ids": ["4dccd7a5-790c-c4d1-0000-108000000000"],"names": [{ "name": "ENIGMA TECHNOLOGIES" }],"websites": ["https://enigma.com"]}]}}Each task returned its result for a specific reason.
Task Result Why name_verificationname_exact_matchThe name matches the brand exactly. sos_name_verificationname_matchThe Secretary of State registration adds INC.to the name.address_verificationandsos_address_verificationaddress_matchThe record includes a floor ( FL 17) that the request left out.
Interpret the result
Section titled “Interpret the result”| Part | What it tells you |
|---|---|
| HTTP status | Whether Enigma accepted and processed the request. |
| Matched data | data.registered_entities and data.brands hold what Enigma matched. |
| Task result | result is the specific result code of a task, such as name_exact_match or address_not_verified. Branch on this value. |
| Task status | status is a coarse summary, usually success or failure. |
| Sources | sources lists the Enigma records that support a result, when there are any. |
| Response ID | response_id is the identifier to log, and to give Enigma when you investigate a request. |
A registered entity lists its brands in brand_ids, and a brand lists its
registered entities in registered_entity_ids. Join records by these IDs, not
by their position in the arrays. Even with top_n=1, the returned brand is not
guaranteed to be linked to the returned registered entity. Check that the
brand’s registered_entity_ids contains the registered entity’s id before you
treat them as one business.
Choose the right request
Section titled “Choose the right request”| Request | Use it when | What it returns |
|---|---|---|
package=identify |
You need identity matching, enrichment, onboarding prefill, or third-party confirmation. | The matched data and four name and address tasks. |
package=verify |
You need a full business verification for compliance, such as onboarding under a KYB program. | Everything in identify, plus registration status fields and three tasks: domestic_registration, person_verification, and verification_tier (beta). |
Add checks to either package with add-ons
in attrs, for example attrs=watchlist for watchlist screening. Each add-on
must be enabled for your account. The
use cases show a complete request for every
job, from onboarding a business to screening an owner or getting negative news.
Before you go live
Section titled “Before you go live”- Set
packageexplicitly. A request without it runsverify. See packages. - Keep
top_n=1when you need tasks. Tasks run only on a single match. See control the number of matches. - Send every identifier you have, in the right field. A full street address, a website, and both the legal name and the brand name, when you have them, all improve the match. See send strong identifiers.
- Branch on
result, never onreason. Thereasontext is written for people and can change. See the task object. - Log
response_idfor every request. Quote it to Enigma when you investigate a request. See top-level fields. - Retry
429and5xxresponses with exponential backoff. Fix a400instead of retrying it. Every retry is a new request. See retries and backoff. - Treat add-ons as account features. Confirm with Enigma which add-ons are enabled for your account. See account enablement.