- Docs
- Guides
- Build with Enigma
- GraphQL API
Gov Archive records
Get government records about a business, a person, or an address from the GraphQL API and the Python SDK.
This guide shows you how to search government records about a business using Gov Archive. You can query permits, violations, filings, licenses, and other regulatory records from 7,000+ federal, state, and municipal datasets, through the Python SDK or directly with the GraphQL API.
Before you begin
Section titled “Before you begin”- An Enigma account
- An Enigma API key, available in the Console under Settings > Account > API keys
Get records from a question with the Python SDK
Section titled “Get records from a question with the Python SDK”The Enigma Python SDK, enigma-api-client, turns a question in plain English into a GraphQL query and runs it. When your question names a business, location, person, or address and asks for its government records, the query selects them in two places:
- On each entity: the number of records Enigma links to that entity and, for some questions, a page of them.
- In archive searches: searches of Gov Archive by the same name, person, or street address, under keys that start with
archiveRecordsorarchiveBrandRecords. Each returns up to 50 of the records that name what it searched for, whether or not Enigma links them to an entity.
The SDK needs Python 3.11 or later and your Enigma API key.
pip install enigma-api-clientexport ENIGMA_API_KEY="your-api-key"import asyncioimport os
from enigma_api_client import Client, ClientConfig
async def main(): config = ClientConfig(enigma_api_key=os.environ["ENIGMA_API_KEY"]) async with Client(config) as client: response = await client.search(prompt="Show business licenses held by Walgreens") if not response.is_success(): raise RuntimeError(f"HTTP {response.status_code}: {response.errors}") for entity in response.data["search"]: print(entity["__typename"], "linked records:", entity.get("recordCount")) for key, items in response.data.items(): if key.startswith(("archiveRecords", "archiveBrandRecords")): for item in items or []: if item["__typename"] == "Record": print(key, item["sourceTitle"], item["data"])
asyncio.run(main())A question asks for records when it names a record type the SDK reads, such as UCC and lien filings, licenses, permits, inspections, violations, government contracts, PPP loans, SAM.gov registrations, Form 5500 benefit plans, or EPA records. The archive searches then keep only the records that carry a tag of the types the question names. A dataset can carry a record type’s tag without belonging to that type, so check sourceTitle. A question that asks for public or government records in general gets records of every type, unless it also names a type the SDK reads. Records aren’t sorted by date.
Each record has sourceTitle, sourceUrl, tags, firstObservedDate, lastObservedDate, and data, the original row as key-value pairs. sourceUrl links to the dataset, not to the row, and can be null. The observed dates tell you when Enigma first and last saw the row; the record’s own dates, such as a filing date, are in data. See Record for every field.
Get government records in the Python SDK guide lists every record type a question can ask for, the fields each entity gets, which archive searches a query gets, and how to read more of an entity’s records. Each archive search is an UNGROUNDED search; for every record a search finds, page by page, use a RECORD search.
Query records with GraphQL
Section titled “Query records with GraphQL”The GraphQL API returns Gov Archive records alongside Enigma’s business data. Send each query as the query field of a JSON body in a POST request to https://api.enigma.com/graphql, with your API key in the x-api-key header. Each record is one row of a government dataset.
You can get records in three ways:
- Linked records: records that Enigma has matched to a business, person, or address. You reach them through the
recordsfield of an entity such as a legal entity, brand, operating location, person, or address, and you can count, filter, and page through them. UNGROUNDEDsearch results: records whose stated business name, person name, or address matches your search. SetdataLayer: UNGROUNDEDin a search to get them asRecordresults.- A
RECORDsearch: every linked record a search finds and, withdataLayer: UNGROUNDED, the records matched by name or address, with paging and totals. SetentityType: RECORD.
Get a business’s linked records
Section titled “Get a business’s linked records”query { search(searchInput: {name: "Starbucks Corporation", entityType: LEGAL_ENTITY, conditions: {limit: 1}}) { ... on LegalEntity { id recordTotal: count(field: "records") records(first: 10) { pageInfo { hasNextPage endCursor } edges { node { sourceTitle sourceUrl tags firstObservedDate data } } } } }}| Field | Description |
|---|---|
sourceTitle |
The dataset’s title as published by its source |
sourceDescription |
The dataset’s description as published by its source |
sourceUrl |
A link to the source dataset, not to the individual record; often null |
tags |
Keywords describing the record’s dataset (subject, record type, and jurisdiction), such as business_license, ucc_lien, federal, or tx |
data |
The original row as key-value pairs |
firstObservedDate, lastObservedDate |
When Enigma first and last observed the record, usually not the record’s own dates; use the dates in data, such as a filing date |
count(field: "records") returns the number of linked records without fetching them. To get the next page, pass the endCursor value as after, for example records(first: 10, after: "<endCursor>").
Filter linked records by tag or dataset title
Section titled “Filter linked records by tag or dataset title”Pass a filter in conditions on records or count:
- By tag:
{CONTAINS: ["tags", ["business_license"]]}matches records whose dataset carries every listed tag. To match any of several tags, combine clauses withOR:{OR: [{CONTAINS: ["tags", ["business_license"]]}, {CONTAINS: ["tags", ["ucc_lien"]]}]}. - By dataset title:
{IN: ["sourceTitle", ["Business Licenses", "UCC Liens"]]}matches those exact titles. Titles are not unique across sources, so useILIKEfor a pattern, or a tag for a subject.EQalso works onsourceTitle. - Large entities: on an entity with many linked records, a filtered count or page can take longer than the request allows. Count without a filter, or search the archive by name with
UNGROUNDED, which filters by tag.
query { search(searchInput: {name: "Starbucks Corporation", entityType: LEGAL_ENTITY, conditions: {limit: 1}}) { ... on LegalEntity { licenseTotal: count(field: "records", conditions: {filter: {CONTAINS: ["tags", ["business_license"]]}}) records(first: 5, conditions: {filter: {CONTAINS: ["tags", ["business_license"]]}}) { edges { node { sourceTitle tags data } } } } }}Summarize records by dataset and tag
Section titled “Summarize records by dataset and tag”Registered entities (a business as recorded across its state registrations) and addresses also have summary fields:
recordCount: the number of linked records, returned as a stringrecordSourceCounts: the number of records per dataset titlerecordTagCounts: the number of records per tag
query { search(searchInput: {name: "Starbucks Corporation", entityType: LEGAL_ENTITY, conditions: {limit: 1}}) { ... on LegalEntity { registeredEntities(first: 5) { edges { node { recordCount recordSourceCounts recordTagCounts } } } } }}Search records by name with UNGROUNDED
Section titled “Search records by name with UNGROUNDED”Set dataLayer: UNGROUNDED in searchInput. The search returns the matching businesses as usual, plus Record results. Select the records with an inline fragment on Record; __typename tells businesses and records apart:
query { search(searchInput: { name: "Chipotle Mexican Grill", entityType: LEGAL_ENTITY, dataLayer: UNGROUNDED, address: {state: "TX"}, conditions: {limit: 20, filter: {CONTAINS: ["tags", ["liquor_license"]]}} }) { __typename ... on LegalEntity { id } ... on Record { sourceTitle tags data } }}- Address:
street1,city,postalCode, andstateinaddressnarrow theRecordresults. - Brands: with
entityType: BRAND, theRecordresults match the name against brand names, such as DBAs, instead of registered business names, which any otherentityType, or none, matches. ARECORDsearch matches both. - Filtering:
conditions.filternarrows theRecordresults only. It acceptstagswithEQ,IN, orCONTAINS, combined withAND; useINto match any of several tags. Any other filter, includingORorsourceTitle, returns the businesses and an error, with no records. - Limits: by default a search returns up to 10 businesses and 50 records.
conditions.limitsets both caps, and records stop at 1,000. A search can return fewer records than exist, and itsRecordresults have no total or paging, so treat them as a sample. For a complete list with totals, use aRECORDsearch. - Counts per entity: on the legal entities, people, or addresses any search returns,
count(field: "records", dataLayer: UNGROUNDED)counts the records whose stated name or address is exactly one of that entity’s names, or its address, ignoring case, spacing, and punctuation. Select it on the search’s own results; on an entity nested under them it is an error. It takes noconditions. It is null when an entity has more than 20 names, a name too short to look up, or the count takes longer than 5 seconds. - Duplicates: the search leaves out any record that the same response returns in a business’s
records, so theRecordresults change with your selection. - Timeouts: if the record lookup takes longer than 20 seconds, the response keeps the businesses and adds an error, with no records. Retrying can succeed.
- Scope:
aggregatequeries do not supportdataLayer: UNGROUNDED, and searches that setoutputreturn noRecordresults.
List every record a search finds
Section titled “List every record a search finds”Set entityType: RECORD to list every record a search finds, page by page, with totals. The search returns one Record that stands for the whole search: its records field pages through the records, count(field: "records") returns the totals, and its id identifies the search. Its other fields are null.
query ($after: String) { search(searchInput: {name: "Sunrise Dental", entityType: RECORD, dataLayer: UNGROUNDED}) { ... on Record { total: count(field: "records") linkedTotal: count(field: "records", dataLayer: GROUNDED) matchedTotal: count(field: "records", dataLayer: UNGROUNDED) records(first: 100, after: $after) { pageInfo { hasNextPage endCursor } edges { node { sourceTitle tags data } } } } }}- Which records: search by a
name, aperson, or anaddresswithstreet1. By default, the search lists the records linked to the businesses, people, or addresses it matches: up to 250 legal entities for aname, up to 100 people forperson, or up to 100 addresses for anaddressalone. WithdataLayer: UNGROUNDED, the records whose stated name or address matches follow, each record listed once; there anamematches registered business names and brand names, such as DBAs. Addaddressfields to narrow the search; astatewith no otheraddressfield narrows legal entities and matched records, not people. - Totals:
count(field: "records")counts every record the search lists. WithdataLayer: GROUNDEDit counts the linked records, and withdataLayer: UNGROUNDEDthe records matched by stated name or address, linked or not. Once counted, a total is the same on every page. A total that takes longer than 5 seconds is null with an error on that page and every later one; start again without a cursor to count it again. Large searches often have noUNGROUNDEDtotal, so the default total of anUNGROUNDEDsearch is null too, and paging works without either. - Paging:
firstandafterpage forward;lastandbeforepage backward, andlastalone starts from the end. Mixing the two directions is an error. A page holds 100 records by default and at most 1,000. PassendCursorasafteruntilhasNextPageis false. A page stops reading 20 seconds after the request starts, so it can hold fewer records than you asked for, even none, whilehasNextPageis true: keep paging. If its first read does not finish in time, the page returns an error instead; retry the same page in a request of its own, or with a smallerfirstorlast. An edge’scursorresumes right after its record. - Cursors: a cursor works only with the search that returned it. If you change
searchInput(other thanconditions.limit), or Enigma’s data is refreshed, the cursor is rejected; start again without one. - Errors:
prompt,id,tin,output, more than onefieldsgroup,conditions.filter,conditions.orderBy, andconditions.pageTokenreturn an error.conditions.limithas no effect.
Available record types
Section titled “Available record types”| Category | Examples |
|---|---|
| Business registrations | Secretary of State filings, DBA registrations |
| Permits and licenses | Liquor, cannabis, professional licenses, business permits |
| Health and safety | Food safety inspections, health code violations, building code violations |
| Court filings and liens | UCC liens, bankruptcy filings, active litigation |
| Environmental compliance | EPA records, Clean Air Tracking System, brownfield/site remediation |
| Workplace safety | OSHA violations, citations, worker fatality records |
| Government contracts | USA Spending data, vendor payment records |
| Financial incentives | State economic incentive programs, tax credits |
Rate limits
Section titled “Rate limits”Gov Archive queries are GraphQL queries, including the ones the Python SDK sends, so they follow the GraphQL API rate limits.
Next steps
Section titled “Next steps”- Verify a business with the KYB API to combine Gov Archive with identity verification
- See every field on a GraphQL record