> ## 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 Officers V2

> Search officers, directors, members, registered agents, and shareholders by name and optionally role or jurisdiction. GovFiles Search Officers V2 reference.

Search officers, directors, members, registered agents, and shareholders by name and optionally role or jurisdiction.

> [!NOTE]
>
> Tool ID: `govfiles_search_officers_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_officers_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_officers_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",
      "role": "registered_agent",
      "jurisdictions": "example"
    },
    "summary": {
      "total_matches": 123,
      "total_is_capped": true,
      "returned": 123,
      "next_page": 1,
      "jurisdictions_searched": [
        "software companies hiring engineers"
      ]
    },
    "results": [
      {
        "match": {
          "matched_field": "officer_name"
        },
        "officer": {
          "type": "company",
          "name": "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_officers_v2 --json` for the latest machine-readable contract.

## Input reference

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

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `payload.q` | `string` | Yes | — | Search query over officer names. Supports Google-style syntax: AND/OR, parentheses, quoted phrases, and prefix wildcards. |
| `payload.role` | `"registered_agent" \| "officer" \| "manager" \| "member" \| "governor" \| "owner" \| "incorporator" \| "shareholder" \| "other" \| "unknown"` | No | — | Optional exact filter on the officer's normalized role kind (e.g. 'officer', 'registered\_agent'). Officers whose role kind differs are excluded. Allowed: `registered_agent`, `officer`, `manager`, `member`, `governor`, `owner`, `incorporator`, `shareholder`, `other`, `unknown`. |
| `payload.jurisdictions` | `string` | No | `"all"` | Either 'all' or a comma-separated list of jurisdiction codes (e.g. 'us\_de,us\_ca'). |
| `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 company officers, directors, members, agents, and shareholders by name across US corporate records.",
    "properties": {
      "q": {
        "type": "string",
        "description": "Search query over officer names. Supports Google-style syntax: AND/OR, parentheses, quoted phrases, and prefix wildcards."
      },
      "role": {
        "type": [
          "string",
          "null"
        ],
        "description": "Optional exact filter on the officer's normalized role kind (e.g. 'officer', 'registered_agent'). Officers whose role kind differs are excluded.",
        "enum": [
          "registered_agent",
          "officer",
          "manager",
          "member",
          "governor",
          "owner",
          "incorporator",
          "shareholder",
          "other",
          "unknown"
        ]
      },
      "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",
        "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.role` | `"registered_agent" \| "officer" \| "manager" \| "member" \| "governor" \| "owner" \| "incorporator" \| "shareholder" \| "other" \| "unknown"` | Yes | — | Echo of the requested role filter, or null. Allowed: `registered_agent`, `officer`, `manager`, `member`, `governor`, `owner`, `incorporator`, `shareholder`, `other`, `unknown`. |
| `result.data.request.jurisdictions` | `string` | Yes | — | Echo of the request `jurisdictions` string ('all' or comma-separated codes). |
| `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 officers, ordered by jurisdiction code then company number. Each entry is one matched officer, so a company appears once per matching officer. |
| `result.data.results[].match` | `object` | Yes | — | — |
| `result.data.results[].match.matched_field` | `"officer_name"` | Yes | — | Always `officer_name`: officer search matches against the officer's name. |
| `result.data.results[].officer` | `object` | Yes | — | — |
| `result.data.results[].officer.type` | `"company" \| "person" \| "unknown"` | Yes | — | Allowed: `company`, `person`, `unknown`. |
| `result.data.results[].officer.name` | `string` | Yes | — | Minimum length: 1. |
| `result.data.results[].officer.roles` | `array` | No | — | — |
| `result.data.results[].officer.roles[].kind` | `"registered_agent" \| "officer" \| "manager" \| "member" \| "governor" \| "owner" \| "incorporator" \| "shareholder" \| "other" \| "unknown"` | Yes | — | Allowed: `registered_agent`, `officer`, `manager`, `member`, `governor`, `owner`, `incorporator`, `shareholder`, `other`, `unknown`. |
| `result.data.results[].officer.roles[].title` | `string \| null` | No | — | — |
| `result.data.results[].officer.roles[].ownership_percentage` | `number \| null` | No | — | — |
| `result.data.results[].officer.roles[].started_on` | `string \| null` | No | — | Format: `date`. |
| `result.data.results[].officer.roles[].ended_on` | `string \| null` | No | — | Format: `date`. |
| `result.data.results[].officer.address` | `object \| null` | No | — | — |
| `result.data.results[].officer.address.raw` | `string \| null` | No | — | — |
| `result.data.results[].officer.address.street_address` | `string \| null` | No | — | — |
| `result.data.results[].officer.address.street_address_2` | `string \| null` | No | — | — |
| `result.data.results[].officer.address.locality` | `string \| null` | No | — | — |
| `result.data.results[].officer.address.region` | `string \| null` | No | — | — |
| `result.data.results[].officer.address.postal_code` | `string \| null` | No | — | — |
| `result.data.results[].officer.address.country` | `string \| null` | No | — | — |
| `result.data.results[].officer.address.country_code` | `string \| null` | No | — | — |
| `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 | — | — |

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_officers_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.