- Docs
- API reference
- Endpoints and schemas
- KYB API
KYB API
Verify a U.S. business with one request: match it to Enigma's records, run the checks you choose and get the evidence behind the results.
The KYB API matches the business you describe to Enigma’s records, runs the
verification tasks you ask for, and returns the matched data with the evidence
behind most task results. Only negative news can arrive later. This reference
documents version 2 of the API, served under /v2/kyb/.
New to the API? Send a first request with the KYB quickstart, then pick a use case below.
Use cases
Section titled “Use cases”Every use case is the same POST /v2/kyb/ call. The query string sets the use
case, and add-ons combine in one request: package=verify&attrs=watchlist
verifies a business and screens it at once.
| Use case | Request | What you get |
|---|---|---|
| Onboard a business | ?package=verify&attrs=watchlist,tin_verification, then a person-only screen for each owner |
The full check most onboarding flows run: the match, its registration standing, the people on its filings, the verification tier, watchlist screening and an IRS check of its TIN. |
| Verify a business | ?package=verify or ?package=identify |
The match and the standard tasks of the package. |
| Get attributes only | ?products=phone_numbers,operating_status |
Each match’s IDs and the attributes you list, without standard tasks. |
| Screen a business | Add &attrs=watchlist |
Watchlist hits for the business and the people on its registrations. |
| Screen a person | ?attrs=watchlist, with only a person in the body |
Watchlist hits for one individual, such as an owner. |
| Verify a TIN or SSN | Add &attrs=tin_verification or &attrs=ssn_verification |
An IRS check that the number matches the name. |
| Get negative news | Add &attrs=negative_news, then GET /v2/kyb/{task_id} |
Recent negative news about each matched registered entity. |
Endpoints
Section titled “Endpoints”| Endpoint | Request | Purpose |
|---|---|---|
| Run a KYB check | POST /v2/kyb/ |
Match a business, run the checks in your package and add-ons, and return the response. |
| Retrieve a background task | GET /v2/kyb/{task_id} |
Retrieve negative news results that were not ready when the POST request returned. |
The base URL is https://api.enigma.com.
How this reference is organized
Section titled “How this reference is organized”The sections follow one KYB request from start to finish.
| Section | What it covers |
|---|---|
| Use cases | A complete request and response for each job, such as onboarding a business or screening a person. Start here. |
| Endpoints | The full definition of the two requests: every parameter, body field and status code. |
| Request options | What a request asks for: the package and the add-ons. |
| Response | What comes back: the response object, how Enigma chose the match, and the matched registered entities, brands and addresses. |
| Checks | What each check compares and what its results mean. |
| Errors and rate limits | Status codes, limits and when to retry. |
Authentication
Section titled “Authentication”Send your API key in the x-api-key header on every request.
- Get a key in Enigma Console under Settings, then Account, then API keys.
- Call the API from your server. Never put the key in browser code, a mobile app or a public repository.
- A request with a missing or invalid key is rejected with
401(or403). See Errors and rate limits.
Conventions
Section titled “Conventions”| Convention | Rule |
|---|---|
| Format | Requests and responses are JSON. Send Content-Type: application/json on every POST, or the request fails with 400. |
| Field names | Keys are snake_case. The one exception is the negative news article object, which uses sourceName and publishedDate. |
| IDs | Every ID, including response_id, is an opaque string. Store and compare IDs; do not parse them. Log response_id for every request, and quote it when you contact Enigma support. background_task.id is null when there is nothing to poll. |
| Linked records | registered_entities and brands link through brand_ids and registered_entity_ids. The two arrays can differ in length, so never join them by position. |
| Missing values | A field in your package is null when Enigma has no value, and some fields are left out instead. Handle a missing key the same as null. See Missing and null fields. |
| Arrays | Any array can be empty, so check its length before you read an element. A registered entity’s urls list is left out when it is empty. When the screening service fails, watchlists holds the single string "Screen API error" instead of hit objects. See When screening does not complete. |
| Dates | Date fields such as formation_date and issue_date are YYYY-MM-DD strings. |
| Results and reasons | A task’s result is a fixed value to branch on. Its reason is a readable explanation that can change. Never branch on its text. |
| Key order | The order of keys in an object is not part of the contract. |
| Coverage | The KYB API covers businesses in the U.S. only. |
Related
Section titled “Related”- KYB quickstart: send a first request and read the response.
- Run a KYB check: every parameter, body field and validation rule.
- Packages and Add-ons: what each request checks and returns.
- Response object: every top-level field, and how your options change the response.
- How checks work: every check and its results.
- Errors and rate limits: status codes and when to retry.