- Docs
- API reference
- Endpoints and schemas
- KYB API
- Response
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.
Example
Section titled “Example”This request sends a legal name and a brand name, a full street address, a website and a person.
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.
{ "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" }] } ] }}An identify request that matched nothing still returns HTTP 200, with empty
data arrays and not-verified task results. The response is trimmed to two of
the four tasks.
{ "risk_summary": { "tasks": [ { "task_name": "address_verification", "status": "failure", "result": "address_not_verified", "reason": "No input address matches any address in any of Enigma's records", "sources": [] }, { "task_name": "name_verification", "status": "failure", "result": "name_not_verified", "reason": "No input business name matches a business name in any of Enigma's records", "sources": [] } ] }, "response_id": "2a1b3c4d-5e6f-7890-abcd-ef1234567890", "data": { "registered_entities": [], "brands": [] }}How matching works
Section titled “How matching works”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:
- Standardizes your input. Casing and spacing are normalized, and addresses are parsed into street, city, state and postal code.
- 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.
- Adds your website and the submitted person to every search, to tell apart businesses with similar names.
- 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_thresholdare dropped. - Merges the results of all combinations. A business found by several combinations appears once.
- Returns up to
top_nregistered entities and up totop_nbrands. Attop_n=1it 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.
Which record is the match
Section titled “Which record is the match”- In
data.registered_entities, registered entities found directly come first, best match first, followed by registered entities linked to a matched brand. Attop_n=1it 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_confidencein the response is on watchlist hits.
Control the number of matches
Section titled “Control the number of matches”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_nof each, as candidates with no tasks. Each array is built and cut totop_nseparately, so the two can differ in length. What else changes, forrisk_summary, the TIN and SSN checks and watchlist screening, is in Whentop_nis 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 --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.
Set a match threshold
Section titled “Set a match threshold”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.
Send strong identifiers
Section titled “Send strong identifiers”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.
namesRequired, asnameornamesThe 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
Incwhen you know it.addressNarrows the search to one place. Send all of
street_address1,city,stateandpostal_code. Sendpostal_codeas a string: a number fails the request. The address tasks needstreet_address1; without it, both address tasks returnaddress_not_verified.addressesA second address finds the business when its registered address and its operating address differ. Send both, up to 2.
websiteSeparates businesses that share a common or similar name. Send one. A bare domain such as
enigma.comworks.personAdds an owner or officer to every search. Also used by the
person_verificationtask. Send one person withfirst_nameandlast_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.
Avoid these inputs
Section titled “Avoid these inputs”- Legal name and brand name in one string. Send them as two entries in
namesso each is searched on its own. - Undocumented keys. Only the documented keys are read.
ziporzip_codein an address, or a top-levelphone, is ignored without an error. - Placeholder values. Leave out a field you do not have. A placeholder such
as
N/Aorunknownis searched like a real value. - Too many values. More than 2 names, 2 addresses, 1 website or 1 person returns 400. See Validation.
When nothing matches
Section titled “When nothing matches”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_verificationandaddress_verificationcan still succeed against the brand, while the SoS tasks anddomestic_registrationreport 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 usetop_nabove 1 to see the closest candidates that clear the new threshold.
Related
Section titled “Related”- Run a KYB check: every request field, limit and validation rule.
- Response object: how
the response changes with
top_nand your package. - How checks work: what each task checks and the results it can return.
- Registered entities and Brands: the matched records.