> ## 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 companies

> Search US companies across 75 million+ company records.

Run a [query](#query-syntax) across company names and status and return matching companies. Each hit includes the full [company entity](/guides/company-schema) 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`](/guides/company-schema#name) 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`:

```bash theme={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}'
```


## OpenAPI

````yaml POST /v2/companies/search
openapi: 3.1.0
info:
  title: govfiles Corporate Entity API
  version: 0.2.0
  description: >-
    Search US business entity records and resolve physical local businesses to
    their legal operators and published principals.
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: Local Businesses
    description: >-
      Asynchronous matching of physical businesses to their legal operators and
      published principals.
  - name: Account
    description: Account and billing endpoints.
paths:
  /v2/companies/search:
    post:
      tags:
        - Companies
      summary: Search companies
      description: Search US companies across 75 million+ company records.
      operationId: searchCompaniesV2
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanySearchRequestV2'
        required: true
      responses:
        '200':
          description: Successful search response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponseV2'
        '400':
          description: >-
            Malformed query syntax. 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:
    CompanySearchRequestV2:
      properties:
        q:
          type: string
          description: >-
            Search query. Supports Google-style syntax: AND/OR, parentheses,
            quoted phrases, and prefix wildcards.
          examples:
            - acme
          example: acme
        match_alternative_names:
          type: boolean
          description: Also match against DBAs, trade names, and other alternative names.
          default: true
        match_previous_names:
          type: boolean
          description: Also match against historical legal names.
          default: true
        jurisdictions:
          type: string
          description: >-
            Either 'all' or a comma-separated list of jurisdiction codes (e.g.
            'us_de,us_ca').
          default: all
        status:
          type: string
          enum:
            - active
            - inactive
            - unknown
            - any
          description: >-
            Filter by registry status. 'active' and 'inactive' also include
            records with no published status; 'unknown' matches only those
            records; 'any' disables the filter.
          default: any
        order_by:
          type: string
          enum:
            - jurisdiction
            - relevance
          description: >-
            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.
          default: jurisdiction
        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
    SearchResponseV2:
      properties:
        page:
          type: integer
          description: 1-based page number of this response.
        request:
          $ref: '#/components/schemas/SearchRequestEchoV2'
          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/SearchResultV2'
          type: array
          description: >-
            Matching companies, ordered according to the request's `order_by`.
            Empty when nothing matched.
      type: object
      required:
        - page
        - request
        - summary
        - results
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
      type: object
    SearchRequestEchoV2:
      properties:
        query:
          type: string
          description: The `q` string as submitted in the request.
        match_alternative_names:
          type: boolean
          description: Echo of the request flag.
        match_previous_names:
          type: boolean
          description: Echo of the request flag.
        jurisdictions:
          type: string
          description: >-
            Echo of the request `jurisdictions` string ('all' or comma-separated
            codes).
        status:
          type: string
          enum:
            - active
            - inactive
            - unknown
            - any
          description: Echo of the requested status filter.
          examples:
            - any
          example: any
        order_by:
          type: string
          enum:
            - jurisdiction
            - relevance
          description: Echo of the requested result ordering.
          examples:
            - jurisdiction
          example: jurisdiction
      type: object
      required:
        - query
        - match_alternative_names
        - match_previous_names
        - jurisdictions
        - status
        - order_by
    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
    SearchResultV2:
      properties:
        match:
          $ref: '#/components/schemas/MatchInfo'
        company:
          $ref: '#/components/schemas/PublicCompanyEntity'
          description: >-
            The full company entity. See the company schema page for the
            field-by-field reference.
      type: object
      required:
        - match
        - 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
    MatchInfo:
      properties:
        matched_field:
          type: string
          enum:
            - name
            - alternative_names
            - previous_names
          description: >-
            Which field on the Company record matched the query: `name`,
            `alternative_names`, or `previous_names`. When more than one field
            matches, `name` takes precedence, then `alternative_names`, then
            `previous_names`.
          examples:
            - name
          example: name
        matched_value:
          type: string
          description: The actual value pulled from the matched field.
      type: object
      required:
        - matched_field
        - matched_value
    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/PublicEntityAddresses'
            - 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
    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
    PublicEntityAddresses:
      properties:
        registered:
          anyOf:
            - $ref: '#/components/schemas/PublicEntityAddress'
            - type: 'null'
        headquarters:
          anyOf:
            - $ref: '#/components/schemas/PublicEntityAddress'
            - type: 'null'
        mailing:
          anyOf:
            - $ref: '#/components/schemas/PublicEntityAddress'
            - 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
    PublicParty:
      properties:
        type:
          $ref: '#/components/schemas/PublicPartyType'
        name:
          type: string
          minLength: 1
        roles:
          items:
            $ref: '#/components/schemas/PublicRole'
          type: array
        address:
          anyOf:
            - $ref: '#/components/schemas/PublicEntityAddress'
            - type: 'null'
      type: object
      required:
        - type
        - name
    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
    PublicEntityAddress:
      properties:
        raw:
          type:
            - string
            - 'null'
        street_address:
          type:
            - string
            - 'null'
        street_address_2:
          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
    NameKind:
      type: string
      enum:
        - previous_legal
        - trading
        - alias
    PublicPartyType:
      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
    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
    PartyRoleKind:
      type: string
      enum:
        - registered_agent
        - officer
        - manager
        - member
        - governor
        - owner
        - incorporator
        - shareholder
        - other
        - unknown
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````