- Docs
- API reference
- Endpoints and schemas
- KYB API
- Response
Registered entities
The legal entities Enigma matched, with their Secretary of State registrations, the people named on them, and their addresses.
A registered entity is a legal entity that files with a Secretary of State (SoS): a corporation, an LLC or a partnership, for example. Registered entities sit in the data.registered_entities array of the response object, and matching decides which ones appear: the registered entities that match your input, up to top_n of them (default 1). The business as customers know it is a separate object, the brand.
The identify package returns less of each registration than verify; see The registration object. Add-on attributes add bankruptcies and the addresses of registered persons. The API sometimes calls a registered entity a legal entity: legal_entity_id in a bankruptcy and in a negative news subtask holds a registered entity’s id.
A registered entity from the verify package, without add-ons and trimmed to one registration, looks like this. For the whole entity with both add-ons, see the full example.
{ "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", "type": "registered_agent" }] } ], "addresses": [], "urls": ["https://example.com/records/de-4973743"]}The registered entity object
Section titled “The registered entity object”idEnigma’s ID for the registered entity. Always present, including in attribute-only requests. Treat it as an opaque string. Brands point to it in
registered_entity_ids.formation_dateThe entity’s formation date, as
YYYY-MM-DD.nullwhen unknown.registered_entity_typeThe entity’s legal form, standardized across states. See Registered entity types.
namesThe entity’s legal names. Each object has one key,
name(string or null). Up to 10.brand_idsThe
idof each brand linked to this entity, up to 10. The response returns at mosttop_nbrands, so an ID here can be missing fromdata.brands. Join by ID, never by array position. See How records link.registrationsThe entity’s Secretary of State registrations. See The registration object.
addressesMailing addresses Enigma holds for the entity that do not already appear under a registration.
[]when there are none. These addresses have notype. See Addresses.urlsThe source URLs of the records behind the entity, sorted and without duplicates. Left out when there are none.
bankruptciesWithbankruptciesBankruptcy filings on the entity. Only with the
bankruptciesadd-on. See Bankruptcies.
Every field except urls and bankruptcies is present even when Enigma has no value for it: a scalar is null and an array is []. See Empty values.
Registered entity types
Section titled “Registered entity types”registered_entity_type takes one of these values, or null when Enigma has no legal form for the entity.
Show the 18 values
| Value | Meaning |
|---|---|
Corporation |
A for-profit corporation with shareholders and limited liability. |
Non-profit Corporation |
A corporation organized for a nonprofit purpose. |
Non-stock Corporation |
A corporation with no shares, such as a membership or mutual benefit organization. |
Professional Corporation |
A corporation restricted to licensed professionals, such as doctors or lawyers. |
Limited Liability Company |
A company whose owners (members) have limited liability. |
Non-profit Limited Liability Company |
An LLC organized for a nonprofit purpose. |
Professional Limited Liability Company |
A PLLC: an LLC restricted to licensed professionals. |
Limited Partnership |
A partnership with at least one general partner and one limited partner. |
Non-profit Limited Partnership |
A limited partnership organized for a nonprofit purpose. |
Professional Limited Partnership |
A limited partnership restricted to licensed professionals. |
General Partnership |
A partnership in which every partner has unlimited liability. |
Co-operative |
A business owned and governed by its members. |
Non-profit Co-operative |
A cooperative organized for a nonprofit purpose. |
Non-stock Co-operative |
A cooperative based on membership rather than shares. |
Limited Cooperative Association |
A cooperative that admits investor members alongside patron members. |
Unincorporated Non-profit Association |
A nonprofit group that never incorporated. |
Sole Proprietorship |
An unincorporated business with one owner. Most states do not require one to register, so domestic_registration often returns domestic_not_found. See domestic_registration. |
Unknown |
Enigma could not standardize the entity’s legal form. |
The registration object
Section titled “The registration object”A registration is one filing with a Secretary of State. An entity has a domestic registration in its home state, the state where it was formed, and can have foreign registrations in other states where it does business. Enigma standardizes registrations from all 50 states, Washington, DC, and Puerto Rico.
registration_stateThe two-letter code of the state where the registration was filed.
registered_nameThe business name as it appears on the registration.
file_numberThe file number the state assigned to the registration.
issue_dateThe date the state issued the registration, as
YYYY-MM-DD.jurisdiction_typeverifyonlydomesticwhen filed in the home state,foreignwhen filed in another state,unknownwhen the home state is not known.home_jurisdiction_stateverifyonlyThe two-letter code of the entity’s home state. Often
null. Theregistration_stateof the registration whosejurisdiction_typeisdomesticis also the home state.statusverifyonlyThe standardized standing of the registration. See Registration status values.
sub_statusverifyonlyA finer standing, when the state supplies one. See Registration status values.
status_detailverifyonlyThe state’s own status message, word for word, for example
ActiveorPermanently Revoked.personsThe people and organizations named on the registration. See Registered persons.
addressesThe addresses on the registration, up to 10, with the addresses that match your input first. Each has a
type, such asheadquartersorregistered_agent. See Addresses.
The domestic_registration task reads these fields for you: it finds the domestic registration and reports its status as a task result.
Registration status values
Section titled “Registration status values”Branch on status and sub_status. status_detail is free text in each state’s own wording and varies by state. status, sub_status and status_detail can each be null.
status takes one of these values:
| Value | Meaning |
|---|---|
active |
The registration is in force with the state. |
inactive |
The registration has lapsed, or has been dissolved, revoked or withdrawn. |
unknown |
The state supplied no usable status. |
sub_status takes one of these values:
| Value | Meaning |
|---|---|
good_standing |
The state reports the entity as meeting its filing obligations. |
not_good_standing |
The entity is out of compliance with the state, for example late on reports or fees. |
pending_active |
The registration is in the process of becoming active. |
pending_inactive |
The registration is in the process of becoming inactive, for example during a dissolution. |
unknown |
The state supplied a sub-status that could not be standardized. |
Registered persons
Section titled “Registered persons”registrations[].persons lists the officers, directors and registered agents named on a registration. A registered person can be an organization: when a company fills a role, such as a registered agent service, name is the company’s name. Each name appears once per registration, with every title it holds there.
A registered person is not the person you submit in the request. The person_verification task compares your submitted person with the registered persons.
nameThe person’s full name, or the organization’s name.
titlesThe person’s titles on this registration, in lowercase free text, for example
registered agentorchief executive officer. An element isnullwhen the registration gives no title.addressesWithperson_addressesOnly with the
person_addressesadd-on. The addresses Enigma links to the person, withouttype.[]for an organization.
A person’s address can have null street fields, and in some cases is {"full_address": "..."} instead, with the whole address as one string. Once you request person_addresses, these addresses also count toward address_verification.
Bankruptcies
Section titled “Bankruptcies”bankruptcies lists the bankruptcy filings on a registered entity, up to 10. It is present only when you request the bankruptcies add-on, and is [] when the entity has none. To find the filings for a brand, follow its registered_entity_ids to the matching registered entities.
case_numberThe U.S. District Court docket number of the case.
chapter_typeThe bankruptcy chapter, for example
7(liquidation) or11(reorganization). Treat the value as text; do not assume it is a number.filing_dateThe date the bankruptcy was filed, as
YYYY-MM-DD.legal_entity_idEnigma’s ID for the registered entity the bankruptcy is associated with.
debtor_nameThe debtor’s name on the bankruptcy filing.
petitionThe nature of the petition, for example
voluntaryorinvoluntary.judgeThe judge presiding over the case.
entry_dateThe date the case was entered, as
YYYY-MM-DD.date_convertedThe date the case was converted to another chapter, as
YYYY-MM-DD.date_dismissedThe date the case was dismissed, as
YYYY-MM-DD.date_terminatedThe date of the final docket entry, when the case closed, as
YYYY-MM-DD.debtor_discharged_dateThe date the court discharged the debtor, as
YYYY-MM-DD.
Enigma can add fields to this object. Ignore fields you do not recognize.
Attribute-only requests
Section titled “Attribute-only requests”In an attribute-only request (products), a registered entity always has its id, plus only what the attributes you name add:
| Attribute | Adds to the registered entity |
|---|---|
registration.<field> |
registrations, each with only the named fields plus addresses (the five street fields and type). |
person_addresses |
registrations, each with addresses and with persons holding only name and addresses (no titles). |
bankruptcies |
bankruptcies. |
Limits
Section titled “Limits”Most lists have a maximum length. When Enigma has more, the response includes only the first ones, and nothing in the response says that the list was cut short.
| List | Maximum |
|---|---|
data.registered_entities |
top_n registered entities (default 1). See Matching. |
names |
10 names per registered entity. |
brand_ids |
10 IDs per registered entity. |
registrations |
No fixed maximum, but the list can be incomplete. Enigma reads registrations from at most 10 underlying filings grouped under the entity, so an entity with more can have registrations the response does not show. |
registrations[].persons |
Names drawn from up to 10 roles per registration, each name once. |
registrations[].addresses |
10 addresses per registration, the addresses that match your input first. |
bankruptcies |
10 bankruptcy filings per registered entity. |
Example
Section titled “Example”This example shows a registered entity with a domestic and a foreign registration, a registered agent that is an organization, and both registered-entity add-ons. The request uses the verify package with bankruptcies and person_addresses.
curl --request POST \ "https://api.enigma.com/v2/kyb/?package=verify&attrs=bankruptcies,person_addresses" \ --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 trimmed to data.registered_entities, and its addresses are trimmed to the street fields, type and urls. For the deliverability fields, see Addresses. Its values are illustrative. For the full response to a similar request, see the Response object example.
{ "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": [] } ], "addresses": [ { "street_address1": "251 LITTLE FALLS DR", "street_address2": null, "city": "WILMINGTON", "state": "DE", "postal_code": "19808", "type": "registered_agent", "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" } ] } ], "addresses": [ { "street_address1": "245 5TH AVE", "street_address2": "FL 17", "city": "NEW YORK", "state": "NY", "postal_code": "10016", "type": "headquarters", "urls": ["https://example.com/records/ny-5012345"] } ] } ], "addresses": [], "urls": [ "https://example.com/records/de-4973743", "https://example.com/records/ny-5012345" ], "bankruptcies": [] } ] }}What to notice:
- One domestic and one foreign registration. The entity’s home state is Delaware, so the Delaware registration is
domestic. The New York registration isforeign, and itshome_jurisdiction_stateisDE. - The registered agent is an organization. Corporation Service Company is named as
registered agent, so itsaddressesis[]even withperson_addressesrequested. Its address on the registration has atypeofregistered_agent, which is not the business’s location. - Jane Smith appears as a registered person. She is named on the New York registration. Because you requested
person_addresses, heraddressesholds the addresses Enigma links to her, withouttype. Theperson_verificationtask compares thepersonyou sent with her. addresseson the entity is empty. Enigma holds no mailing address for this entity beyond the addresses already listed under its registrations.bankruptciesis[]. You requested the add-on and Enigma found no bankruptcy filings.- The IDs join.
brand_idsholds the brand’sid,5f53e079-c66a-487e-8a9d-08efc39652ee. That brand (not shown) lists this entity’sidin itsregistered_entity_ids.
Related
Section titled “Related”- Response object: where
data.registered_entitiessits, and how records link by ID. - Brands: the business as customers know it, and its operating locations.
- Addresses: the address object, address types and deliverability fields.
- Registration and person checks: the
domestic_registrationandperson_verificationtasks that read these fields. - Add-ons: the
bankruptciesandperson_addressesadd-ons.