Skip to content
Console(opens in a new tab)

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.

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

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.

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 (or 403). See Errors and rate limits.
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.