Skip to content
Console(opens in a new tab)

Matching

How Enigma finds the business you describe, and how to control how many matches you get and how close they must be.

Every KYB request starts with a match. Enigma searches its records for the business in your request body, and the match decides what data holds and what every task compares your input against. At top_n=1, the default, your package’s tasks run on the best match, so a wrong match makes every task result wrong. The input you send decides the match more than any setting; top_n and match_threshold then control how many matches come back and how close they must be.

This request sends a legal name and a brand name, a full street address, a website and a person.

cURL
curl --request POST "https://api.enigma.com/v2/kyb/?package=verify" \
--header "x-api-key: $ENIGMA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"names": ["Enigma Technologies Inc", "Enigma"],
"address": {
"street_address1": "245 5th Ave",
"city": "New York",
"state": "NY",
"postal_code": "10016"
},
"website": "https://enigma.com",
"person": {
"first_name": "Jane",
"last_name": "Smith"
}
}'

The response below is trimmed to data, and to the fields that identify each match and link them. The registered entity lists the brand’s id in brand_ids, and the brand lists the registered entity’s id in registered_entity_ids.

200 OK
{
"response_id": "2a1b3c4d-5e6f-7890-abcd-ef1234567890",
"data": {
"registered_entities": [
{
"id": "4dccd7a5-790c-c4d1-0000-108000000000",
"names": [{ "name": "ENIGMA TECHNOLOGIES, INC." }],
"brand_ids": ["5f53e079-c66a-487e-8a9d-08efc39652ee"]
}
],
"brands": [
{
"id": "5f53e079-c66a-487e-8a9d-08efc39652ee",
"registered_entity_ids": ["4dccd7a5-790c-c4d1-0000-108000000000"],
"names": [{ "name": "ENIGMA TECHNOLOGIES" }]
}
]
}
}

Enigma keeps two kinds of linked record for a business. A registered entity is the legal entity and its Secretary of State registrations. A brand is the business as customers know it. The two names often differ: Instacart is registered as Maplebear Inc. Enigma links brands to registered entities, so you can send either name and still reach both records.

For each request, Enigma:

  1. Standardizes your input. Casing and spacing are normalized, and addresses are parsed into street, city, state and postal code.
  2. Builds one search for every combination of your names and addresses. Two names and two addresses give four combinations. Each combination looks for registered entities and brands.
  3. Adds your website and the submitted person to every search, to tell apart businesses with similar names.
  4. Scores each record it finds (a candidate) with a match confidence from 0 to 1, which says how likely it is that the candidate is the business you described. Candidates below match_threshold are dropped.
  5. Merges the results of all combinations. A business found by several combinations appears once.
  6. Returns up to top_n registered entities and up to top_n brands. At top_n=1 it also runs your package’s tasks on the match.

When no candidate is close enough, Enigma returns no match rather than a weak one. See When nothing matches.

  • In data.registered_entities, registered entities found directly come first, best match first, followed by registered entities linked to a matched brand. At top_n=1 it holds at most one element, the match.
  • In data.brands, brands linked to the registered entities Enigma found come first, then brands found directly.
  • The match confidence is not returned on registered entities or brands. The only match_confidence in the response is on watchlist hits.

top_n sets the maximum number of matches returned. It is an integer of 1 or more, and defaults to 1. top_n=0 returns 400.

  • At top_n=1, the default, you get at most one registered entity and one brand, and your package’s tasks run on the match.
  • Above 1, you get up to top_n of each, as candidates with no tasks. Each array is built and cut to top_n separately, so the two can differ in length. What else changes, for risk_summary, the TIN and SSN checks and watchlist screening, is in When top_n is above 1.

This request asks for up to three candidates. No tasks run above top_n=1, so identify is enough. The match_threshold value is illustrative; see Set a match threshold.

cURL
curl --request POST \
"https://api.enigma.com/v2/kyb/?package=identify&top_n=3&match_threshold=0.8" \
--header "x-api-key: $ENIGMA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Enigma Technologies",
"address": {
"street_address1": "245 5th Ave",
"city": "New York",
"state": "NY",
"postal_code": "10016"
}
}'

The response holds response_id and data, with up to three registered entities and up to three brands. Their order and how to join them by ID are described in Which record is the match.

match_threshold is the minimum match confidence a candidate needs to be returned. It is a number from 0 to 1. Enigma applies it to every name and address combination, for registered entities and brands alike, and drops candidates that score below it. A record returned only because it links to a match is not scored on its own.

  • Set it explicitly. When you omit it, Enigma applies an undocumented default. Set your own value so your results do not depend on it.
  • Send a valid number or omit it. A value that is not a number, or is outside 0 to 1, returns 400. Omit the parameter rather than sending it empty.

A higher threshold gives fewer wrong matches and more requests with no match. A lower threshold returns more matches, and more of them can be wrong. To see how a value performs, run a set of businesses whose correct match you already know. The threshold is your only control over how close a match must be.

The KYB API reads only the fields listed in the request body reference. It needs a business name in every request except a person-only screen. These input rules apply to POST /v2/kyb/ only, and differ from GraphQL search.

The more of the business you describe, the fewer wrong matches and missed matches you get. Send every identifier you hold, each in its own field, as the One match example does.

namesbody, arrayRequired, as name or names

The business name, the main search key. Send the legal name and the brand name (DBA) as two entries, up to 2. Include a legal suffix such as Inc when you know it.

addressbody, object

Narrows the search to one place. Send all of street_address1, city, state and postal_code. Send postal_code as a string: a number fails the request. The address tasks need street_address1; without it, both address tasks return address_not_verified.

addressesbody, array

A second address finds the business when its registered address and its operating address differ. Send both, up to 2.

websitebody, string

Separates businesses that share a common or similar name. Send one. A bare domain such as enigma.com works.

personbody, object

Adds an owner or officer to every search. Also used by the person_verification task. Send one person with first_name and last_name, without titles or suffixes in the name fields.

A TIN is read only when you request tin_verification, and ignored otherwise. When it is read, it is used only for the TIN check and does not change which entity is matched. TIN verification checks names with a legal-entity designator, such as Inc or LLC, first. To lead with a specific name, set primary_name. See Name and TIN pairs.

  • Legal name and brand name in one string. Send them as two entries in names so each is searched on its own.
  • Undocumented keys. Only the documented keys are read. zip or zip_code in an address, or a top-level phone, is ignored without an error.
  • Placeholder values. Leave out a field you do not have. A placeholder such as N/A or unknown is searched like a real value.
  • Too many values. More than 2 names, 2 addresses, 1 website or 1 person returns 400. See Validation.

A request that matches nothing still returns HTTP 200. Check data.registered_entities: when it is empty, no registered entity matched. When data.brands is empty too, nothing matched.

When both arrays are empty at top_n=1, risk_summary is still present, and each standard task returns the result and status below. identify runs the first four tasks; verify runs all seven.

Task Result Status
address_verification address_not_verified failure
sos_address_verification address_not_verified failure
name_verification name_not_verified failure
sos_name_verification name_not_verified failure
domestic_registration domestic_not_found failure
person_verification person_not_verified failure
verification_tier tier_unknown success
  • Add-on tasks return the results described for each on How checks work.
  • When you request negative news and no registered entity matched, the response has no background_task.
  • A response can also return a brand but no registered entity. Then name_verification and address_verification can still succeed against the brand, while the SoS tasks and domestic_registration report their not-verified and not-found results.

The No match example shows an identify request with no match: empty data arrays and not-verified task results. Branch on each result; the reason text is for people and can change.

If you expect a match, try these changes:

  • Check the input for typos, and send a full street address.
  • Send both the legal name and the brand name in names.
  • Add a website or a person.
  • Lower match_threshold, then use top_n above 1 to see the closest candidates that clear the new threshold.