> ## 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.
Tool ID: `govfiles_search_companies_v2`
## Run this action
Use the TypeScript SDK for a single call. Put `ctx.tools.execute(...)` inside a Play when the call should be durable, scheduled, or run across a CSV.
```ts theme={null}
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={null}
deepline tools execute govfiles_search_companies_v2 --input '{
"q": "software companies hiring engineers"
}' --json
```
## Example response
The SDK exposes this shape at `result.toolResponse.raw`. Values below are representative.
```json theme={null}
{
"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 tools get 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. |
Show raw input schema
### Input JSON Schema
```json theme={null}
{
"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
}
```
## 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.
This output schema is too large to embed without slowing the page. Get the complete live contract with `deepline tools get 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](/docs/providers/govfiles/guide)
* [SDK V2 quickstart](/docs/sdk-v2/quickstart)
* [SDK reference](/docs/sdk-v2/sdk-reference)
* [Run tools across a CSV](/docs/sdk-v2/batch-csv)