Skip to main content
POST
/
v2
/
officers
/
search
Search officers
curl --request POST \
  --url https://api.govfiles.dev/v2/officers/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "q": "john smith",
  "role": "officer",
  "jurisdictions": "all",
  "limit": 100,
  "page": 1
}
'
{
  "page": 123,
  "request": {
    "query": "<string>",
    "jurisdictions": "<string>"
  },
  "summary": {
    "total_matches": 123,
    "total_is_capped": true,
    "returned": 10,
    "next_page": 123,
    "jurisdictions_searched": [
      "<string>"
    ]
  },
  "results": [
    {
      "match": {
        "matched_field": "officer_name"
      },
      "officer": {
        "name": "<string>",
        "roles": [
          {
            "title": "<string>",
            "ownership_percentage": 123,
            "started_on": "2023-12-25",
            "ended_on": "2023-12-25"
          }
        ],
        "address": {
          "raw": "<string>",
          "street_address": "<string>",
          "locality": "<string>",
          "region": "<string>",
          "postal_code": "<string>",
          "country": "<string>",
          "country_code": "<string>"
        }
      },
      "company": {
        "jurisdiction_code": "<string>",
        "entity_number": "<string>",
        "legal_name": "<string>",
        "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>",
            "locality": "<string>",
            "region": "<string>",
            "postal_code": "<string>",
            "country": "<string>",
            "country_code": "<string>"
          },
          "headquarters": {
            "raw": "<string>",
            "street_address": "<string>",
            "locality": "<string>",
            "region": "<string>",
            "postal_code": "<string>",
            "country": "<string>",
            "country_code": "<string>"
          },
          "mailing": {
            "raw": "<string>",
            "street_address": "<string>",
            "locality": "<string>",
            "region": "<string>",
            "postal_code": "<string>",
            "country": "<string>",
            "country_code": "<string>"
          }
        },
        "names": [
          {
            "name": "<string>",
            "started_on": "2023-12-25",
            "ended_on": "2023-12-25"
          }
        ],
        "parties": [
          {
            "name": "<string>",
            "roles": [
              {
                "title": "<string>",
                "ownership_percentage": 123,
                "started_on": "2023-12-25",
                "ended_on": "2023-12-25"
              }
            ],
            "address": {
              "raw": "<string>",
              "street_address": "<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": [
          {
            "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>"
      }
    }
  ]
}
Run a query across officer, director, member, agent, and shareholder names and return the companies they belong to. Each hit includes the matched officer and the full company entity it belongs to. Each request is billed at a flat rate. Fetching the next page counts as a separate request.

​
Results

Each result is a single matched officer, not a deduplicated company. A company that has two officers matching your query appears twice — once per matching officer — each with its own officer. summary.total_matches counts matching officers. officer is the matched Party: the name, every role the person holds at that company (normalized kind plus the registry’s verbatim title), and their address when published. company is the full company entity, and match.matched_field is always officer_name.

​
Query syntax

The q field uses the same Google-style query language as company search, run against the officer’s name.

​
Terms

  • Word — smith matches the word smith anywhere in an officer name.
  • Quoted phrase — "john smith" matches the two words adjacent and in order.
  • Prefix wildcard — smith* matches any word starting with smith. The * must be the last character of the word.

​
Operators

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

​
Filtering by role

Set role to a RoleKind value to keep only officers holding that role. For example role: "registered_agent" returns only registered agents, and role: "officer" excludes agents, members, and shareholders. The filter is exact on the normalized role kind — to filter on the registry’s verbatim wording, match on the returned officer.roles[].title instead. The filter is applied on top of the q name match.

​
Coverage

Officer data is only available in the jurisdictions that publish it; a company with no officers on record never appears in officer search even if it is returned by company search. Scope a search with jurisdictions exactly as in company search (all or comma-separated codes such as us_fl,us_ny).

​
Pagination

Page sizes are capped at 100. Walk pages by following summary.next_page until it returns null.

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
q
string
required

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

Example:

"john smith"

​
role
enum<string> | null

Optional exact filter on the officer's normalized role kind (e.g. 'officer', 'registered_agent'). Officers whose role kind differs are excluded.

Available options:
registered_agent,
officer,
manager,
member,
governor,
owner,
incorporator,
shareholder,
other,
unknown
Example:

"officer"

​
jurisdictions
string
default:all

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

​
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 officers, ordered by jurisdiction code then company number. Each entry is one matched officer, so a company appears once per matching officer.