> ## Documentation Index
> Fetch the complete documentation index at: https://docs.govfiles.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Search officers

> Search company officers, directors, members, agents, and shareholders by name across US corporate records.

Run a [query](#query-syntax) 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](/guides/company-schema) 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](/guides/company-schema#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](/api-reference/endpoints/searchcompanies#query-syntax), 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](/guides/company-schema#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](/api-reference/endpoints/searchcompanies). 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`.


## OpenAPI

````yaml POST /v2/officers/search
openapi: 3.1.0
info:
  title: govfiles Corporate Entity API
  version: 0.2.0
  description: >-
    Search US business entity records by name, registry number, jurisdiction, or
    status.
servers:
  - url: https://api.govfiles.dev
security: []
tags:
  - name: Health
    description: Service health checks.
  - name: Companies
    description: Corporate entity search and lookup endpoints.
  - name: Officers
    description: Officer, director, and agent search endpoints.
  - name: Account
    description: Account and billing endpoints.
paths:
  /v2/officers/search:
    post:
      tags:
        - Officers
      summary: Search officers
      description: >-
        Search company officers, directors, members, agents, and shareholders by
        name across US corporate records.
      operationId: searchOfficersV2
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfficerSearchRequestV2'
        required: true
      responses:
        '200':
          description: Successful search response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfficerSearchResponseV2'
        '400':
          description: >-
            Malformed query syntax or unknown jurisdiction. The detail field
            describes the specific rule violated.
        '401':
          description: Missing or invalid API key.
        '402':
          description: Insufficient credits.
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    OfficerSearchRequestV2:
      properties:
        q:
          type: string
          description: >-
            Search query over officer names. Supports Google-style syntax:
            AND/OR, parentheses, quoted phrases, and prefix wildcards.
          examples:
            - john smith
          example: john smith
        role:
          anyOf:
            - $ref: '#/components/schemas/PartyRoleKind'
            - type: 'null'
          description: >-
            Optional exact filter on the officer's normalized role kind (e.g.
            'officer', 'registered_agent'). Officers whose role kind differs are
            excluded.
          examples:
            - officer
          example: officer
        jurisdictions:
          type: string
          description: >-
            Either 'all' or a comma-separated list of jurisdiction codes (e.g.
            'us_de,us_ca').
          default: all
        limit:
          type: integer
          maximum: 100
          minimum: 1
          description: Results per page, 1 to 100.
          default: 100
        page:
          type: integer
          minimum: 1
          description: 1-based page number.
          default: 1
      type: object
      required:
        - q
    OfficerSearchResponseV2:
      properties:
        page:
          type: integer
          description: 1-based page number of this response.
        request:
          $ref: '#/components/schemas/OfficerSearchRequestEchoV2'
          description: Echo of the request as resolved by the server.
        summary:
          $ref: '#/components/schemas/SearchSummary'
          description: Aggregate match counts and pagination cursor.
        results:
          items:
            $ref: '#/components/schemas/OfficerSearchResultV2'
          type: array
          description: >-
            Matching officers, ordered by jurisdiction code then company number.
            Each entry is one matched officer, so a company appears once per
            matching officer.
      type: object
      required:
        - page
        - request
        - summary
        - results
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
      type: object
    PartyRoleKind:
      type: string
      enum:
        - registered_agent
        - officer
        - manager
        - member
        - governor
        - owner
        - incorporator
        - shareholder
        - other
        - unknown
    OfficerSearchRequestEchoV2:
      properties:
        query:
          type: string
          description: The `q` string as submitted in the request.
        role:
          anyOf:
            - $ref: '#/components/schemas/PartyRoleKind'
            - type: 'null'
          description: Echo of the requested role filter, or null.
        jurisdictions:
          type: string
          description: >-
            Echo of the request `jurisdictions` string ('all' or comma-separated
            codes).
      type: object
      required:
        - query
        - role
        - jurisdictions
    SearchSummary:
      properties:
        total_matches:
          type: integer
          description: >-
            Number of companies matching the query, counted up to a cap of
            10,000. When `total_is_capped` is true there are at least this many
            matches and possibly more; use `next_page` to page through all of
            them.
        total_is_capped:
          type: boolean
          description: >-
            True when `total_matches` hit the 10,000 cap and the real total is
            higher. Paginate with `next_page` to retrieve results beyond the
            cap.
        returned:
          type: integer
          description: Number of results in this response.
          examples:
            - 10
          example: 10
        next_page:
          description: >-
            1-based page number to fetch next, or `null` if this is the last
            page. Derived from whether a full page of results was returned, so
            it remains correct past the 10,000 count cap.
          type:
            - integer
            - 'null'
        jurisdictions_searched:
          items:
            type: string
          type: array
          description: >-
            Resolved list of jurisdiction codes actually searched. Expanded when
            the request used `'all'`; normalized otherwise.
      type: object
      required:
        - total_matches
        - total_is_capped
        - returned
        - next_page
        - jurisdictions_searched
    OfficerSearchResultV2:
      properties:
        match:
          $ref: '#/components/schemas/OfficerMatchInfoV2'
        officer:
          $ref: '#/components/schemas/PublicParty'
          description: >-
            The matched officer (officer, director, member, agent, or
            shareholder) from the company's parties list.
        company:
          $ref: '#/components/schemas/PublicCompanyEntity'
          description: >-
            The company entity the matched officer belongs to. See the company
            schema page for the field-by-field reference.
      type: object
      required:
        - match
        - officer
        - company
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
        msg:
          type: string
        type:
          type: string
        input: {}
        ctx:
          type: object
      type: object
      required:
        - loc
        - msg
        - type
    OfficerMatchInfoV2:
      properties:
        matched_field:
          type: string
          const: officer_name
          description: >-
            Always `officer_name`: officer search matches against the officer's
            name.
          examples:
            - officer_name
          example: officer_name
      type: object
      required:
        - matched_field
    PublicParty:
      properties:
        type:
          $ref: '#/components/schemas/EntityKind'
        name:
          type: string
          minLength: 1
        roles:
          items:
            $ref: '#/components/schemas/PublicRole'
          type: array
        address:
          anyOf:
            - $ref: '#/components/schemas/EntityAddress'
            - type: 'null'
      type: object
      required:
        - type
        - name
    PublicCompanyEntity:
      properties:
        kind:
          type: string
          const: company
          default: company
        jurisdiction_code:
          type: string
          maxLength: 5
          minLength: 2
        entity_number:
          type: string
          minLength: 1
        legal_name:
          type: string
          minLength: 1
        status:
          $ref: '#/components/schemas/EntityStatusKind'
        status_raw:
          type:
            - string
            - 'null'
        legal_form:
          $ref: '#/components/schemas/LegalForm'
        legal_form_raw:
          type:
            - string
            - 'null'
        domicile:
          $ref: '#/components/schemas/Domicile'
        formed_on:
          type:
            - string
            - 'null'
          format: date
        dissolved_on:
          type:
            - string
            - 'null'
          format: date
        addresses:
          anyOf:
            - $ref: '#/components/schemas/EntityAddresses'
            - type: 'null'
        names:
          items:
            $ref: '#/components/schemas/EntityName'
          type:
            - array
            - 'null'
        parties:
          items:
            $ref: '#/components/schemas/PublicParty'
          type:
            - array
            - 'null'
        filings:
          items:
            $ref: '#/components/schemas/EntityFiling'
          type:
            - array
            - 'null'
        relationships:
          items:
            $ref: '#/components/schemas/EntityRelationship'
          type:
            - array
            - 'null'
        contact:
          anyOf:
            - $ref: '#/components/schemas/Contact'
            - type: 'null'
        industry_codes:
          items:
            $ref: '#/components/schemas/IndustryCode'
          type:
            - array
            - 'null'
        identifiers:
          items:
            $ref: '#/components/schemas/Identifier'
          type:
            - array
            - 'null'
        entity_url:
          type:
            - string
            - 'null'
        search_url:
          type: string
        as_of:
          type: string
          format: date
      type: object
      required:
        - jurisdiction_code
        - entity_number
        - legal_name
        - status
        - legal_form
        - domicile
        - search_url
        - as_of
    EntityKind:
      type: string
      enum:
        - company
        - person
        - unknown
    PublicRole:
      properties:
        kind:
          $ref: '#/components/schemas/PartyRoleKind'
        title:
          type:
            - string
            - 'null'
        ownership_percentage:
          type:
            - number
            - 'null'
        started_on:
          type:
            - string
            - 'null'
          format: date
        ended_on:
          type:
            - string
            - 'null'
          format: date
      type: object
      required:
        - kind
    EntityAddress:
      properties:
        raw:
          type:
            - string
            - 'null'
        street_address:
          type:
            - string
            - 'null'
        locality:
          type:
            - string
            - 'null'
        region:
          type:
            - string
            - 'null'
        postal_code:
          type:
            - string
            - 'null'
        country:
          type:
            - string
            - 'null'
        country_code:
          type:
            - string
            - 'null'
      type: object
    EntityStatusKind:
      type: string
      enum:
        - active
        - inactive
        - dissolved
        - suspended
        - merged
        - withdrawn
        - unknown
    LegalForm:
      type: string
      enum:
        - llc
        - corporation
        - nonprofit
        - limited_partnership
        - limited_liability_partnership
        - partnership
        - trust
        - other
        - unknown
    Domicile:
      type: string
      enum:
        - domestic
        - foreign
        - unknown
    EntityAddresses:
      properties:
        registered:
          anyOf:
            - $ref: '#/components/schemas/EntityAddress'
            - type: 'null'
        headquarters:
          anyOf:
            - $ref: '#/components/schemas/EntityAddress'
            - type: 'null'
        mailing:
          anyOf:
            - $ref: '#/components/schemas/EntityAddress'
            - type: 'null'
      type: object
    EntityName:
      properties:
        name:
          type: string
          minLength: 1
        kind:
          $ref: '#/components/schemas/NameKind'
        started_on:
          type:
            - string
            - 'null'
          format: date
        ended_on:
          type:
            - string
            - 'null'
          format: date
      type: object
      required:
        - name
        - kind
    EntityFiling:
      properties:
        id:
          type:
            - string
            - 'null'
        title:
          type:
            - string
            - 'null'
        filed_on:
          type: string
          format: date
        type:
          anyOf:
            - $ref: '#/components/schemas/FilingType'
            - type: 'null'
        url:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
      type: object
      required:
        - filed_on
    EntityRelationship:
      properties:
        kind:
          $ref: '#/components/schemas/RelationshipKind'
        entity:
          $ref: '#/components/schemas/EntityRef'
        effective_date:
          type:
            - string
            - 'null'
          format: date
      type: object
      required:
        - kind
        - entity
    Contact:
      properties:
        websites:
          items:
            type: string
          type:
            - array
            - 'null'
        phone:
          type:
            - string
            - 'null'
        fax:
          type:
            - string
            - 'null'
      type: object
    IndustryCode:
      properties:
        code:
          type: string
          minLength: 1
        scheme:
          type: string
        description:
          type:
            - string
            - 'null'
      type: object
      required:
        - code
        - scheme
    Identifier:
      properties:
        scheme:
          type: string
        value:
          type: string
          minLength: 1
      type: object
      required:
        - scheme
        - value
    NameKind:
      type: string
      enum:
        - previous_legal
        - trading
        - alias
    FilingType:
      properties:
        code:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
      type: object
    RelationshipKind:
      type: string
      enum:
        - merged_into
        - home_entity
        - subsequent_registration
        - alternate_registration
    EntityRef:
      properties:
        name:
          type:
            - string
            - 'null'
        jurisdiction_code:
          type:
            - string
            - 'null'
        entity_number:
          type:
            - string
            - 'null'
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````