Skip to content
Console(opens in a new tab)

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.

Brand
{
"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 }
]
}
}
idstring

Enigma’s ID for the brand. Treat it as an opaque string.

registered_entity_idsarray of string

The id of each registered entity linked to this brand. See How a brand links to registered entities.

namesarray of object

The brand’s names. Each object has one key, name (string or null).

websitesarray of string

The brand’s website, as a full URL.

activitiesobject

High-risk activities the brand is engaged in, such as Cannabis. See Activities.

industriesarray of object

The brand’s industry classifications. See Industries.

operating_locationsarray of object

The physical locations the brand operates. See Operating locations.

card_transactionsobject

Card 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.

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 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.

Example activities field
{
"activities": {
"activities": ["Cannabis"]
}
}

Each object in industries is one classification of the brand in one classification system.

classification_typestring or null

The classification system. See Classification types.

classification_codestring or null

The code in that system, such as 513210. Keep it as a string. null for enigma_industry_description, which has no codes.

classification_descriptionstring or null

A readable description of the industry. For a coded system, this is the publisher’s title for the code.

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.

Each object in operating_locations is one physical location the brand operates.

idstring or null

Enigma’s ID for the operating location. Treat it as an opaque string.

namesarray of object

The names the location operates under. Each object has one key, name (string or null).

addressesarray of object

The 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_numbersarray of object

The location’s phone numbers. Each object has one key, phone_number (string or null), usually in E.164 style, such as +12125550100. Only with the phone_numbers add-on.

operating_statusstring or null

Whether the brand is operating at this location. See Operating status values. Only with the operating_status add-on.

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 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.

Example card_transactions
{
"card_transactions_count": [
{
"end_date": "2026-06-30",
"start_date": "2026-04-01",
"period": "3m",
"projected_quantity": 21387
}
]
}
start_datestring

The first day of the period, as YYYY-MM-DD.

end_datestring

The last day of the period, as YYYY-MM-DD.

periodstring

A label for the length of the period, such as 3m. The set of labels is not fixed, so do not branch on it.

projected_quantitynumber

The value for the period. Its meaning and unit depend on the key it sits under. See 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.

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.

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.

This request matches Enigma Technologies with the identify package and adds phone numbers, operating status and two card-transaction values.

cURL
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"
}
}'

What to notice:

  • The brand links by ID. registered_entity_ids holds the id of the matched registered entity. That entity’s brand_ids (not in this trimmed example) holds this brand’s id.
  • The operating-location address has no type. Only registration addresses carry type.
  • The Enigma industry description has no code. Its classification_code is null.
  • Card transactions are keyed by value. card_transactions has one key for each card-transaction value requested, and each holds an array of periods.
  • Response object: where data.brands sits in the response, and how records link.
  • Matching: how Enigma matches brands, and how top_n changes 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.