- Docs
- API reference
- Endpoints and schemas
- KYB API
- Endpoints
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/.
https://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.
Example
Section titled “Example”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 --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" }'This example shows the shape at top_n=1, trimmed to one task and to the IDs
that link a registered entity to its brand.
{ "risk_summary": { "tasks": [ { "task_name": "sos_name_verification", "status": "success", "result": "name_match", "reason": "An input business name matches a business name on a matching SoS registration", "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", "brand_ids": ["5f53e079-c66a-487e-8a9d-08efc39652ee"] } ], "brands": [ { "id": "5f53e079-c66a-487e-8a9d-08efc39652ee", "registered_entity_ids": ["4dccd7a5-790c-c4d1-0000-108000000000"] } ] }}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.
Authentication
Section titled “Authentication”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.
The parts of a request
Section titled “The parts of a request”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
Section titled “Query parameters”Query parameters choose what Enigma checks and returns, and how many matches come back. All are optional.
packageThe package:
identifyorverify. Defaultverify. Case-insensitive. Set it explicitly in production. Cannot be combined withproducts.attrsComma-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 withproducts. See the rules below the list.productsComma-separated attributes for an attribute-only request: no package and no standard tasks. At least one value; an unknown value returns
400.watchlist,tin_verificationandssn_verificationstill add their tasks. Cannot be combined withpackageorattrs.top_nThe maximum number of matches to return. Default
1. Must be1or greater. Tasks run only at1; see Whentop_nis above 1.match_thresholdThe minimum match confidence a candidate needs, from
0to1. 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:
attrsvalues are case-sensitive, and an unknown value is ignored without an error.attrs=Watchlistis ignored, so no watchlist screening runs and no error tells you.- The bare value
card_transactionsreturns400, even alongside other values. Name the values you want, such ascard_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.
When top_n is above 1
Section titled “When top_n is above 1”With top_n=2 or more:
- No tasks run, and
risk_summaryis omitted from the response. data.registered_entitiesanddata.brandseach hold up totop_ncandidates. The two arrays can differ in length. Join them by ID, not by position.- A request that includes
tin_verificationorssn_verificationreturns400. watchliststill returns hits in thewatchlistsarray, but there is nowatchlisttask.
See Control the number of matches for a worked request.
Request body
Section titled “Request body”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.
Single values
Section titled “Single values”nameRequired unless you sendnamesorprimary_name, or on a person-only screenThe business name: the legal name or a trade name (DBA). See person-only screen.
websiteThe business website, as a URL (
https://enigma.com) or a bare domain (enigma.com). Helps tell apart businesses that share a name.addressA business address. See Address fields.
personForssn_verificationOne person connected to the business, such as an owner or officer. Used for matching and for the
person_verificationtask, and required forssn_verification. See Person fields.tinFortin_verificationThe business’s federal Taxpayer Identification Number (EIN). Read only with
tin_verification. See Validation.
Address fields
Section titled “Address fields”The same fields apply to address, to each item in addresses, and to
person.address. Send every value as a string.
street_address1For the address tasksStreet number and name, for example
245 5th Ave. The address tasks need it: without it,address_verificationandsos_address_verificationboth returnaddress_not_verified.street_address2Suite, unit or floor.
cityCity.
stateTwo-letter state code, for example
NY.postal_codeZIP code. Send it as a string to keep leading zeros. The field is
postal_code;zipandzip_codeare ignored.
Person fields
Section titled “Person fields”A person object accepts only these keys. Any other key returns 400.
first_nameForperson_verificationFirst name. Needed for
person_verification.last_nameForperson_verificationandssn_verificationLast name. Needed for
person_verification, and the namessn_verificationchecks the SSN against.date_of_birthDate of birth as
YYYY-MM-DD. Helps match the person.addressThe person’s address. See Address fields.
ssnForssn_verificationThe 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.
Multiple values
Section titled “Multiple values”Use the multiple-value fields when a business has more than one name or address, for example a legal name and a trade name.
namesUp to 2 business name strings. Empty strings and duplicates are removed before the limit is checked.
primary_nameEnigma 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
namesor on its own, not withname.addressesUp to 2 business address objects. See Address fields.
websitesUp to 1 website string.
personsUp to 1 person object. See Person fields.
tinsFortin_verification, if you send notin1 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.
The data wrapper
Section titled “The data wrapper”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.
{ "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.
Screen a person without a business
Section titled “Screen a person without a business”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(orproducts) must be exactlywatchlist. Any other value, or neither parameter, returns400.packageis optional. It changes only which standard tasks appear inrisk_summary.tasks, and each of them reports its not-verified, not-found or unknown result.data.registered_entitiesanddata.brandsare empty arrays. The result is in thewatchlisttask and thewatchlistsarray.- 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.watchlistscreens 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.
Validation
Section titled “Validation”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
attrsvalues, includingverification_tier. tinandtinswithouttin_verification.person.ssnwithoutssn_verification.- Unrecognized top-level keys and address keys, such as
zip_code. Unknownpersonkeys return400(see above).
A failed rule returns an error body:
{ "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.
Response
Section titled “Response”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 codes
Section titled “Status codes”| 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.
Related
Section titled “Related”- Use cases: a complete request for each job.
- Packages and
Add-ons: the values of
package,attrsandproducts. - Matching: how the body finds the business, and the inputs that improve the match.
- Response object: every field in the response.
- How checks work: every task and its results.
GET /v2/kyb/{task_id}: the follow-up request for negative news.- Errors and rate limits: status codes and when to retry.