- Docs
- API reference
- Endpoints and schemas
- KYB API
- Use cases
Verify a business
Match a business to Enigma's records and run the standard tasks of the verify or identify package.
https://api.enigma.com/v2/kyb/?package=verifySend what you know about a U.S. business. Enigma matches it to a registered
entity and a brand, runs the standard tasks of your package against the match,
and returns the matched data with a result for each task. This is the base of
every business request: like every use case, it is one POST /v2/kyb/ request,
and add-ons such as watchlist screening or a TIN check combine in the same call,
as in Onboard a business.
Example
Section titled “Example”This request runs the seven standard verify tasks. The submitted person is
checked by person_verification.
curl --request POST "https://api.enigma.com/v2/kyb/?package=verify" \ --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" } }'This response is trimmed to one task and to the IDs that link the 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"] } ] }}Parameters
Section titled “Parameters”x-api-keyRequiredYour API key. Send it from your server only. See Authentication.
packageDefaultverifyverifyoridentify. Set it explicitly in production. Case-insensitive. See Choose a package.top_nDefault 11. Tasks run only at1. See Whentop_nis above 1.match_thresholdA number from
0to1: the minimum match confidence a candidate needs. See Set a match threshold.attrsAdd-on tasks and attributes, run on top of either package. See Add-ons.
nameRequiredThe business name. Send
name, or up to twonames, such as a legal name and a trade name. Enigma tries every combination of names and addresses. Only a business name is required, but the tasks check what you send.addressFor the address tasksaddresswithstreet_address1. Without it, both address tasks returnaddress_not_verified.personForperson_verificationOn
verify,person_verificationalways runs, and returnsperson_not_verifiedwhen the request has noperson.
Each identifier you add helps Enigma find the right match; see Send strong identifiers. All query parameters are in Query parameters, all body fields in Request body, and the rules in Validation.
Response
Section titled “Response”risk_summary.tasks[]The standard tasks of the package, then any add-on tasks you request. Branch on each task’s
result.identifyruns only the first four tasks below;verifyruns all seven. Find a task bytask_name, not by its position. See Tasks by package.Show the 7 tasks and their results
Task Results name_verificationname_exact_match,name_match,name_not_verifiedsos_name_verificationname_exact_match,name_match,name_not_verifiedaddress_verificationaddress_exact_match,address_match,address_not_verifiedsos_address_verificationaddress_exact_match,address_match,address_not_verifieddomestic_registrationdomestic_active,domestic_unknown,domestic_inactive,domestic_not_foundperson_verificationperson_match,person_not_verifiedverification_tiertier_1,tier_2,tier_3,tier_unknowndata.registered_entitiesThe matched registered entity and its registrations. On
verify, each registration carries itsstatus. See The registration object.data.brandsThe matched brand, linked to registered entities by ID. See Brands.
response_idThe ID of this response. Log it and quote it to Enigma support. See Top-level fields.
More examples
Section titled “More examples”Identify
Section titled “Identify”This request matches a business and checks its name and address with the four
identify tasks.
curl --request POST "https://api.enigma.com/v2/kyb/?package=identify" \ --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" } }'The response has the same shape as the verify response, with four tasks,
and registrations without the five fields that only verify returns.
Several names
Section titled “Several names”This request sends a legal name and a trade name in the request data wrapper,
with primary_name inside it. Enigma tries each name with the address. See
The data wrapper.
curl --request POST "https://api.enigma.com/v2/kyb/?package=verify" \ --header "x-api-key: $ENIGMA_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "data": { "primary_name": "Enigma Technologies Inc", "names": ["Enigma Technologies Inc", "Enigma"], "addresses": [ { "street_address1": "245 5th Ave", "city": "New York", "state": "NY", "postal_code": "10016" } ], "websites": ["https://enigma.com"] } }'Before you rely on it
Section titled “Before you rely on it”- A 200 is not a verification.
200means Enigma processed the request, including when nothing matched or a task failed. Read the outcome fromdataand each task’sresult. See Status codes. - Join by ID. Even at
top_n=1, the returned brand is not always linked to the returned registered entity. See Which record is the match. - Set the package explicitly. A request with neither
packagenorproductsrunsverify. To decide which one you need, see Choose a package.
Related
Section titled “Related”- Packages: the tasks and fields each package returns, and how to choose one.
- Add-ons: every add-on task and attribute you can request on top of a package.
- How checks work: every task and its results.
- Onboard a business: verification together with watchlist screening and a TIN check.