Skip to main content
POST
/
v1
/
companies
/
search
Search entity records
curl --request POST \
  --url https://api.govfiles.dev/v1/companies/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "q": "acme",
  "match_alternative_names": false,
  "match_previous_names": false,
  "jurisdictions": "all",
  "status": "any",
  "limit": 100,
  "page": 1
}
'
{
  "page": 123,
  "request": {
    "query": "<string>",
    "match_alternative_names": true,
    "match_previous_names": true,
    "jurisdictions": "<string>",
    "status": "any"
  },
  "summary": {
    "total_matches": 123,
    "returned": 10,
    "next_page": 123,
    "jurisdictions_searched": [
      "<string>"
    ]
  },
  "results": [
    {
      "match": {
        "matched_field": "name",
        "matched_value": "<string>"
      },
      "company": {}
    }
  ]
}
Run a query across company names and status and return matching companies. Each hit includes the full Company object plus a match block telling you which field drove the result. Each request is billed at a flat rate. Fetching the next page counts as a separate request.

​
Query syntax

The q field uses a Google-style query language. It runs against the legal name field, plus alternative_names and previous_names when those flags are enabled.

​
Terms

  • Word — acme matches the word acme in any searched field.
  • Quoted phrase — "acme holdings" matches the two words adjacent and in order. Wildcards inside quoted phrases are rejected.
  • Prefix wildcard — acme* matches any word starting with acme. The * must be the last character of the word; embedded or leading wildcards are rejected.

​
Operators

  • AND — acme AND holdings (also implicit: acme holdings is the same).
  • OR — acme OR ajax.
  • Parentheses — (acme OR ajax) AND holdings to override precedence. AND binds tighter than OR.
Operators are case-sensitive: lowercase and / or are treated as plain words.

​
Examples

QueryMatches
acmeAny name with the word acme — e.g. ACME CORP, ACME HOLDINGS LLC, ACME INDUSTRIES INC
acme holdingsBoth words present, in any order — e.g. ACME HOLDINGS LLC, ACME REALTY HOLDINGS INC
"acme holdings"The phrase as adjacent words — matches ACME HOLDINGS LLC but not ACME REALTY HOLDINGS INC
acme OR ajaxEither word — e.g. ACME CORP, AJAX SHIPPING LLC
(acme OR ajax) AND holdingsholdings plus one of acme / ajax — e.g. ACME HOLDINGS LLC, AJAX HOLDINGS GROUP
acm*Any word starting with acm — e.g. ACME CORP, ACMETECH LLC, ACMA INC
acme OR "ajax holdings"acme anywhere, or the phrase ajax holdings — e.g. ACME CORP, AJAX HOLDINGS LLC
holding*Any word starting with holding — e.g. HOLDING CORP, HOLDINGS LLC, HOLDINGCO INC

​
Limits

  • Syntax errors return 400 Bad Request with a positional message in the detail field.

​
Pagination

Page sizes are capped at 100. Walk pages by following summary.next_page until it returns null: 
curl -s -X POST 'https://api.govfiles.dev/v1/companies/search' \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $GOVFILES_API_KEY" \
  -d '{"q":"holdings","jurisdictions":"us_de","limit":100,"page":1}'

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
q
string
required

Search query. Supports Google-style syntax: AND/OR, parentheses, quoted phrases, and prefix wildcards.

Example:

"acme"

​
match_alternative_names
boolean
default:false

Also match against DBAs, trade names, and other alternative names.

​
match_previous_names
boolean
default:false

Also match against historical legal names.

​
jurisdictions
string
default:all

Either 'all' or a comma-separated list of jurisdiction codes (e.g. 'us_de,us_ca').

​
status
enum<string>
default:any

Filter by registry status. 'unknown' matches records with no published status; 'any' disables the filter.

Available options:
active,
inactive,
unknown,
any
​
limit
integer
default:100

Results per page, 1 to 100.

Required range: 1 <= x <= 100
​
page
integer
default:1

1-based page number.

Required range: x >= 1

Response

Successful search response.

​
page
integer
required

1-based page number of this response.

​
request
object
required

Echo of the request as resolved by the server.

​
summary
object
required

Aggregate match counts and pagination cursor.

​
results
object[]
required

Matching companies, ranked by relevance. Empty when nothing matched.