- Docs
- API reference
- Endpoints and schemas
- KYB API
- Response
Response object
The top-level fields of a KYB response, what each one holds, and how the response changes with the options you send.
Every successful call to
POST /v2/kyb/ returns
HTTP 200 with a JSON object built from the same top-level parts: the matched
records in data, a response_id, the check results in risk_summary at
top_n=1, and watchlists and background_task when you request them. Each
part is listed in Top-level fields and documented on its
own page. HTTP 200 means Enigma processed
the request, not that the business is verified. Read the outcome from data and
from each task’s result. For the body of a non-200 response, see
Errors and rate limits.
Example
Section titled “Example”A verify request with watchlist screening, trimmed to one task and the IDs
that link the records. The full response is in
Example response.
{ "risk_summary": { "tasks": [ { "task_name": "name_verification", "status": "success", "result": "name_exact_match" } ] }, "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"] } ] }, "watchlists": []}An identify request that matched nothing, trimmed to two of the four tasks.
It still returns HTTP 200, with empty data arrays and not-verified task
results. See
When nothing matches.
{ "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": [] }}Top-level fields
Section titled “Top-level fields”dataAlwaysThe registered entities and brands Enigma matched. How Enigma picks them is on Matching. Their fields are on Registered entities, Brands and Addresses. See The
dataobject.risk_summaryWhentop_n=1The tasks run against the match, one per check. Present only when
top_n=1, the default. See How checks work.watchlistsWithwatchlistPresent when you request watchlist screening (
watchlistinattrsorproducts), at anytop_n. One object per watchlist hit, or[]when screening found none. When screening fails or times out, it can hold the string"Screen API error"or only some of the hits. See Watchlist screening and When screening does not complete.background_taskWithnegative_newsPresent when you request
negative_news(inattrsorproducts) and at least one registered entity matched. Also absent when the news lookup failed for every matched entity, so a missingbackground_taskdoes not mean no negative news was found. Holds negative news results, or a task ID to poll. See Negative news.response_idAlwaysIdentifies this response. Log it, and quote it when you contact Enigma support. Treat it as an opaque string. See Conventions.
Fields not listed here are not part of the response contract. For key order, IDs and empty arrays, see Conventions.
The data object
Section titled “The data object”The data object is always present and always holds two arrays, registered_entities and brands. Both are empty when nothing matched and on a person-only screen. With top_n=1, each array holds at most one object. With top_n above 1, each holds up to top_n.
The list below shows the nested arrays and objects in data. Scalar fields, such as a registered entity’s id and formation_date, are documented on the linked pages.
registered_entities[]: the legal entities that match your input. See Registered entities.names[]: the entity’s legal names.brand_ids[]: the IDs of the brands linked to this entity.registrations[]: the entity’s Secretary of State registrations.persons[]: registered persons, such as officers and registered agents.addresses[]: the person’s addresses. Only with theperson_addressesadd-on.
addresses[]: the addresses on the registration, with theirtype, such asheadquartersorregistered_agent.
addresses[]: mailing addresses that do not already appear under a registration.urls[]: the source URLs of the records behind the entity.bankruptcies[]: bankruptcy filings. Only with thebankruptciesadd-on.
brands[]: the businesses as customers know them. See Brands.registered_entity_ids[]: the IDs of the registered entities linked to this brand.names[]: the brand’s names.websites[]: the brand’s website. Holds at most one URL.activities: notable activities, such as cannabis.industries[]: industry classifications.card_transactions: card activity. Only with a card-transaction add-on attribute. See Card-transaction values.operating_locations[]: the brand’s physical locations.names[]: the location’s names.addresses[]: the location’s addresses.phone_numbers[]: the location’s phone numbers. Only with thephone_numbersadd-on.operating_status: whether the location is open. Only with theoperating_statusadd-on.
Address objects share one shape, with USPS deliverability fields. There are two exceptions. A registered person’s address can be an object with a single full_address string and no other fields. Addresses in an attribute-only request (products) can leave out the deliverability fields. See Addresses.
What data does not include
Section titled “What data does not include”- A match confidence. Registered entities and brands carry no score.
match_confidenceappears only on watchlist hits. - A TIN or SSN you submit. It appears only in the
sourcesof thetin_verificationorssn_verificationtask.
Empty values
Section titled “Empty values”A field that your request returns is present even when Enigma has no value for it: a scalar is null and an array is []. There are two exceptions. A registered entity’s urls is left out when there are no source URLs. The four deliverability fields on an address (deliverable, virtual, delivery_type, rdi) can be missing when Enigma has no deliverability data for that address.
How records link
Section titled “How records link”Registered entities and brands are separate arrays that link by ID, through
brand_ids and registered_entity_ids. How to join them, and which record is
the match, is in
Which record is the match.
The risk_summary object
Section titled “The risk_summary object”risk_summary holds one field, tasks: an array of tasks, each run against the
match and each reporting one check. Find a task by its task_name and branch on
its result. The task object, the tasks each package runs and every result
value are on How checks work, starting with
Tasks by package.
How the response changes
Section titled “How the response changes”The baseline is a verify request at top_n=1, as in the example response. Each option below changes it. For the task-level detail, see When the task list changes.
| Request | What changes |
|---|---|
identify package (package=identify) |
risk_summary.tasks holds the four name and address tasks, followed by any add-on tasks you request. Registrations leave out jurisdiction_type, home_jurisdiction_state, status, sub_status and status_detail. See Packages. |
top_n above 1 |
No risk_summary. data.registered_entities and data.brands each hold up to top_n candidates, and their lengths can differ. watchlists is still returned when requested. See When top_n is above 1 and Matching. |
Add-on tasks in attrs |
At top_n=1, each requested task is added to the end of risk_summary.tasks. watchlist also adds the top-level watchlists array, at any top_n. tin_verification and ssn_verification require top_n=1 and return HTTP 400 otherwise. See Add-on tasks. |
Add-on attributes in attrs |
Each attribute is added to the object that holds it, as shown in the data tree. negative_news adds background_task. See Add-on attributes. |
Attribute-only request (products) |
data holds the IDs (the registered entity id, the brand id and registered_entity_ids) plus the attributes you named, with the containers and identifiers they need: a registration attribute also returns each registration’s addresses, a person attribute the person’s name, and an operating-location attribute each location’s id. risk_summary.tasks is [] unless you named watchlist, tin_verification or ssn_verification. See Attribute-only requests. |
| Person-only screen | data.registered_entities and data.brands are empty. The name and address tasks report their not-verified results. With verify, person_verification reports person_not_verified, domestic_registration reports domestic_not_found, and verification_tier reports tier_unknown. The watchlist task and watchlists carry the screening result. See Screen a person without a business. |
| No match | Still HTTP 200. data.registered_entities and data.brands are empty. The name, address and person tasks report their not-verified results, domestic_registration reports domestic_not_found, and verification_tier reports tier_unknown. See When nothing matches. |
Example response
Section titled “Example response”This request asks for the verify package with watchlist screening. It sends a business name, a website, a street address without a suite number, and one person.
curl --request POST "https://api.enigma.com/v2/kyb/?package=verify&attrs=watchlist" \ --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" } }'The response is complete. Its values are illustrative.
Look for these points in the response below:
- The address tasks report
address_match, not an exact match. The records carry a suite number (FL 17) that the request left out.address_verificationfound the address on a registration and on an operating location.sos_address_verificationchecks registrations only. - The name tasks differ. The submitted name exactly matches the brand name, so
name_verificationreportsname_exact_match. The registered name addsINC., sosos_name_verification, which checks registrations only, reportsname_match. - The submitted person matched a registered person. Jane Smith is named on the New York registration, so
person_verificationreportsperson_match. - The verification tier is
tier_1. Onlyhas_active_registrationandhas_einare incriteria.met, so the business’s existence rests on self-reported records.has_web_presencemeans an established web presence. See Verification tier. - Screening found nothing.
watchlistsis[]and thewatchlisttask reportswatchlist_no_hits.
{ "risk_summary": { "tasks": [ { "task_name": "address_verification", "status": "success", "result": "address_match", "reason": "An input address matches an address in any of Enigma's records", "sources": [ { "address": { "street_address1": "245 5TH AVE", "street_address2": "FL 17", "city": "NEW YORK", "state": "NY", "postal_code": "10016", "type": "headquarters", "deliverable": "deliverable", "virtual": "not_virtual", "delivery_type": "multi-tenant building", "rdi": "commercial" }, "match_entity_type": "registered_entity", "match_relationship_type": "registration_address", "urls": ["https://example.com/records/ny-5012345"] }, { "address": { "street_address1": "245 5TH AVE", "street_address2": "FL 17", "city": "NEW YORK", "state": "NY", "postal_code": "10016", "deliverable": "deliverable", "virtual": "not_virtual", "delivery_type": "multi-tenant building", "rdi": "commercial" }, "match_entity_type": "brand", "match_relationship_type": "operating_location_address", "urls": [] } ] }, { "task_name": "sos_address_verification", "status": "success", "result": "address_match", "reason": "An input address matches an address on a matching SoS registration", "sources": [ { "address": { "street_address1": "245 5TH AVE", "street_address2": "FL 17", "city": "NEW YORK", "state": "NY", "postal_code": "10016", "type": "headquarters", "deliverable": "deliverable", "virtual": "not_virtual", "delivery_type": "multi-tenant building", "rdi": "commercial" }, "match_entity_type": "registered_entity", "match_relationship_type": "registration_address" } ] }, { "task_name": "name_verification", "status": "success", "result": "name_exact_match", "reason": "An input business name exactly matches a business name in any of Enigma's records", "sources": [ { "name": "ENIGMA TECHNOLOGIES", "match_entity_type": "brand", "urls": [] } ] }, { "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" } ] }, { "task_name": "domestic_registration", "status": "success", "result": "domestic_active", "reason": "An active domestic registration was found", "sources": [ { "issue_date": "2011-04-26", "file_number": "4973743", "registration_state": "DE", "registered_name": "ENIGMA TECHNOLOGIES, INC." } ] }, { "task_name": "person_verification", "status": "success", "result": "person_match", "reason": "The person name matches a person name on a matching SoS registration", "sources": [ { "name": "JANE SMITH", "match_entity_type": "registered_entity" } ] }, { "task_name": "verification_tier", "status": "success", "result": "tier_1", "reason": "Tier 1 (Low): verification is supported by trust-based records such as corporate registration and EIN. These are self-reported and the accuracy of the information is neither validated nor corroborated by independent sources.", "criteria": { "met": ["has_active_registration", "has_ein"], "not_met": [ "has_reviews", "has_web_presence", "has_card_transactions", "has_substantial_review_history", "has_open_location", "has_government_record" ], "evidence": { "active_registration_count": 2, "review_count": 0, "website_count": 1, "total_review_count": 0, "open_location_count": 0 } } }, { "task_name": "watchlist", "status": "success", "result": "watchlist_no_hits", "reason": "No hits were identified on the consolidated sanctions list (including OFAC)" } ] }, "response_id": "2a1b3c4d-5e6f-7890-abcd-ef1234567890", "data": { "registered_entities": [ { "id": "4dccd7a5-790c-c4d1-0000-108000000000", "formation_date": "2011-04-26", "registered_entity_type": "Corporation", "names": [ { "name": "ENIGMA TECHNOLOGIES, INC." } ], "brand_ids": ["5f53e079-c66a-487e-8a9d-08efc39652ee"], "registrations": [ { "registration_state": "DE", "registered_name": "ENIGMA TECHNOLOGIES, INC.", "file_number": "4973743", "issue_date": "2011-04-26", "jurisdiction_type": "domestic", "home_jurisdiction_state": "DE", "status": "active", "sub_status": "good_standing", "status_detail": "Active", "persons": [ { "name": "CORPORATION SERVICE COMPANY", "titles": ["registered agent"] } ], "addresses": [ { "street_address1": "251 LITTLE FALLS DR", "street_address2": null, "city": "WILMINGTON", "state": "DE", "postal_code": "19808", "type": "registered_agent", "deliverable": "deliverable", "virtual": "not_virtual", "delivery_type": "street", "rdi": "commercial", "urls": ["https://example.com/records/de-4973743"] } ] }, { "registration_state": "NY", "registered_name": "ENIGMA TECHNOLOGIES, INC.", "file_number": "5012345", "issue_date": "2014-06-15", "jurisdiction_type": "foreign", "home_jurisdiction_state": "DE", "status": "active", "sub_status": "good_standing", "status_detail": "Active", "persons": [ { "name": "JANE SMITH", "titles": ["chief executive officer"] } ], "addresses": [ { "street_address1": "245 5TH AVE", "street_address2": "FL 17", "city": "NEW YORK", "state": "NY", "postal_code": "10016", "type": "headquarters", "deliverable": "deliverable", "virtual": "not_virtual", "delivery_type": "multi-tenant building", "rdi": "commercial", "urls": ["https://example.com/records/ny-5012345"] } ] } ], "addresses": [], "urls": [ "https://example.com/records/de-4973743", "https://example.com/records/ny-5012345" ] } ], "brands": [ { "id": "5f53e079-c66a-487e-8a9d-08efc39652ee", "registered_entity_ids": ["4dccd7a5-790c-c4d1-0000-108000000000"], "activities": { "activities": [] }, "names": [ { "name": "ENIGMA TECHNOLOGIES" } ], "websites": ["https://enigma.com"], "operating_locations": [ { "id": "20e8d448-f6c7-4854-9855-f8367b97b097", "names": [ { "name": "ENIGMA TECHNOLOGIES" } ], "addresses": [ { "street_address1": "245 5TH AVE", "street_address2": "FL 17", "city": "NEW YORK", "state": "NY", "postal_code": "10016", "deliverable": "deliverable", "virtual": "not_virtual", "delivery_type": "multi-tenant building", "rdi": "commercial" } ] } ], "industries": [ { "classification_description": "Software Publishers", "classification_type": "naics_2022_code", "classification_code": "513210" } ] } ] }, "watchlists": []}Related
Section titled “Related”POST /v2/kyb/: the request that returns this response.- Matching: how Enigma picks the
records in
data, and whattop_nandmatch_thresholddo. - Registered entities,
Brands and
Addresses: every field under
data. - How checks work: every task in
risk_summary, its results and its sources. - Errors and rate limits: the bodies of non-200 responses.