Skip to content
Console(opens in a new tab)

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.

A verify request with watchlist screening, trimmed to one task and the IDs that link the records. The full response is in Example response.

200 OK
{
"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": []
}
dataobjectAlways

The registered entities and brands Enigma matched. How Enigma picks them is on Matching. Their fields are on Registered entities, Brands and Addresses. See The data object.

risk_summaryobjectWhen top_n=1

The tasks run against the match, one per check. Present only when top_n=1, the default. See How checks work.

watchlistsarrayWith watchlist

Present when you request watchlist screening (watchlist in attrs or products), at any top_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_taskobjectWith negative_news

Present when you request negative_news (in attrs or products) and at least one registered entity matched. Also absent when the news lookup failed for every matched entity, so a missing background_task does not mean no negative news was found. Holds negative news results, or a task ID to poll. See Negative news.

response_idstringAlways

Identifies 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 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 the person_addresses add-on.
      • addresses[]: the addresses on the registration, with their type, such as headquarters or registered_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 the bankruptcies add-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 the phone_numbers add-on.
      • operating_status: whether the location is open. Only with the operating_status add-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.

  • A match confidence. Registered entities and brands carry no score. match_confidence appears only on watchlist hits.
  • A TIN or SSN you submit. It appears only in the sources of the tin_verification or ssn_verification task.

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.

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.

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.

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.

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
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_verification found the address on a registration and on an operating location. sos_address_verification checks registrations only.
  • The name tasks differ. The submitted name exactly matches the brand name, so name_verification reports name_exact_match. The registered name adds INC., so sos_name_verification, which checks registrations only, reports name_match.
  • The submitted person matched a registered person. Jane Smith is named on the New York registration, so person_verification reports person_match.
  • The verification tier is tier_1. Only has_active_registration and has_ein are in criteria.met, so the business’s existence rests on self-reported records. has_web_presence means an established web presence. See Verification tier.
  • Screening found nothing. watchlists is [] and the watchlist task reports watchlist_no_hits.
200 OK
{
"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": []
}