Search companies

curl --request POST \
  --url https://api.govfiles.dev/v2/companies/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "q": "acme",
  "match_alternative_names": true,
  "match_previous_names": true,
  "jurisdictions": "all",
  "status": "any",
  "order_by": "jurisdiction",
  "limit": 100,
  "page": 1
}
'

import requests

url = "https://api.govfiles.dev/v2/companies/search"

payload = {
    "q": "acme",
    "match_alternative_names": True,
    "match_previous_names": True,
    "jurisdictions": "all",
    "status": "any",
    "order_by": "jurisdiction",
    "limit": 100,
    "page": 1
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    q: 'acme',
    match_alternative_names: true,
    match_previous_names: true,
    jurisdictions: 'all',
    status: 'any',
    order_by: 'jurisdiction',
    limit: 100,
    page: 1
  })
};

fetch('https://api.govfiles.dev/v2/companies/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.govfiles.dev/v2/companies/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'q' => 'acme',
    'match_alternative_names' => true,
    'match_previous_names' => true,
    'jurisdictions' => 'all',
    'status' => 'any',
    'order_by' => 'jurisdiction',
    'limit' => 100,
    'page' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.govfiles.dev/v2/companies/search"

	payload := strings.NewReader("{\n  \"q\": \"acme\",\n  \"match_alternative_names\": true,\n  \"match_previous_names\": true,\n  \"jurisdictions\": \"all\",\n  \"status\": \"any\",\n  \"order_by\": \"jurisdiction\",\n  \"limit\": 100,\n  \"page\": 1\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.govfiles.dev/v2/companies/search")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"q\": \"acme\",\n  \"match_alternative_names\": true,\n  \"match_previous_names\": true,\n  \"jurisdictions\": \"all\",\n  \"status\": \"any\",\n  \"order_by\": \"jurisdiction\",\n  \"limit\": 100,\n  \"page\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.govfiles.dev/v2/companies/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"q\": \"acme\",\n  \"match_alternative_names\": true,\n  \"match_previous_names\": true,\n  \"jurisdictions\": \"all\",\n  \"status\": \"any\",\n  \"order_by\": \"jurisdiction\",\n  \"limit\": 100,\n  \"page\": 1\n}"

response = http.request(request)
puts response.read_body

{
  "page": 123,
  "request": {
    "query": "<string>",
    "match_alternative_names": true,
    "match_previous_names": true,
    "jurisdictions": "<string>",
    "status": "any",
    "order_by": "jurisdiction"
  },
  "summary": {
    "total_matches": 123,
    "total_is_capped": true,
    "returned": 10,
    "next_page": 123,
    "jurisdictions_searched": [
      "<string>"
    ]
  },
  "results": [
    {
      "match": {
        "matched_field": "name",
        "matched_value": "<string>"
      },
      "company": {
        "jurisdiction_code": "<string>",
        "entity_number": "<string>",
        "legal_name": "<string>",
        "status": "active",
        "legal_form": "llc",
        "domicile": "domestic",
        "search_url": "<string>",
        "as_of": "2023-12-25",
        "kind": "company",
        "status_raw": "<string>",
        "legal_form_raw": "<string>",
        "formed_on": "2023-12-25",
        "dissolved_on": "2023-12-25",
        "addresses": {
          "registered": {
            "raw": "<string>",
            "street_address": "<string>",
            "street_address_2": "<string>",
            "locality": "<string>",
            "region": "<string>",
            "postal_code": "<string>",
            "country": "<string>",
            "country_code": "<string>"
          },
          "headquarters": {
            "raw": "<string>",
            "street_address": "<string>",
            "street_address_2": "<string>",
            "locality": "<string>",
            "region": "<string>",
            "postal_code": "<string>",
            "country": "<string>",
            "country_code": "<string>"
          },
          "mailing": {
            "raw": "<string>",
            "street_address": "<string>",
            "street_address_2": "<string>",
            "locality": "<string>",
            "region": "<string>",
            "postal_code": "<string>",
            "country": "<string>",
            "country_code": "<string>"
          }
        },
        "names": [
          {
            "name": "<string>",
            "kind": "previous_legal",
            "started_on": "2023-12-25",
            "ended_on": "2023-12-25"
          }
        ],
        "parties": [
          {
            "type": "company",
            "name": "<string>",
            "roles": [
              {
                "kind": "registered_agent",
                "title": "<string>",
                "ownership_percentage": 123,
                "started_on": "2023-12-25",
                "ended_on": "2023-12-25"
              }
            ],
            "address": {
              "raw": "<string>",
              "street_address": "<string>",
              "street_address_2": "<string>",
              "locality": "<string>",
              "region": "<string>",
              "postal_code": "<string>",
              "country": "<string>",
              "country_code": "<string>"
            }
          }
        ],
        "filings": [
          {
            "filed_on": "2023-12-25",
            "id": "<string>",
            "title": "<string>",
            "type": {
              "code": "<string>",
              "name": "<string>"
            },
            "url": "<string>",
            "description": "<string>"
          }
        ],
        "relationships": [
          {
            "kind": "merged_into",
            "entity": {
              "name": "<string>",
              "jurisdiction_code": "<string>",
              "entity_number": "<string>"
            },
            "effective_date": "2023-12-25"
          }
        ],
        "contact": {
          "websites": [
            "<string>"
          ],
          "phone": "<string>",
          "fax": "<string>"
        },
        "industry_codes": [
          {
            "code": "<string>",
            "scheme": "<string>",
            "description": "<string>"
          }
        ],
        "identifiers": [
          {
            "scheme": "<string>",
            "value": "<string>"
          }
        ],
        "entity_url": "<string>"
      }
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

POST

companies

Search companies

curl --request POST \
  --url https://api.govfiles.dev/v2/companies/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "q": "acme",
  "match_alternative_names": true,
  "match_previous_names": true,
  "jurisdictions": "all",
  "status": "any",
  "order_by": "jurisdiction",
  "limit": 100,
  "page": 1
}
'

import requests

url = "https://api.govfiles.dev/v2/companies/search"

payload = {
    "q": "acme",
    "match_alternative_names": True,
    "match_previous_names": True,
    "jurisdictions": "all",
    "status": "any",
    "order_by": "jurisdiction",
    "limit": 100,
    "page": 1
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    q: 'acme',
    match_alternative_names: true,
    match_previous_names: true,
    jurisdictions: 'all',
    status: 'any',
    order_by: 'jurisdiction',
    limit: 100,
    page: 1
  })
};

fetch('https://api.govfiles.dev/v2/companies/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.govfiles.dev/v2/companies/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'q' => 'acme',
    'match_alternative_names' => true,
    'match_previous_names' => true,
    'jurisdictions' => 'all',
    'status' => 'any',
    'order_by' => 'jurisdiction',
    'limit' => 100,
    'page' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.govfiles.dev/v2/companies/search"

	payload := strings.NewReader("{\n  \"q\": \"acme\",\n  \"match_alternative_names\": true,\n  \"match_previous_names\": true,\n  \"jurisdictions\": \"all\",\n  \"status\": \"any\",\n  \"order_by\": \"jurisdiction\",\n  \"limit\": 100,\n  \"page\": 1\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.govfiles.dev/v2/companies/search")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"q\": \"acme\",\n  \"match_alternative_names\": true,\n  \"match_previous_names\": true,\n  \"jurisdictions\": \"all\",\n  \"status\": \"any\",\n  \"order_by\": \"jurisdiction\",\n  \"limit\": 100,\n  \"page\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.govfiles.dev/v2/companies/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"q\": \"acme\",\n  \"match_alternative_names\": true,\n  \"match_previous_names\": true,\n  \"jurisdictions\": \"all\",\n  \"status\": \"any\",\n  \"order_by\": \"jurisdiction\",\n  \"limit\": 100,\n  \"page\": 1\n}"

response = http.request(request)
puts response.read_body

{
  "page": 123,
  "request": {
    "query": "<string>",
    "match_alternative_names": true,
    "match_previous_names": true,
    "jurisdictions": "<string>",
    "status": "any",
    "order_by": "jurisdiction"
  },
  "summary": {
    "total_matches": 123,
    "total_is_capped": true,
    "returned": 10,
    "next_page": 123,
    "jurisdictions_searched": [
      "<string>"
    ]
  },
  "results": [
    {
      "match": {
        "matched_field": "name",
        "matched_value": "<string>"
      },
      "company": {
        "jurisdiction_code": "<string>",
        "entity_number": "<string>",
        "legal_name": "<string>",
        "status": "active",
        "legal_form": "llc",
        "domicile": "domestic",
        "search_url": "<string>",
        "as_of": "2023-12-25",
        "kind": "company",
        "status_raw": "<string>",
        "legal_form_raw": "<string>",
        "formed_on": "2023-12-25",
        "dissolved_on": "2023-12-25",
        "addresses": {
          "registered": {
            "raw": "<string>",
            "street_address": "<string>",
            "street_address_2": "<string>",
            "locality": "<string>",
            "region": "<string>",
            "postal_code": "<string>",
            "country": "<string>",
            "country_code": "<string>"
          },
          "headquarters": {
            "raw": "<string>",
            "street_address": "<string>",
            "street_address_2": "<string>",
            "locality": "<string>",
            "region": "<string>",
            "postal_code": "<string>",
            "country": "<string>",
            "country_code": "<string>"
          },
          "mailing": {
            "raw": "<string>",
            "street_address": "<string>",
            "street_address_2": "<string>",
            "locality": "<string>",
            "region": "<string>",
            "postal_code": "<string>",
            "country": "<string>",
            "country_code": "<string>"
          }
        },
        "names": [
          {
            "name": "<string>",
            "kind": "previous_legal",
            "started_on": "2023-12-25",
            "ended_on": "2023-12-25"
          }
        ],
        "parties": [
          {
            "type": "company",
            "name": "<string>",
            "roles": [
              {
                "kind": "registered_agent",
                "title": "<string>",
                "ownership_percentage": 123,
                "started_on": "2023-12-25",
                "ended_on": "2023-12-25"
              }
            ],
            "address": {
              "raw": "<string>",
              "street_address": "<string>",
              "street_address_2": "<string>",
              "locality": "<string>",
              "region": "<string>",
              "postal_code": "<string>",
              "country": "<string>",
              "country_code": "<string>"
            }
          }
        ],
        "filings": [
          {
            "filed_on": "2023-12-25",
            "id": "<string>",
            "title": "<string>",
            "type": {
              "code": "<string>",
              "name": "<string>"
            },
            "url": "<string>",
            "description": "<string>"
          }
        ],
        "relationships": [
          {
            "kind": "merged_into",
            "entity": {
              "name": "<string>",
              "jurisdiction_code": "<string>",
              "entity_number": "<string>"
            },
            "effective_date": "2023-12-25"
          }
        ],
        "contact": {
          "websites": [
            "<string>"
          ],
          "phone": "<string>",
          "fax": "<string>"
        },
        "industry_codes": [
          {
            "code": "<string>",
            "scheme": "<string>",
            "description": "<string>"
          }
        ],
        "identifiers": [
          {
            "scheme": "<string>",
            "value": "<string>"
          }
        ],
        "entity_url": "<string>"
      }
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Run a query across company names and status and return matching companies. Each hit includes the full company entity 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 current legal name, plus alternative names (DBAs, trade names, aliases) and previous legal names — both matched by default and reported in the entity’s names list. Set match_alternative_names or match_previous_names to false to narrow the search to the legal name.

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

Query	Matches
`acme`	Any name with the word `acme` — e.g. `ACME CORP`, `ACME HOLDINGS LLC`, `ACME INDUSTRIES INC`
`acme holdings`	Both 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 ajax`	Either word — e.g. `ACME CORP`, `AJAX SHIPPING LLC`
`(acme OR ajax) AND holdings`	`holdings` 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/v2/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

string

required

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

Example:

"acme"

match_alternative_names

boolean

default:true

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

match_previous_names

boolean

default:true

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. 'active' and 'inactive' also include records with no published status; 'unknown' matches only those records; 'any' disables the filter.

Available options:

active,

inactive,

unknown,

any

order_by

enum<string>

default:jurisdiction

Result ordering. 'jurisdiction' orders by jurisdiction code then company number. 'relevance' orders by match quality: companies whose name is exactly the query rank first, then descending full-text rank with current-name matches weighted above alternative and previous names.

Available options:

jurisdiction,

relevance

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.

Show child attributes

summary

object

required

Aggregate match counts and pagination cursor.

Show child attributes

results

object[]

required

Matching companies, ordered according to the request's order_by. Empty when nothing matched.

Show child attributes

Get started

Company registrations

Local business ownership

Miscellaneous

Bulk data

Search companies

Query syntax

Terms

Operators

Examples

Limits

Authorizations

Body

Response

​Query syntax

​Terms

​Operators

​Examples

​Limits

​Pagination

Authorizations

Body

Response

Query syntax

Terms

Operators

Examples

Limits

Pagination