Skip to content
Console(opens in a new tab)

Run a KYB check

Match a business and run the checks you choose, in one request: every parameter, body field, validation rule and status code of POST /v2/kyb/.

POSThttps://api.enigma.com/v2/kyb/

Send what you know about a U.S. business. Enigma matches it to the registered entities and brands in its data, runs the tasks in your package plus any add-on tasks, and returns the matched data with a result for each task. The request is synchronous. Only negative news can arrive later, through a background task.

Every use case is this one request with a different query string. This page defines every part of it; the use cases show complete requests for each job, such as verifying a business or screening a person.

This request runs the seven standard verify tasks, screens against watchlists, and checks the TIN with the IRS. The submitted person is checked by person_verification. top_n=1 is the default; it is shown because tin_verification requires it.

cURL
curl --request POST "https://api.enigma.com/v2/kyb/?package=verify&attrs=watchlist,tin_verification&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"
},
"person": {
"first_name": "Jane",
"last_name": "Smith"
},
"tin": "123456789"
}'

Each use case has its own complete request: identify a business, send several names, ask for attributes only, screen a person, or get negative news.

Send your API key in the x-api-key header. Create a key in Enigma Console, and send it from your server only: never expose it in a browser, a mobile app or a public repository. A missing or invalid key returns 401 (or 403). See Authentication.

A request has four parts. Three go in the query string, and the business input goes in the JSON body.

Part Written as Answers
Package ?package=verify What should Enigma check?
Add-ons &attrs=watchlist What else should it check or return?
Match controls &top_n=1&match_threshold=0.8 How many matches, and how close?
Business input {"name": "...", "address": {...}} Which business do I mean?

Two request forms change which parts you send. An attribute-only request replaces the package and add-ons with products. A person-only screen sends a person and no business input.

Query parameters choose what Enigma checks and returns, and how many matches come back. All are optional.

packagequery, string

The package: identify or verify. Default verify. Case-insensitive. Set it explicitly in production. Cannot be combined with products.

attrsquery, string

Comma-separated add-on tasks and add-on attributes to run on top of the package, for example watchlist,bankruptcies. Add-ons must be enabled for your account. Cannot be combined with products. See the rules below the list.

productsquery, string

Comma-separated attributes for an attribute-only request: no package and no standard tasks. At least one value; an unknown value returns 400. watchlist, tin_verification and ssn_verification still add their tasks. Cannot be combined with package or attrs.

top_nquery, integer

The maximum number of matches to return. Default 1. Must be 1 or greater. Tasks run only at 1; see When top_n is above 1.

match_thresholdquery, number

The minimum match confidence a candidate needs, from 0 to 1. Candidates below it are dropped before ranking. Set it explicitly; do not rely on a default. To send no threshold, omit the parameter instead of sending it empty.

Check attrs values carefully:

  • attrs values are case-sensitive, and an unknown value is ignored without an error. attrs=Watchlist is ignored, so no watchlist screening runs and no error tells you.
  • The bare value card_transactions returns 400, even alongside other values. Name the values you want, such as card_revenue_amount. See Card-transaction values for all eight.

verification_tier is not an add-on value: in attrs it is ignored, and in products it returns 400. The verification tier runs with the verify package; see When it runs.

With top_n=2 or more:

  • No tasks run, and risk_summary is omitted from the response.
  • data.registered_entities and data.brands each hold up to top_n candidates. The two arrays can differ in length. Join them by ID, not by position.
  • A request that includes tin_verification or ssn_verification returns 400.
  • watchlist still returns hits in the watchlists array, but there is no watchlist task.

See Control the number of matches for a worked request.

The body is a JSON object that describes one business. Send it with the header Content-Type: application/json; without it, the body is not read and the request returns 400. Only a business name is required, except for a person-only screen. Every other field is optional, but each identifier you add helps Enigma find the right match. See Send strong identifiers.

Most fields have a single-value form (name) and a multiple-value form (names); primary_name has one form only. Send one form of a field, not both. You can mix forms across fields, for example name with addresses. Enigma ignores top-level keys it does not recognize.

namestringRequired unless you send names or primary_name, or on a person-only screen

The business name: the legal name or a trade name (DBA). See person-only screen.

websitestring

The business website, as a URL (https://enigma.com) or a bare domain (enigma.com). Helps tell apart businesses that share a name.

addressobject

A business address. See Address fields.

personobjectFor ssn_verification

One person connected to the business, such as an owner or officer. Used for matching and for the person_verification task, and required for ssn_verification. See Person fields.

tinstringFor tin_verification

The business’s federal Taxpayer Identification Number (EIN). Read only with tin_verification. See Validation.

The same fields apply to address, to each item in addresses, and to person.address. Send every value as a string.

street_address1stringFor the address tasks

Street number and name, for example 245 5th Ave. The address tasks need it: without it, address_verification and sos_address_verification both return address_not_verified.

street_address2string

Suite, unit or floor.

citystring

City.

statestring

Two-letter state code, for example NY.

postal_codestring

ZIP code. Send it as a string to keep leading zeros. The field is postal_code; zip and zip_code are ignored.

A person object accepts only these keys. Any other key returns 400.

first_namestringFor person_verification

First name. Needed for person_verification.

last_namestringFor person_verification and ssn_verification

Last name. Needed for person_verification, and the name ssn_verification checks the SSN against.

date_of_birthstring

Date of birth as YYYY-MM-DD. Helps match the person.

addressobject

The person’s address. See Address fields.

ssnstringFor ssn_verification

The person’s Social Security Number. Read only with ssn_verification. See Validation.

On verify, the person_verification task always runs. Without a person in the request, it returns person_not_verified.

Use the multiple-value fields when a business has more than one name or address, for example a legal name and a trade name.

namesarray

Up to 2 business name strings. Empty strings and duplicates are removed before the limit is checked.

primary_namestring

Enigma puts it first in the list of names, so it leads the TIN check among names of the same kind. It counts toward the 2-name limit. Use it with names or on its own, not with name.

addressesarray

Up to 2 business address objects. See Address fields.

websitesarray

Up to 1 website string.

personsarray

Up to 1 person object. See Person fields.

tinsarrayFor tin_verification, if you send no tin

1 or 2 TIN strings. Duplicates are removed after dashes are removed. Read only with tin_verification, which checks each name against each TIN. See Name and TIN pairs.

Enigma tries every combination of names and addresses, so two names and two addresses give four combinations. A second name or address widens the search; it does not narrow it. See How matching works.

You can nest every body field under a single top-level data key. The wrapper is optional and works with either form of each field. When you use it, data must be the only top-level key: a field beside it, such as primary_name, returns 400. Put primary_name inside data with the other fields.

Request body with the data wrapper
{
"data": {
"primary_name": "Enigma Technologies Inc",
"names": ["Enigma Technologies Inc", "Enigma"]
}
}

Verify a business has a complete request with several names.

The request data wrapper is unrelated to the data object in the response.

A person-only screen checks one individual against watchlists when there is no business to match. Send a body with only person (or persons), and no name, address, website or TIN.

  • attrs (or products) must be exactly watchlist. Any other value, or neither parameter, returns 400.
  • package is optional. It changes only which standard tasks appear in risk_summary.tasks, and each of them reports its not-verified, not-found or unknown result.
  • data.registered_entities and data.brands are empty arrays. The result is in the watchlist task and the watchlists array.
  • Adding any business input makes it a normal business request. Enigma then matches the business, uses the person for matching and person_verification, and requires a business name as usual. Screening of the submitted person is then not guaranteed, so do not rely on it. watchlist screens the matched business and the people on its registrations. To screen the person, send a separate person-only request.

Screen a person shows the request and the response.

Enigma validates the request before it searches. The first rule that fails returns 400.

Applies to Rule
Body Valid JSON, sent with Content-Type: application/json.
data If present, the only top-level key.
Business name At least one of name, names or primary_name, except on a person-only screen.
Field pairs Not both name and names, address and addresses, website and websites, person and persons, or primary_name and name.
Limits At most 2 names (including primary_name), 2 addresses, 1 website and 1 person.
Types name, primary_name, website and tin are strings; address and person are objects; names, addresses, websites and persons are arrays.
person keys Only first_name, last_name, date_of_birth, address and ssn.
package identify or verify, in any case.
products At least one value, every value recognized, and not combined with package or attrs.
card_transactions The bare value returns 400 in attrs or products, even alongside other values.
top_n 1 or greater.
match_threshold A number from 0 to 1.
Person-only screen attrs (or products) is exactly watchlist.
tin_verification A TIN in tin, or 1 or 2 in tins (not both), each with 9 digits after dashes are removed, a business name, and top_n=1.
ssn_verification A person with ssn on the person object (not top level), 9 digits after dashes are removed, and top_n=1.

A top_n that is not a whole number, or a value in address or an addresses item that is not a string (such as a numeric postal_code), is not caught by validation and returns 500. See Status codes.

Enigma ignores these without an error:

  • Unrecognized attrs values, including verification_tier.
  • tin and tins without tin_verification.
  • person.ssn without ssn_verification.
  • Unrecognized top-level keys and address keys, such as zip_code. Unknown person keys return 400 (see above).

A failed rule returns an error body:

Example response: 400
{
"error": true,
"message": "Bad Request: Query parameter 'top_n' must be greater than 0"
}

Branch on the HTTP status, not on message. Its wording can change. Errors and rate limits lists the common messages.

A successful request returns 200 with a JSON object that holds risk_summary, response_id and data, plus watchlists and background_task when you request them. The Response object page defines every field, and how your options change the response.

The Response tab under Example shows the shape at top_n=1.

Status Meaning Retry
200 The request was processed. This includes no match and failed tasks. No
400 The request failed validation. No
401 The API key is missing or invalid. No
403 Access was denied, or the method and path do not exist. No
429 Too many requests. Yes, with backoff
500 An unexpected error. Only if the request is valid
502 An upstream data service failed. Yes, with backoff
504 The request took longer than about 29 seconds. Yes, with backoff

A 500 caused by a non-integer top_n or a non-string business address value repeats until you fix the request. Contact support if a 500 persists. Set your client timeout to about 30 seconds. If you retry a 504 that included a TIN or SSN check within a short window, that task reports duplicate. Error bodies, rate limits and backoff timings are in Errors and rate limits.