- Docs
- API reference
- Endpoints and schemas
- KYB API
- Response
Brands
The businesses as customers know them, with their industries, websites, card activity and operating locations.
A brand is a business under the name customers see on a storefront, a website or a receipt. That name can differ from the legal name on the business’s Secretary of State registrations, which Enigma returns on the registered entity. Brands sit in the data.brands array of the response object, and matching decides which ones appear. With top_n=1, the default, the array holds at most one brand; with a higher top_n, it holds up to top_n.
The identify and verify packages return the same brand fields. Add-on attributes add card transactions to the brand, and phone numbers and operating status to its operating locations.
Here is one brand, trimmed from the full example at the end of this page.
{ "id": "5f53e079-c66a-487e-8a9d-08efc39652ee", "registered_entity_ids": ["4dccd7a5-790c-c4d1-0000-108000000000"], "names": [{ "name": "ENIGMA TECHNOLOGIES" }], "websites": ["https://enigma.com"], "activities": { "activities": [] }, "industries": [ { "classification_type": "naics_2022_code", "classification_code": "513210", "classification_description": "Software Publishers" } ], "operating_locations": [ { "id": "20e8d448-f6c7-4854-9855-f8367b97b097", "names": [{ "name": "ENIGMA TECHNOLOGIES" }], "addresses": [{ "street_address1": "245 5TH AVE", "city": "NEW YORK", "state": "NY" }], "phone_numbers": [{ "phone_number": "+12125550100" }], "operating_status": "Open" } ], "card_transactions": { "card_transactions_count": [ { "start_date": "2026-04-01", "end_date": "2026-06-30", "period": "3m", "projected_quantity": 21387 } ] }}The brand object
Section titled “The brand object”idEnigma’s ID for the brand. Treat it as an opaque string.
registered_entity_idsThe
idof each registered entity linked to this brand. See How a brand links to registered entities.namesThe brand’s names. Each object has one key,
name(string or null).websitesThe brand’s website, as a full URL.
activitiesHigh-risk activities the brand is engaged in, such as
Cannabis. See Activities.industriesThe brand’s industry classifications. See Industries.
operating_locationsThe physical locations the brand operates. See Operating locations.
card_transactionsCard transactions, with one key per card-transaction value you request. Returned only when you request a card-transaction value. See Card transactions.
Every field your request returns is present on every brand. An empty list is [], never omitted. A brand has no addresses of its own; its addresses are on its operating locations.
How a brand links to registered entities
Section titled “How a brand links to registered entities”Brands and registered entities are separate arrays. brands[].registered_entity_ids holds the id of each linked registered entity, and registered_entities[].brand_ids holds the id of each linked brand. Join the two by these IDs, never by array position: the brand at index 0 does not necessarily belong to the registered entity at index 0. See How records link.
An ID in registered_entity_ids can refer to a registered entity that is not in data.registered_entities, because the response holds at most top_n registered entities. Even with top_n=1, the returned brand and registered entity are not guaranteed to be linked, so check the IDs before you treat them as one business.
A brand has no bankruptcies of its own. To find the bankruptcy filings behind a brand, follow registered_entity_ids to the matching entries in data.registered_entities that are present in the response, and read their bankruptcies.
Activities
Section titled “Activities”activities is an object with one key, activities, whose value is an array of strings. Each string names one high-risk activity the brand is engaged in, such as Cannabis. The array is often empty, which means Enigma has recorded no such activity for the brand.
{ "activities": { "activities": ["Cannabis"] }}Industries
Section titled “Industries”Each object in industries is one classification of the brand in one classification system.
classification_typeThe classification system. See Classification types.
classification_codeThe code in that system, such as
513210. Keep it as a string.nullforenigma_industry_description, which has no codes.classification_descriptionA readable description of the industry. For a coded system, this is the publisher’s title for the code.
Classification types
Section titled “Classification types”| Value | Meaning |
|---|---|
naics_2017_code |
North American Industry Classification System, 2017 edition. |
naics_2022_code |
North American Industry Classification System, 2022 edition. |
sic_code |
Standard Industrial Classification. |
mcc_code |
Merchant Category Code, as assigned by the card networks. |
enigma_industry_description |
Enigma’s own plain-language description, not hierarchical. It can capture detail the standard systems miss, such as the cuisine a restaurant serves. |
This list is not closed. Handle a classification_type value not listed here without failing.
Operating locations
Section titled “Operating locations”Each object in operating_locations is one physical location the brand operates.
idEnigma’s ID for the operating location. Treat it as an opaque string.
namesThe names the location operates under. Each object has one key,
name(string or null).addressesThe location’s addresses, with those that match your input first. Each uses the shared address object with its USPS deliverability fields, but without
type.phone_numbersThe location’s phone numbers. Each object has one key,
phone_number(string or null), usually in E.164 style, such as+12125550100. Only with thephone_numbersadd-on.operating_statusWhether the brand is operating at this location. See Operating status values. Only with the
operating_statusadd-on.
Operating status values
Section titled “Operating status values”| Value | Meaning |
|---|---|
Open |
The brand is operating at this location. |
Closed |
The brand has closed permanently at this location. |
Temporarily Closed |
The brand is not operating at this location now, but has not closed permanently. |
Unknown |
Enigma does not have enough information to tell. Also returned when Enigma has no status for the location. |
operating_status can be null. Treat null like Unknown.
The address_verification task also checks operating-location addresses. When one backs the task result, its entry in sources has match_entity_type: brand and match_relationship_type: operating_location_address. See Sources.
Card transactions
Section titled “Card transactions”Card transactions show whether a brand takes card payments, and how much: counts, revenue, customers and refunds. To get them, name one or more card-transaction values in attrs (with either package) or in products. Passing card_transactions itself in attrs or products returns 400. Name the individual values instead. See Card-transaction values on the add-ons page.
card_transactions is an object with one key for each card-transaction value you request. Read each key by name. Each key holds an array of period objects, and the array is [] when Enigma has no card transactions for that value.
{ "card_transactions_count": [ { "end_date": "2026-06-30", "start_date": "2026-04-01", "period": "3m", "projected_quantity": 21387 } ]}The period object
Section titled “The period object”start_dateThe first day of the period, as
YYYY-MM-DD.end_dateThe last day of the period, as
YYYY-MM-DD.periodA label for the length of the period, such as
3m. The set of labels is not fixed, so do not branch on it.projected_quantityThe value for the period. Its meaning and unit depend on the key it sits under. See Card-transaction values.
Card-transaction values
Section titled “Card-transaction values”For each card-transaction value, the table gives the meaning of projected_quantity in its period objects.
Show the 8 values
| Value | Meaning |
|---|---|
avg_transaction_size |
The average card transaction size, in dollars. |
card_transactions_count |
The total number of card transactions. |
card_revenue_amount |
The sum of all card transaction amounts, in dollars. |
card_revenue_yoy_growth |
The ratio of the period’s card revenue to the same period one year earlier. |
card_revenue_prior_period_growth |
The ratio of the period’s card revenue to the previous period. |
card_customers_average_daily_count |
The average number of unique customers per day. |
has_transactions |
1 if the brand had any card transactions in the period, 0 otherwise. |
refunds_amount |
The total amount refunded, in dollars. |
Attribute-only requests
Section titled “Attribute-only requests”In an attribute-only request (products), a brand carries only id, registered_entity_ids and the attributes you name. A card-transaction value adds card_transactions. phone_numbers or operating_status adds operating_locations, where each location has its id and the attributes you named.
Limits
Section titled “Limits”Each list below has a maximum length. When Enigma holds more items, the response truncates the list and does not say so.
| List | Maximum |
|---|---|
data.brands |
top_n brands. |
registered_entity_ids |
10 IDs per brand. |
names |
10 names per brand. |
websites |
1 URL per brand. |
industries |
10 classifications per brand. |
activities.activities |
10 activities per brand. |
operating_locations |
30 locations per brand. |
operating_locations[].names |
10 names per operating location. |
operating_locations[].addresses |
10 addresses per operating location. |
operating_locations[].phone_numbers |
10 numbers per operating location. |
card_transactions |
50 period objects per brand, across all the values you request. |
Example
Section titled “Example”This request matches Enigma Technologies with the identify package and adds phone numbers, operating status and two card-transaction values.
curl --request POST "https://api.enigma.com/v2/kyb/?package=identify&attrs=phone_numbers,operating_status,card_transactions_count,card_revenue_amount" \ --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 is trimmed to the brand: risk_summary and data.registered_entities are left out. Its values, including the period labels, are illustrative.
{ "response_id": "2a1b3c4d-5e6f-7890-abcd-ef1234567890", "data": { "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", "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" } ], "names": [ { "name": "ENIGMA TECHNOLOGIES" } ], "phone_numbers": [ { "phone_number": "+12125550100" } ], "operating_status": "Open" } ], "industries": [ { "classification_description": "Software Publishers", "classification_type": "naics_2022_code", "classification_code": "513210" }, { "classification_description": "Business data and analytics", "classification_type": "enigma_industry_description", "classification_code": null } ], "card_transactions": { "card_transactions_count": [ { "end_date": "2026-06-30", "start_date": "2026-04-01", "period": "3m", "projected_quantity": 21387 } ], "card_revenue_amount": [ { "end_date": "2026-06-30", "start_date": "2026-04-01", "period": "3m", "projected_quantity": 1840250.75 } ] } } ] }}What to notice:
- The brand links by ID.
registered_entity_idsholds theidof the matched registered entity. That entity’sbrand_ids(not in this trimmed example) holds this brand’sid. - The operating-location address has no
type. Only registration addresses carrytype. - The Enigma industry description has no code. Its
classification_codeisnull. - Card transactions are keyed by value.
card_transactionshas one key for each card-transaction value requested, and each holds an array of periods.
Related
Section titled “Related”- Response object: where
data.brandssits in the response, and how records link. - Matching: how Enigma matches brands, and how
top_nchanges the number returned. - Registered entities: the legal entities that brands link to, with their registrations and bankruptcies.
- Addresses: the address object and its deliverability fields.
- Add-ons: how to request card transactions, phone numbers and operating status.