KYB Response data Object

The data object returned in the KYB API response is a structured compilation of attributes describing entities in Enigma’s data model that best match the information provided in the request. The response is structured as arrays of:

• registered_entities
  • which can have many registrations
    • which can have many persons
    • which can have many addresses
• brands
  • which can operate in many industries
  • which can operate at many operating locations
    • each of which is located at an address

Together, these attributes offer a holistic perspective of a business and its relationship to people and places. They are the basis on which tasks verify the information you provide about a business.

registered_entities attributes

These attributes are included for each registered entity, also known as a legal entity, returned in the response. By default, up to one registered entity is returned, but more can be returned by specifying a greater number via the top_n parameter. See Advanced Query Parameters for more information.

Attribute	Description	Example
id	Enigma’s unique ID for the registered entity.	350806dc-5617-7c57-0000-10c000000000
formation_date	The earliest non-null issue_date from the entity's registrations, formatted YYYY-MM-DD.	2011-04-26
registered_entity_type	The standardized legal form of the entity. See entity type values below.	Corporation
names	Array of up to ten standardized names of the entity, derived from the name as listed on the entity's registration.	[{"name": "ENIGMA TECHNOLOGIES, INC."}]
brand_ids	Array of Brand IDs associated with the registered entity. Use these to join to the corresponding entries in the brands array — particularly useful when top_n > 1 returns multiple candidate matches.	5f53e079-c66a-487e-8a9d-08efc39652ee
registrations	Array of all registrations associated with the registered entity. See registrations attributes for more information.	See registrations attributes.

registered_entity_type values

Value
Corporation
Non-profit Corporation
Non-stock Corporation
Professional Corporation
Limited Liability Company
Non-profit Limited Liability Company
Professional Limited Liability Company
Limited Partnership
Non-profit Limited Partnership
Professional Limited Partnership
General Partnership
Co-operative
Non-profit Co-operative
Non-stock Co-operative
Limited Cooperative Association
Unincorporated Non-profit Association
Sole Proprietorship
Unknown

registrations attributes

Legal entities must file a registration with the Secretary of State (SoS) of each U.S. state that they operate in. Enigma sources and standardizes legal entity registrations from all applicable U.S. jurisdictions, including all 50 states, as well as Washington DC and Puerto Rico. These attributes are included for each registration returned in the registrations array.

Attribute	Description	Example
registration_state	The US state where the registration was filed.	DE
jurisdiction_type	foreign if the registration is for any state other than the business's home state; otherwise, domestic. Only included in the verify package.	domestic
home_jurisdiction_state	Two-letter abbreviation for the state jurisdiction of the business. Only included in the verify package.	NY
registered_name	Business name as on the registration filing.	ENIGMA TECHNOLOGIES, INC.
file_number	File number of the registration filing.	4973743
issue_date	Issue date of the registration filing, formatted YYYY-MM-DD.	2011-04-26
status	Standardized status of the standing of the registration. Possible values include active, inactive, or unknown. Only included in the verify package.	active
sub_status	If available from the state, a normalized sub-status for the business. Possible values include good_standing, not_good_standing, pending_active, pending_inactive, unknown, and null. Only included in the verify package.	good_standing
status_detail	If available, the official filing status message provided by the state. Only included in the verify package.	Permanently Revoked
persons	Array of up to ten persons named on the registration filing. See persons attributes for more information.	See persons attributes.
addresses	Array of up to ten addresses listed on the registration filing. See addresses attributes for more information.	See addresses attributes.

persons attributes

These attributes are included for each person returned in the persons array.

Attribute	Description	Example
name	The name of the person named on the registration filing.	HICHAM OUDGHIRI
titles	Array of titles for the person named on the registration filing.	["chief executive officer"]

addresses attributes

These attributes are included for each address, of which there can be up to ten per registration or operating_location.

Attribute	Description	Example
street_address1	The main street address with number, name, and directionals using USPS standards.	245 5TH AVE
street_address2	Additional address information like unit, suite or floor number using USPS abbreviations.	FL 17
city	The city where this address is located.	NEW YORK
state	The two-letter abbreviation of the U.S. state or territory.	NY
postal_code	The current five-digit U.S. postal code of the address.	10016
type	The standardized address type as it appears on the registration with the relevant Secretary of State. Only present on registration addresses — not included on operating location addresses. See address type descriptions below.	registered
deliverable	Whether the address is deliverable per USPS delivery point validation. Possible values: deliverable, not_deliverable, vacant, no_stat.	vacant
virtual	Whether the address is associated with a Commercial Mail Receiving Agency (CMRA), indicating a virtual or mailbox address. Possible values: virtual, not_virtual.	not_virtual
delivery_type	The type of mail delivery for this address. Possible values include rural route or highway contract route, general delivery, street, post office box, multi-tenant building, firm, and null	multi-tenant building
rdi	Whether USPS identifies the address as residential or commercial. Possible values: residential, commercial.	commercial

Address type values

Value	Description
headquarters	The principal place of business. This is the most meaningful address for verifying where a business actually operates.
registered	The address listed on the SoS registration filing, which may differ from the physical operating address.
registered_agent	The address of the registered agent — a third party designated to receive legal notices on behalf of the entity. This address often belongs to a law firm or professional agent service, not the business itself. Do not use this address for business location verification.
officer	The personal address of a named officer or director listed on the registration.
mailing	A mailing address for the entity, which may be a P.O. box or forwarding address.
site	A physical location associated with the entity, as listed on the filing.

brands attributes

These attributes are included for each brand returned in the brands array. By default, one brand is returned, but you can retrieve more by specifying a greater number via the top_n parameter. See Advanced Query Parameters for more information.

Attribute	Description	Example
id	Enigma’s unique ID for the brand.	5f53e079-c66a-487e-8a9d-08efc39652ee
registered_entity_ids	Array of registered entity IDs associated with the brand. Use these to join to the corresponding entries in the registered_entities array — the counterpart to registered_entity.brand_ids.	350806dc-5617-7c57-0000-10c000000000
activities	Object with a single key activities, whose value is an array of notable activities the brand is engaged in. See Brand Activity for more information.	{"activities": ["Cannabis"]}
names	The customer-facing version of the names that represent the business. See Brand Name for more information.	[{"name": "ENIGMA TECHNOLOGIES"}]
industries	Array of industries that the brand does business in. See industries attributes for more information.	See industries attributes.
websites	Array of websites associated the brand.	https://enigma.com
operating_locations	Array of operating locations that the brand operates. See operating_locations attributes for more information.	See operating_locations attributes.

industries attributes

These attributes are included for each industry returned in the industries array.

Attribute	Description	Example
classification_description	Human-readable description of the industry. For industries with an industry_type that is an industry classification system, this will be the description corresponding to industry_code, provided by the developer of the industry classification system.	Software Publishers
classification_type	The classification system used. Possible values are naics_2017_code, naics_2022_code, sic_code, mcc_code, and enigma_industry_description. The enigma_industry_description is a non-hierarchical, colloquial classification that often expresses dimensions of a business that are unavailable in standard industry classification systems (e.g. the style of food offered by a restaurant).	naics_2022_code
classification_code	The numeric value of the industry code. This field only contains a value for certain industry classification systems (The industry_type indicates the industry classification system). For all other classification system, this field is null.	513210

operating_locations attributes

These attributes are included for each operating location returned in the operating_locations array.

Attribute	Description	Example
id	Enigma’s unique ID for the operating location.	20e8d448-f6c7-4854-9855-f8367b97b097
addresses	Array of up to ten addresses associated with this operating location. See addresses attributes for more information.	See addresses attributes.
names	Array of up to ten name objects associated with this operating location. Each object has a single name key containing the name string.	[{"name": "ENIGMA TECHNOLOGIES"}]

Available add-on attributes

Optionally, additional attributes can be requested via the attrs parameter. See advanced query parameters for more information on how to request add-on attributes.

Attribute	Included in	Description	Example
bankruptcies	registered_entities	The details of bankruptcy filings (chapter_type, filing date and case number etc.) associated with this legal entity. All bankruptcy cases are handled in federal courts under rules outlined in the U.S. Bankruptcy Code.	See bankruptcy for more information.
avg_transaction_size	brands.card_transactions	The average transaction size in dollars for the location for the latest time period.	See card transactions for more information.
card_transactions_count	brands.card_transactions	The total number of card transactions for the location for the latest time period.	See card transactions for more information.
card_revenue_amount	brands.card_transactions	The sum of all transaction amounts in dollars for the location for the latest time period.	See card transactions for more information.
card_revenue_yoy_growth	brands.card_transactions	The ratio of the location's latest time period revenue to the same period one year prior.	See card transactions for more information.
card_revenue_prior_period_growth	brands.card_transactions	The ratio of the location's latest time period revenue to the previous period.	See card transactions for more information.
card_customers_average_daily_count	brands.card_transactions	The average number of unique daily customers for the location for the latest time period.	See card transactions for more information.
has_transactions	brands.card_transactions	1 if the location had any transactions in the latest time period, 0 otherwise.	See card transactions for more information.
refunds_amount	brands.card_transactions	The total amount of refunds in dollars for the location for the latest time period.	See card transactions for more information.
operating_status	operating_locations	This field reflects the operational state of the brand at this address during the time period shown. Possible values include Open, Closed, Temporarily Closed, and Unknown.	Open
phone_numbers	operating_locations	Twelve-digit string representation of the complete phone number.	+12544454098
person_addresses	registered_entities.registrations.persons	The addresses connected to each person on the registration. Non-person agents will have empty addresses. If this attribute is enabled, the person addresses will be included in address verification.