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

# GovFiles: Search Companies V2

> Search 75M+ US company records with Google-style name queries, jurisdiction/status filters, relevance ordering, filings, parties, addresses, and identifiers.

Search 75M+ US company records with Google-style name queries, jurisdiction/status filters, relevance ordering, filings, parties, addresses, and identifiers.

> [!NOTE]
>
> Tool ID: `govfiles_search_companies_v2`

## Run this action

Use the TypeScript SDK for one call. Use `ctx.tools.execute(...)` inside a Play for durable calls, scheduled calls, or CSV processing.

```ts theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
import { Deepline } from 'deepline';

const deepline = await Deepline.connect();
const result = await deepline.tools.execute(
  'govfiles_search_companies_v2',
  {
    "q": "software companies hiring engineers"
  },
);

console.log(result.toolResponse.raw);
```

### CLI

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline tools execute govfiles_search_companies_v2 --input '{
  "q": "software companies hiring engineers"
}' --json
```

## Example response

The SDK returns this shape at `result.toolResponse.raw`. The example values illustrate the response.

```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
{
  "data": {
    "page": 123,
    "request": {
      "query": "software companies hiring engineers",
      "match_alternative_names": true,
      "match_previous_names": true,
      "jurisdictions": "example",
      "status": "active",
      "order_by": "jurisdiction"
    },
    "summary": {
      "total_matches": 123,
      "total_is_capped": true,
      "returned": 123,
      "next_page": 1,
      "jurisdictions_searched": [
        "software companies hiring engineers"
      ]
    },
    "results": [
      {
        "match": {
          "matched_field": "name",
          "matched_value": "example"
        },
        "company": {
          "jurisdiction_code": "examp",
          "entity_number": "example",
          "legal_name": "Example",
          "status": "active",
          "legal_form": "llc",
          "domicile": "domestic",
          "search_url": "https://example.com",
          "as_of": "2026-01-15"
        }
      }
    ]
  }
}
```

Use `deepline describe govfiles_search_companies_v2 --json` for the latest machine-readable contract.

## Input reference

Search US companies across 75 million+ company records.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `payload.q` | `string` | Yes | — | Search query. Supports Google-style syntax: AND/OR, parentheses, quoted phrases, and prefix wildcards. |
| `payload.match_alternative_names` | `boolean` | No | `true` | Also match against DBAs, trade names, and other alternative names. |
| `payload.match_previous_names` | `boolean` | No | `true` | Also match against historical legal names. |
| `payload.jurisdictions` | `string` | No | `"all"` | Either 'all' or a comma-separated list of jurisdiction codes (e.g. 'us\_de,us\_ca'). |
| `payload.status` | `"active" \| "inactive" \| "unknown" \| "any"` | No | `"any"` | Filter by registry status. 'active' and 'inactive' also include records with no published status. 'unknown' matches only those records. 'any' disables the filter. Allowed: `active`, `inactive`, `unknown`, `any`. |
| `payload.order_by` | `"jurisdiction" \| "relevance"` | No | `"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. Allowed: `jurisdiction`, `relevance`. |
| `payload.limit` | `integer` | No | `100` | Results per page, 1 to 100. Minimum: 1. Maximum: 100. |
| `payload.page` | `integer` | No | `1` | 1-based page number. Minimum: 1. |

<details>
  <summary>Show raw input schema</summary>

  ### Input JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Search US companies across 75 million+ company records.",
    "properties": {
      "q": {
        "type": "string",
        "description": "Search query. Supports Google-style syntax: AND/OR, parentheses, quoted phrases, and prefix wildcards."
      },
      "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",
        "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",
        "enum": [
          "active",
          "inactive",
          "unknown",
          "any"
        ]
      },
      "order_by": {
        "type": "string",
        "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",
        "enum": [
          "jurisdiction",
          "relevance"
        ]
      },
      "limit": {
        "type": "integer",
        "description": "Results per page, 1 to 100.",
        "default": 100,
        "minimum": 1,
        "maximum": 100
      },
      "page": {
        "type": "integer",
        "description": "1-based page number.",
        "default": 1,
        "minimum": 1
      }
    },
    "required": [
      "q"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Output reference

Standard tool result payload.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `result.data` | `object` | Yes | — | Provider response payload. |
| `result.data.page` | `integer` | Yes | — | 1-based page number of this response. |
| `result.data.request` | `object` | Yes | — | — |
| `result.data.request.query` | `string` | Yes | — | The `q` string as submitted in the request. |
| `result.data.request.match_alternative_names` | `boolean` | Yes | — | Echo of the request flag. |
| `result.data.request.match_previous_names` | `boolean` | Yes | — | Echo of the request flag. |
| `result.data.request.jurisdictions` | `string` | Yes | — | Echo of the request `jurisdictions` string ('all' or comma-separated codes). |
| `result.data.request.status` | `"active" \| "inactive" \| "unknown" \| "any"` | Yes | — | Echo of the requested status filter. Allowed: `active`, `inactive`, `unknown`, `any`. |
| `result.data.request.order_by` | `"jurisdiction" \| "relevance"` | Yes | — | Echo of the requested result ordering. Allowed: `jurisdiction`, `relevance`. |
| `result.data.summary` | `object` | Yes | — | — |
| `result.data.summary.total_matches` | `integer` | Yes | — | 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. |
| `result.data.summary.total_is_capped` | `boolean` | Yes | — | 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. |
| `result.data.summary.returned` | `integer` | Yes | — | Number of results in this response. |
| `result.data.summary.next_page` | `integer \| null` | Yes | — | 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. |
| `result.data.summary.jurisdictions_searched` | `array` | Yes | — | Resolved list of jurisdiction codes actually searched. Expanded when the request used `'all'`. normalized otherwise. |
| `result.data.results` | `array` | Yes | — | Matching companies, ordered according to the request's `order_by`. Empty when nothing matched. |
| `result.data.results[].match` | `object` | Yes | — | — |
| `result.data.results[].match.matched_field` | `"name" \| "alternative_names" \| "previous_names"` | Yes | — | 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`. Allowed: `name`, `alternative_names`, `previous_names`. |
| `result.data.results[].match.matched_value` | `string` | Yes | — | The actual value pulled from the matched field. |
| `result.data.results[].company` | `object` | Yes | — | — |
| `result.data.results[].company.kind` | `"company"` | No | `"company"` | — |
| `result.data.results[].company.jurisdiction_code` | `string` | Yes | — | Minimum length: 2. Maximum length: 5. |
| `result.data.results[].company.entity_number` | `string` | Yes | — | Minimum length: 1. |
| `result.data.results[].company.legal_name` | `string` | Yes | — | Minimum length: 1. |
| `result.data.results[].company.status` | `"active" \| "inactive" \| "dissolved" \| "suspended" \| "merged" \| "withdrawn" \| "unknown"` | Yes | — | Allowed: `active`, `inactive`, `dissolved`, `suspended`, `merged`, `withdrawn`, `unknown`. |
| `result.data.results[].company.status_raw` | `string \| null` | No | — | — |
| `result.data.results[].company.legal_form` | `"llc" \| "corporation" \| "nonprofit" \| "limited_partnership" \| "limited_liability_partnership" \| "partnership" \| "trust" \| "other" \| "unknown"` | Yes | — | Allowed: `llc`, `corporation`, `nonprofit`, `limited_partnership`, `limited_liability_partnership`, `partnership`, `trust`, `other`, `unknown`. |
| `result.data.results[].company.legal_form_raw` | `string \| null` | No | — | — |
| `result.data.results[].company.domicile` | `"domestic" \| "foreign" \| "unknown"` | Yes | — | Allowed: `domestic`, `foreign`, `unknown`. |
| `result.data.results[].company.formed_on` | `string \| null` | No | — | Format: `date`. |
| `result.data.results[].company.dissolved_on` | `string \| null` | No | — | Format: `date`. |
| `result.data.results[].company.addresses` | `object \| null` | No | — | — |
| `result.data.results[].company.addresses.registered` | `object \| null` | No | — | — |
| `result.data.results[].company.addresses.registered.raw` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.registered.street_address` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.registered.street_address_2` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.registered.locality` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.registered.region` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.registered.postal_code` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.registered.country` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.registered.country_code` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.headquarters` | `object \| null` | No | — | — |
| `result.data.results[].company.addresses.headquarters.raw` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.headquarters.street_address` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.headquarters.street_address_2` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.headquarters.locality` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.headquarters.region` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.headquarters.postal_code` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.headquarters.country` | `string \| null` | No | — | — |
| `result.data.results[].company.addresses.headquarters.country_code` | `string \| null` | No | — | — |

The table shows the first 50 fields. Expand the raw schema below for every field.

> [!NOTE]
>
> This output schema is too large for an inline display. Read the complete live contract with `deepline describe govfiles_search_companies_v2 --json`.

## Deepline cost

* Pricing model: `per_result` (per result).
* Estimated Deepline credits: `0.14` per pricing unit.

## Related documentation

* [GovFiles provider guide](https://deepline.com/docs/providers/govfiles/guide.md)
* [SDK V2 quickstart](https://deepline.com/docs/sdk-v2/quickstart.md)
* [SDK reference](https://deepline.com/docs/sdk-v2/sdk-reference.md)
* [Run tools across a CSV](https://deepline.com/docs/sdk-v2/batch-csv.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.