@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/companies.md

@@ -0,0 +1,2211 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.companies`: Companies
+
+50 operations (25 read, 9 write, 5 destructive, 11 billable).
+
+8 of these also have a hand-written method (`g8.companies`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [companies.d.ts](companies.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`assignCompanyOwner`](#op-assigncompanyowner) | `POST /api/v1/companies/assign-owner` | write | `companies:write` | Assign Company Owner |
+| [`attachCompanyContact`](#op-attachcompanycontact) | `POST /api/v1/companies/{company_id}/contacts/{contact_id}` | write | `companies:write` | Attach Company Contact |
+| [`bulkEnrichCompanies`](#op-bulkenrichcompanies) | `POST /api/v1/companies/enrich/bulk` | billable | `enrichment:run` | Bulk Enrich Companies |
+| [`bulkEnrichCompanyPeople`](#op-bulkenrichcompanypeople) | `POST /api/v1/companies/enrich/people/bulk` | billable | `enrichment:run` | Bulk Enrich Company People |
+| [`bulkEnrichCompanyStakeholders`](#op-bulkenrichcompanystakeholders) | `POST /api/v1/companies/enrich/stakeholders/bulk` | billable | `enrichment:run` | Bulk Enrich Company Stakeholders |
+| [`createCompany`](#op-createcompany) ★ | `POST /api/v1/companies` | write | `companies:write` | Create Company |
+| [`createCompanyColumn`](#op-createcompanycolumn) ★ | `POST /api/v1/companies/columns/create` | write | `companies:write` | Create Company Column |
+| [`createCompanyTask`](#op-createcompanytask) | `POST /api/v1/companies/{company_id}/tasks` | write | `companies:write` | Create Company Task |
+| [`deleteCompany`](#op-deletecompany) ★ | `DELETE /api/v1/companies/{company_id}` | destructive | `companies:delete` | Delete Company |
+| [`deleteCompanyColumn`](#op-deletecompanycolumn) | `DELETE /api/v1/companies/columns/{column_id}` | destructive | `companies:delete` | Delete Company Column |
+| [`deleteCompanyDocument`](#op-deletecompanydocument) | `DELETE /api/v1/companies/{company_id}/documents/{document_id}` | destructive | `companies:delete` | Delete Company Document |
+| [`enrichCompany`](#op-enrichcompany) | `POST /api/v1/companies/{company_id}/enrich` | billable | `enrichment:run` | Enrich Company |
+| [`generateCompanyDocument`](#op-generatecompanydocument) | `POST /api/v1/companies/{company_id}/documents/types/{doc_type}/generate` | billable | `enrichment:run` | Generate Company Document |
+| [`getCompaniesOpenJobs`](#op-getcompaniesopenjobs) | `POST /api/v1/companies/open-jobs` | read | `companies:read` | Get Companies Open Jobs |
+| [`getCompany`](#op-getcompany) ★ | `GET /api/v1/companies/{company_id}` | read | `companies:read` | Get Company |
+| [`getCompanyBillingPrefill`](#op-getcompanybillingprefill) | `GET /api/v1/companies/{company_id}/billing-prefill` | read | `companies:read` | Get Company Billing Prefill |
+| [`getCompanyContacts`](#op-getcompanycontacts) ★ | `GET /api/v1/companies/{company_id}/contacts` | read | `companies:read` | Get Company Contacts |
+| [`getCompanyDashboard`](#op-getcompanydashboard) | `GET /api/v1/companies/{company_id}/dashboard` | read | `companies:read` | Get Company Dashboard |
+| [`getCompanyDetail`](#op-getcompanydetail) | `GET /api/v1/companies/{company_id}/detail` | read | `companies:read` | Get Company Detail |
+| [`getCompanyEngagementSummary`](#op-getcompanyengagementsummary) | `GET /api/v1/companies/{company_id}/engagement-summary` | read | `companies:read` | Get Company Engagement Summary |
+| [`getCompanyFormFields`](#op-getcompanyformfields) | `GET /api/v1/companies/form-fields` | read | `companies:read` | Get Company Form Fields |
+| [`getCompanyIcpFit`](#op-getcompanyicpfit) | `GET /api/v1/companies/{company_id}/icp-fit` | read | `companies:read` | Get Company Icp Fit |
+| [`getCompanyIntelligenceData`](#op-getcompanyintelligencedata) | `GET /api/v1/companies/{company_id}/intelligence-data/{data_type}` | read | `companies:read` | Get Company Intelligence Data |
+| [`getCompanyIntelligenceStatus`](#op-getcompanyintelligencestatus) | `GET /api/v1/companies/{company_id}/intelligence-status` | read | `companies:read` | Get Company Intelligence Status |
+| [`getCompanyIntelligenceSteps`](#op-getcompanyintelligencesteps) | `GET /api/v1/companies/{company_id}/intelligence-steps` | read | `companies:read` | Get Company Intelligence Steps |
+| [`getCompanyNextBestStep`](#op-getcompanynextbeststep) | `GET /api/v1/companies/{company_id}/next-best-step` | billable | `enrichment:run` | Get Company Next Best Step |
+| [`getCompanyReviewStats`](#op-getcompanyreviewstats) | `GET /api/v1/companies/review-stats` | read | `companies:read` | Get Company Review Stats |
+| [`getCompanySignals`](#op-getcompanysignals) | `GET /api/v1/companies/{company_id}/signals` | read | `companies:read` | Get Company Signals |
+| [`getCompanySitesVisited`](#op-getcompanysitesvisited) | `GET /api/v1/companies/{company_id}/sites-visited` | read | `companies:read` | Get Company Sites Visited |
+| [`getCompanySynthesisReadiness`](#op-getcompanysynthesisreadiness) | `GET /api/v1/companies/{company_id}/synthesis-readiness` | read | `companies:read` | Get Company Synthesis Readiness |
+| [`getCompanyWorkflowStatus`](#op-getcompanyworkflowstatus) | `GET /api/v1/companies/{company_id}/workflow-status` | read | `companies:read` | Get Company Workflow Status |
+| [`importCompanies`](#op-importcompanies) | `POST /api/v1/companies/import` | billable | `enrichment:run` | Import Companies |
+| [`listCompanies`](#op-listcompanies) ★ | `GET /api/v1/companies` | read | `companies:read` | List Companies |
+| [`listCompaniesEnriched`](#op-listcompaniesenriched) | `GET /api/v1/companies/enriched` | read | `companies:read` | List Companies Enriched |
+| [`listCompanyColumns`](#op-listcompanycolumns) ★ | `GET /api/v1/companies/columns` | read | `companies:read` | List Company Columns |
+| [`listCompanyDocuments`](#op-listcompanydocuments) | `GET /api/v1/companies/{company_id}/documents` | read | `companies:read` | List Company Documents |
+| [`listCompanyPeople`](#op-listcompanypeople) | `GET /api/v1/companies/{company_id}/people` | read | `companies:read` | List Company People |
+| [`listCompanyTasks`](#op-listcompanytasks) | `GET /api/v1/companies/{company_id}/tasks` | read | `companies:read` | List Company Tasks |
+| [`listContactsAcrossCompanies`](#op-listcontactsacrosscompanies) | `GET /api/v1/companies/contacts` | read | `companies:read` | List Contacts Across Companies |
+| [`mergeCompany`](#op-mergecompany) | `POST /api/v1/companies/{company_id}/merge` | destructive | `companies:delete` | Merge Company |
+| [`mergeFilteredCompanies`](#op-mergefilteredcompanies) | `POST /api/v1/companies/merge-filtered` | write | `companies:write` | Merge Filtered Companies |
+| [`previewCompanyMerge`](#op-previewcompanymerge) | `GET /api/v1/companies/{company_id}/merge/preview` | read | `companies:read` | Preview Company Merge |
+| [`refreshCompanyBillingPrefill`](#op-refreshcompanybillingprefill) | `POST /api/v1/companies/{company_id}/billing-prefill/refresh` | write | `companies:write` | Refresh Company Billing Prefill |
+| [`regenerateCompanyDocument`](#op-regeneratecompanydocument) | `POST /api/v1/companies/{company_id}/documents/types/{doc_type}/regenerate` | billable | `enrichment:run` | Regenerate Company Document |
+| [`removeCompanyContact`](#op-removecompanycontact) | `DELETE /api/v1/companies/{company_id}/contacts/{contact_id}` | destructive | `companies:delete` | Remove Company Contact |
+| [`retryCompanyIntelligence`](#op-retrycompanyintelligence) | `POST /api/v1/companies/{company_id}/retry-intelligence` | billable | `enrichment:run` | Retry Company Intelligence |
+| [`retryCompanySynthesis`](#op-retrycompanysynthesis) | `POST /api/v1/companies/{company_id}/retry-synthesis` | billable | `enrichment:run` | Retry Company Synthesis |
+| [`saveSkillResultToCompany`](#op-saveskillresulttocompany) | `POST /api/v1/companies/{company_id}/documents/from-skill` | write | `companies:write` | Save Skill Result To Company |
+| [`startCompanyWorkflow`](#op-startcompanyworkflow) | `POST /api/v1/companies/{company_id}/workflows/{workflow_type}/start` | billable | `enrichment:run` | Start Company Workflow |
+| [`updateCompany`](#op-updatecompany) ★ | `PATCH /api/v1/companies/{company_id}` | write | `companies:write` | Update Company |
+
+---
+
+<a id="op-assigncompanyowner"></a>
+
+### `g8.api.companies.assignCompanyOwner(input)`
+
+**Assign Company Owner**
+
+- HTTP: `POST /api/v1/companies/assign-owner`
+- operationId: `assign_company_owner_companies_assign_owner_post` (also callable as `g8.api.call("assign_company_owner_companies_assign_owner_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `companies:write`
+
+Set the owner on EVERY company matching a selection.
+
+The selection is resolved server-side, so the number of companies affected
+is not bounded by anything in the request. A null `owner_id` UNASSIGNS
+them all.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `AssignOwnerMatchingRequest` | yes | Request body; fields below. |
+
+Body fields (`AssignOwnerMatchingRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.filterModel` | `Record<string, unknown>` | no | Per-column filters. |
+| `body.list_id` | `integer \| null` | no | Restrict the selection to this list. |
+| `body.owner_id` | `string \| null` | no | Owner to assign. Null clears the owner on every match. |
+| `body.segmentFilter` | `SegmentFilterGroup \| null` | no | Advanced AND/OR filter tree. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.assignCompanyOwner({ body: {} });
+```
+
+---
+
+<a id="op-attachcompanycontact"></a>
+
+### `g8.api.companies.attachCompanyContact(input)`
+
+**Attach Company Contact**
+
+- HTTP: `POST /api/v1/companies/{company_id}/contacts/{contact_id}`
+- operationId: `attach_company_contact_companies__company_id__contacts__contact_id__post` (also callable as `g8.api.call("attach_company_contact_companies__company_id__contacts__contact_id__post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `companies:write`
+
+Link a contact to this company. The contact is gated inside the app handler.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+| `path.contact_id` | `string` | yes | Contact to link to the company. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.attachCompanyContact({ path: { company_id: "id", contact_id: "id" } });
+```
+
+---
+
+<a id="op-bulkenrichcompanies"></a>
+
+### `g8.api.companies.bulkEnrichCompanies(input?)`
+
+**Bulk Enrich Companies**
+
+- HTTP: `POST /api/v1/companies/enrich/bulk`
+- operationId: `bulk_enrich_companies_companies_enrich_bulk_post` (also callable as `g8.api.call("bulk_enrich_companies_companies_enrich_bulk_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Enrich EVERY company in the org that still lacks firmographics. SPENDS CREDITS.
+
+One paid provider lookup per company. There is no selection: the scope is
+the whole org, so the spend is bounded by the org's data, not the request.
+
+**Input**: none.
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.companies.bulkEnrichCompanies();
+```
+
+---
+
+<a id="op-bulkenrichcompanypeople"></a>
+
+### `g8.api.companies.bulkEnrichCompanyPeople(input?)`
+
+**Bulk Enrich Company People**
+
+- HTTP: `POST /api/v1/companies/enrich/people/bulk`
+- operationId: `bulk_enrich_company_people_companies_enrich_people_bulk_post` (also callable as `g8.api.call("bulk_enrich_company_people_companies_enrich_people_bulk_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Enrich the people of every company in the org. SPENDS CREDITS. Org-wide.
+
+**Input**: none.
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.companies.bulkEnrichCompanyPeople();
+```
+
+---
+
+<a id="op-bulkenrichcompanystakeholders"></a>
+
+### `g8.api.companies.bulkEnrichCompanyStakeholders(input?)`
+
+**Bulk Enrich Company Stakeholders**
+
+- HTTP: `POST /api/v1/companies/enrich/stakeholders/bulk`
+- operationId: `bulk_enrich_company_stakeholders_companies_enrich_stakeholders_bulk_post` (also callable as `g8.api.call("bulk_enrich_company_stakeholders_companies_enrich_stakeholders_bulk_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Find and enrich the buying committee at every company. SPENDS CREDITS. Org-wide.
+
+**Input**: none.
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.companies.bulkEnrichCompanyStakeholders();
+```
+
+---
+
+<a id="op-createcompany"></a>
+
+### `g8.api.companies.createCompany(input)`
+
+**Create Company**
+
+- HTTP: `POST /api/v1/companies`
+- operationId: `create_company_companies_post` (also callable as `g8.api.call("create_company_companies_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `companies:write`
+- ★ Hand-written: [`g8.companies.create()`](../sdk-clients.md#g8-companies-create)
+
+Create a company.
+
+``domain`` is required; the company is deduped by domain (an existing
+company with the same domain is reused rather than duplicated). Returns the
+``company_id`` (mashup_companies.id) — pass it to
+``g8_update_contact``/``company_id`` to attach the company to a contact, or
+use it on a deal. Optionally add the company to a list via ``list_id``.
+
+Routes to the same production ``CreateCompanyHandler`` the in-app "add
+company" flow uses (dedups, generates COMPANY_ID, creates the ABM/CRM
+overlay so the company is immediately pickable on a Deal).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CompanyCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`CompanyCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.domain` | `string` | yes | Company domain, e.g. acme.com (required) |
+| `body.address` | `string \| null` | no |  |
+| `body.city` | `string \| null` | no |  |
+| `body.country` | `string \| null` | no |  |
+| `body.employee_count` | `string \| null` | no |  |
+| `body.industry` | `string \| null` | no |  |
+| `body.linkedin_url` | `string \| null` | no |  |
+| `body.list_id` | `integer \| null` | no | Optional list to add the company to after creation |
+| `body.name` | `string \| null` | no |  |
+| `body.phone` | `string \| null` | no |  |
+| `body.state` | `string \| null` | no |  |
+| `body.website` | `string \| null` | no |  |
+| `body.zip` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_CompanyCreateResponse_`: the envelope `{ data: CompanyCreateResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CompanyCreateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `status` | `string` | yes |  |
+| `company_id` | `integer \| null` | no |  |
+| `merged` | `boolean` | no | default `false` |
+
+**Example**
+
+```ts
+const result = await g8.api.companies.createCompany({ body: { domain: "acme.com" } });
+```
+
+---
+
+<a id="op-createcompanycolumn"></a>
+
+### `g8.api.companies.createCompanyColumn(input)`
+
+**Create Company Column**
+
+- HTTP: `POST /api/v1/companies/columns/create`
+- operationId: `create_company_column_companies_columns_create_post` (also callable as `g8.api.call("create_company_column_companies_columns_create_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `companies:write`
+- ★ Hand-written: [`g8.companies.createColumn()`](../sdk-clients.md#g8-companies-createcolumn)
+
+Create a custom company column. Global if list_id is null, list-scoped otherwise.
+
+Optionally pass an `enrichment` block to provision a companion waterfall
+pipeline in the same request — STRONGLY RECOMMENDED so the UI 'Enrich'
+button works out-of-the-box. Without it the column is created but isn't
+enrichable until a pipeline is provisioned via
+POST /enrichment/waterfall/configs.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CreateCompanyColumnRequest` | yes | Request body; fields below. |
+
+Body fields (`CreateCompanyColumnRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.created_by` | `string (email)` | yes | Email of the user creating the column (for audit). |
+| `body.title` | `string` | yes | Column title shown in the UI (e.g. 'Tier') |
+| `body.data_type` | `ColumnType` | no | Column data type. Currently only 'text' is supported. default `"text"` |
+| `body.enrichment` | `CreateFieldEnrichmentInput \| null` | no | STRONGLY RECOMMENDED. Optional waterfall enrichment block. When supplied, a companion `enrichment_configs` row is created alongside the column so the UI 'Enrich' button works immediately. Without it the column exists but isn't enrichable until a pipeline is configured via POST /enrichment/waterfall/configs. |
+| `body.list_id` | `integer \| null` | no | If set, the column is list-scoped (only visible on that list). Required when `enrichment` is supplied — waterfall pipelines are list-scoped. |
+
+**Returns** `ApiResponse_CreateCompanyColumnResponse_`: the envelope `{ data: CreateCompanyColumnResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CreateCompanyColumnResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `title` | `string` | yes |  |
+| `data_type` | `ColumnType` | no | default `"text"` |
+| `enrichment` | `CreateFieldEnrichmentResponse \| null` | no | Populated when the request included an `enrichment` block. Use `enrichment.column_id` for subsequent POST /enrichment/waterfall/enrich calls. |
+| `id` | `integer \| null` | no |  |
+| `is_global` | `boolean` | no | Computed: True when object_id is null/empty (global column). default `false` |
+| `name` | `string \| null` | no |  |
+| `object_id` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.companies.createCompanyColumn({ body: { created_by: "jane@acme.com", title: "Example" } });
+```
+
+---
+
+<a id="op-createcompanytask"></a>
+
+### `g8.api.companies.createCompanyTask(input)`
+
+**Create Company Task**
+
+- HTTP: `POST /api/v1/companies/{company_id}/tasks`
+- operationId: `create_company_task_companies__company_id__tasks_post` (also callable as `g8.api.call("create_company_task_companies__company_id__tasks_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `companies:write`
+
+Create a task attached to this company.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | Company id. |
+| `body` | `CompanyTaskCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`CompanyTaskCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.title` | `string` | yes | Task title. |
+| `body.assignee_id` | `string \| null` | no | Assignee user id. |
+| `body.assignee_name` | `string \| null` | no | Assignee display name. |
+| `body.description` | `string \| null` | no | Task body. |
+| `body.due_date` | `string \| null` | no | ISO-8601 due date. |
+| `body.priority` | `integer \| null` | no | Priority, higher is more urgent. |
+| `body.tags` | `Array<string> \| null` | no | Up to 20 labels. max items 20 |
+| `body.task_type` | `string \| null` | no | Task type, e.g. `call`. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.createCompanyTask({ path: { company_id: 123 }, body: { title: "Example" } });
+```
+
+---
+
+<a id="op-deletecompany"></a>
+
+### `g8.api.companies.deleteCompany(input)`
+
+**Delete Company**
+
+- HTTP: `DELETE /api/v1/companies/{company_id}`
+- operationId: `delete_company_companies__company_id__delete` (also callable as `g8.api.call("delete_company_companies__company_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `companies:delete`
+- ★ Hand-written: [`g8.companies.delete()`](../sdk-clients.md#g8-companies-delete)
+
+Soft-delete a company.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | Company ID |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.companies.deleteCompany({ path: { company_id: 123 } });
+```
+
+---
+
+<a id="op-deletecompanycolumn"></a>
+
+### `g8.api.companies.deleteCompanyColumn(input)`
+
+**Delete Company Column**
+
+- HTTP: `DELETE /api/v1/companies/columns/{column_id}`
+- operationId: `delete_company_column_companies_columns__column_id__delete` (also callable as `g8.api.call("delete_company_column_companies_columns__column_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `companies:delete`
+
+Soft-delete a custom company column (sets deleted_at; data is not physically removed).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.column_id` | `integer` | yes | ID of the column to delete |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.companies.deleteCompanyColumn({ path: { column_id: 123 } });
+```
+
+---
+
+<a id="op-deletecompanydocument"></a>
+
+### `g8.api.companies.deleteCompanyDocument(input)`
+
+**Delete Company Document**
+
+- HTTP: `DELETE /api/v1/companies/{company_id}/documents/{document_id}`
+- operationId: `delete_company_document_companies__company_id__documents__document_id__delete` (also callable as `g8.api.call("delete_company_document_companies__company_id__documents__document_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `companies:delete`
+
+Delete one generated document PERMANENTLY. Regenerating it spends credits.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+| `path.document_id` | `string` | yes | Document id. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.companies.deleteCompanyDocument({ path: { company_id: "id", document_id: "id" } });
+```
+
+---
+
+<a id="op-enrichcompany"></a>
+
+### `g8.api.companies.enrichCompany(input)`
+
+**Enrich Company**
+
+- HTTP: `POST /api/v1/companies/{company_id}/enrich`
+- operationId: `enrich_company_companies__company_id__enrich_post` (also callable as `g8.api.call("enrich_company_companies__company_id__enrich_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Look this company up with the enrichment provider. SPENDS CREDITS.
+
+Queues the lookup and returns immediately; the fields land on the company
+when it completes. A company with no domain is refused - the lookup is by
+domain.
+
+The app spells this route after the provider it happens to use today. That
+name is not published here: which provider runs is an implementation
+detail, and the route would have to be renamed the day it changes.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.companies.enrichCompany({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-generatecompanydocument"></a>
+
+### `g8.api.companies.generateCompanyDocument(input)`
+
+**Generate Company Document**
+
+- HTTP: `POST /api/v1/companies/{company_id}/documents/types/{doc_type}/generate`
+- operationId: `generate_company_document_companies__company_id__documents_types__doc_type__generate_post` (also callable as `g8.api.call("generate_company_document_companies__company_id__documents_types__doc_type__generate_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Generate ONE document of this type. SPENDS CREDITS. Asynchronous.
+
+`types/` separates the document TYPE from a document id, so this can
+never be confused with `DELETE /companies/{id}/documents/{document_id}`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+| `path.doc_type` | `string` | yes | Document type, e.g. `account_brief`. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.companies.generateCompanyDocument({ path: { company_id: "id", doc_type: "example" } });
+```
+
+---
+
+<a id="op-getcompaniesopenjobs"></a>
+
+### `g8.api.companies.getCompaniesOpenJobs(input)`
+
+**Get Companies Open Jobs**
+
+- HTTP: `POST /api/v1/companies/open-jobs`
+- operationId: `get_companies_open_jobs_companies_open_jobs_post` (also callable as `g8.api.call("get_companies_open_jobs_companies_open_jobs_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+What are these CRM companies hiring for, right now?
+
+A growth/buying signal: a company staffing up is a company with budget.
+Unrelated to `/marketplace/job-posts`, which publishes SDR roles you are
+recruiting for - both are called "jobs" but they share no data.
+
+`company_ids` are `mashup_companies.id` values, NOT `linkedin_company_id`.
+Both are bare ints, so passing the wrong one addresses a different company
+rather than erroring.
+
+Results split into `items` (resolved) and `unresolved`. An unresolved
+company is normal: it means the company could not be matched to a LinkedIn
+company page, not that it is not hiring. Read `lcid_confidence` before
+trusting a match - 1.0 is an exact LinkedIn-URL match, 0.7 is a domain
+fallback that can mismatch on shared or parked domains. `open_jobs` counts
+postings seen within `window_days`; the source carries no open/closed state,
+so a filled role lingers until it ages out.
+
+Org isolation is by Postgres schema, so ids belonging to another org come
+back as `unresolved` with no existence disclosure. Owner-level RBAC
+(`CompanyScopeFilter`) is deliberately not applied: it reads
+`user.permissions`, which an API-key user does not carry, so wiring it in
+would resolve every API-key caller to scope "none" and return zero rows.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CompaniesOpenJobsRequest` | yes | Request body; fields below. |
+
+Body fields (`CompaniesOpenJobsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.company_ids` | `Array<integer>` | yes | CRM company IDs (mashup_companies.id) - NOT linkedin_company_id min items 1, max items 200 |
+| `body.include_postings` | `boolean` | no | False = counts only (one CH query) default `true` |
+| `body.include_subsidiaries` | `boolean` | no | Roll subsidiary postings into the parent. Off by default: one row = one company. NOTE: when true, `jobs` expands to child companies but `open_jobs` stays parent-only, so len(jobs) can exceed open_jobs. default `false` |
+| `body.limit_per_company` | `integer` | no | default `25`, min 1, max 50 |
+| `body.window_days` | `integer` | no | default `60`, min 1, max 365 |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompaniesOpenJobs({ body: { company_ids: [123] } });
+```
+
+---
+
+<a id="op-getcompany"></a>
+
+### `g8.api.companies.getCompany(input)`
+
+**Get Company**
+
+- HTTP: `GET /api/v1/companies/{company_id}`
+- operationId: `get_company_companies__company_id__get` (also callable as `g8.api.call("get_company_companies__company_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+- ★ Hand-written: [`g8.companies.get()`](../sdk-clients.md#g8-companies-get)
+
+Get detailed information about a single company.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | Company ID |
+| `query.include_custom_fields` | `boolean` | no | When true, the response includes a `custom_fields` object of custom column values keyed by column slug. Default false omits it. default `false` |
+
+**Returns** `ApiResponse_CompanyResponse_`: the envelope `{ data: CompanyResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CompanyResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `integer` | yes |  |
+| `address` | `string \| null` | no |  |
+| `city` | `string \| null` | no |  |
+| `contact_count` | `integer \| null` | no |  |
+| `country` | `string \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `crunchbase_url` | `string \| null` | no |  |
+| `custom_fields` | `Record<string, string \| null> \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `domain` | `string \| null` | no |  |
+| `employee_count` | `string \| null` | no |  |
+| `facebook_url` | `string \| null` | no |  |
+| `founded_year` | `integer \| null` | no |  |
+| `industry` | `string \| null` | no |  |
+| `industry_group` | `string \| null` | no |  |
+| `linkedin_followers` | `string \| null` | no |  |
+| `linkedin_url` | `string \| null` | no |  |
+| `logo_url` | `string \| null` | no |  |
+| `meta_data` | `Record<string, unknown> \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `phone` | `string \| null` | no |  |
+| `revenue` | `string \| null` | no |  |
+| `state` | `string \| null` | no |  |
+| `twitter_url` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+| `website` | `string \| null` | no |  |
+| `zip` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompany({ path: { company_id: 123 } });
+```
+
+---
+
+<a id="op-getcompanybillingprefill"></a>
+
+### `g8.api.companies.getCompanyBillingPrefill(input)`
+
+**Get Company Billing Prefill**
+
+- HTTP: `GET /api/v1/companies/{company_id}/billing-prefill`
+- operationId: `get_company_billing_prefill_companies__company_id__billing_prefill_get` (also callable as `g8.api.call("get_company_billing_prefill_companies__company_id__billing_prefill_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+Billing details discovered for this company, ready to prefill a quote.
+
+`status` is the field to read first: `ready` means the details are usable,
+`pending` means discovery has not finished, `empty` means nothing was
+found. Reads only - it does not trigger discovery.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanyBillingPrefill({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-getcompanycontacts"></a>
+
+### `g8.api.companies.getCompanyContacts(input)`
+
+**Get Company Contacts**
+
+- HTTP: `GET /api/v1/companies/{company_id}/contacts`
+- operationId: `get_company_contacts_companies__company_id__contacts_get` (also callable as `g8.api.call("get_company_contacts_companies__company_id__contacts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+- ★ Hand-written: [`g8.companies.contacts()`](../sdk-clients.md#g8-companies-contacts)
+
+Get contacts belonging to a company.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | Company ID |
+| `query.limit` | `integer` | no | Items per page (max 200) default `100` |
+| `query.offset` | `integer` | no | Offset for pagination default `0` |
+
+**Returns** `ApiResponse_list_CompanyContactItem__`: the envelope `{ data: Array<CompanyContactItem>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CompanyContactItem` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `integer` | yes |  |
+| `city` | `string \| null` | no |  |
+| `country` | `string \| null` | no |  |
+| `direct_phone` | `string \| null` | no |  |
+| `first_name` | `string \| null` | no |  |
+| `full_name` | `string \| null` | no |  |
+| `job_title` | `string \| null` | no |  |
+| `last_name` | `string \| null` | no |  |
+| `linkedin_url` | `string \| null` | no |  |
+| `seniority_level` | `string \| null` | no |  |
+| `state` | `string \| null` | no |  |
+| `work_email` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanyContacts({ path: { company_id: 123 } });
+```
+
+---
+
+<a id="op-getcompanydashboard"></a>
+
+### `g8.api.companies.getCompanyDashboard(input)`
+
+**Get Company Dashboard**
+
+- HTTP: `GET /api/v1/companies/{company_id}/dashboard`
+- operationId: `get_company_dashboard_companies__company_id__dashboard_get` (also callable as `g8.api.call("get_company_dashboard_companies__company_id__dashboard_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+Everything the company detail view shows, in one call.
+
+The deal it surfaces is filtered by its own ALWAYS-ENFORCED deal scope:
+being able to see a company never implies being able to see its deals, so
+a key without deal visibility gets the dashboard with no active deal
+rather than a deal it should not see.
+
+Open-shaped, and it has three legitimate shapes - a full dashboard, and
+two shells for companies that have not been through the account pipeline.
+Read `document_status` to tell them apart.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanyDashboard({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-getcompanydetail"></a>
+
+### `g8.api.companies.getCompanyDetail(input)`
+
+**Get Company Detail**
+
+- HTTP: `GET /api/v1/companies/{company_id}/detail`
+- operationId: `get_company_detail_companies__company_id__detail_get` (also callable as `g8.api.call("get_company_detail_companies__company_id__detail_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+The composed company record the app's detail page renders.
+
+Firmographics, owner, CRM overlay and custom column values in one read.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+| `query.id_kind` | `"auto" \| "company_id"` | no | `auto` resolves the graph8 company id (integer or UUID); `company_id` resolves the global company business key. default `"auto"` |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanyDetail({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-getcompanyengagementsummary"></a>
+
+### `g8.api.companies.getCompanyEngagementSummary(input)`
+
+**Get Company Engagement Summary**
+
+- HTTP: `GET /api/v1/companies/{company_id}/engagement-summary`
+- operationId: `get_company_engagement_summary_companies__company_id__engagement_summary_get` (also callable as `g8.api.call("get_company_engagement_summary_companies__company_id__engagement_summary_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+How much this company has engaged: emails, calls, meetings, visits.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanyEngagementSummary({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-getcompanyformfields"></a>
+
+### `g8.api.companies.getCompanyFormFields(input?)`
+
+**Get Company Form Fields**
+
+- HTTP: `GET /api/v1/companies/form-fields`
+- operationId: `get_company_form_fields_companies_form_fields_get` (also callable as `g8.api.call("get_company_form_fields_companies_form_fields_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+Fields grouped the way the company form presents them.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.list_id` | `integer \| null` | no | Include this list's custom fields. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanyFormFields();
+```
+
+---
+
+<a id="op-getcompanyicpfit"></a>
+
+### `g8.api.companies.getCompanyIcpFit(input)`
+
+**Get Company Icp Fit**
+
+- HTTP: `GET /api/v1/companies/{company_id}/icp-fit`
+- operationId: `get_company_icp_fit_companies__company_id__icp_fit_get` (also callable as `g8.api.call("get_company_icp_fit_companies__company_id__icp_fit_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+How well this company matches your ideal-customer profiles.
+
+A company with no match is a 404 here. The app handler answers 200 with an
+`error` key instead, which makes a missing company indistinguishable from
+a scored one at the status line - translated at this boundary rather than
+published.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | Company business key. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanyIcpFit({ path: { company_id: 123 } });
+```
+
+---
+
+<a id="op-getcompanyintelligencedata"></a>
+
+### `g8.api.companies.getCompanyIntelligenceData(input)`
+
+**Get Company Intelligence Data**
+
+- HTTP: `GET /api/v1/companies/{company_id}/intelligence-data/{data_type}`
+- operationId: `get_company_intelligence_data_companies__company_id__intelligence_data__data_type__get` (also callable as `g8.api.call("get_company_intelligence_data_companies__company_id__intelligence_data__data_type__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+The raw intelligence record of one type - the input the documents are written from.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+| `path.data_type` | `string` | yes | Intelligence data type, e.g. `tech_stack`. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanyIntelligenceData({ path: { company_id: "id", data_type: "example" } });
+```
+
+---
+
+<a id="op-getcompanyintelligencestatus"></a>
+
+### `g8.api.companies.getCompanyIntelligenceStatus(input)`
+
+**Get Company Intelligence Status**
+
+- HTTP: `GET /api/v1/companies/{company_id}/intelligence-status`
+- operationId: `get_company_intelligence_status_companies__company_id__intelligence_status_get` (also callable as `g8.api.call("get_company_intelligence_status_companies__company_id__intelligence_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+One rolled-up status for this company's intelligence run.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanyIntelligenceStatus({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-getcompanyintelligencesteps"></a>
+
+### `g8.api.companies.getCompanyIntelligenceSteps(input)`
+
+**Get Company Intelligence Steps**
+
+- HTTP: `GET /api/v1/companies/{company_id}/intelligence-steps`
+- operationId: `get_company_intelligence_steps_companies__company_id__intelligence_steps_get` (also callable as `g8.api.call("get_company_intelligence_steps_companies__company_id__intelligence_steps_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+Per-step state of the intelligence pipeline for this company.
+
+The granular view: one entry per step with its own status, progress and
+error. `intelligence-status` is the single rolled-up answer.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanyIntelligenceSteps({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-getcompanynextbeststep"></a>
+
+### `g8.api.companies.getCompanyNextBestStep(input)`
+
+**Get Company Next Best Step**
+
+- HTTP: `GET /api/v1/companies/{company_id}/next-best-step`
+- operationId: `get_company_next_best_step_companies__company_id__next_best_step_get` (also callable as `g8.api.call("get_company_next_best_step_companies__company_id__next_best_step_get", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+What to do next with this company, and why. SPENDS CREDITS.
+
+A GET that costs money: the recommendation is generated by a model on a
+cache miss, and the cache key includes the company's engagement state, so
+activity on the account invalidates it. Tiered `billable` for that reason
+rather than as an ordinary read.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | Company id. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.companies.getCompanyNextBestStep({ path: { company_id: 123 } });
+```
+
+---
+
+<a id="op-getcompanyreviewstats"></a>
+
+### `g8.api.companies.getCompanyReviewStats(input?)`
+
+**Get Company Review Stats**
+
+- HTTP: `GET /api/v1/companies/review-stats`
+- operationId: `get_company_review_stats_companies_review_stats_get` (also callable as `g8.api.call("get_company_review_stats_companies_review_stats_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+How many companies and contacts are flagged as needing review.
+
+ORG-WIDE counts. The app handler takes no record scope, so unlike the
+listing beside it these totals are not narrowed to what the caller can
+see - two keys with different record scopes get the same numbers.
+
+**Input**: none.
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanyReviewStats();
+```
+
+---
+
+<a id="op-getcompanysignals"></a>
+
+### `g8.api.companies.getCompanySignals(input)`
+
+**Get Company Signals**
+
+- HTTP: `GET /api/v1/companies/{company_id}/signals`
+- operationId: `get_company_signals_companies__company_id__signals_get` (also callable as `g8.api.call("get_company_signals_companies__company_id__signals_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+Buying signals recorded against this company, newest first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | Company id. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanySignals({ path: { company_id: 123 } });
+```
+
+---
+
+<a id="op-getcompanysitesvisited"></a>
+
+### `g8.api.companies.getCompanySitesVisited(input)`
+
+**Get Company Sites Visited**
+
+- HTTP: `GET /api/v1/companies/{company_id}/sites-visited`
+- operationId: `get_company_sites_visited_companies__company_id__sites_visited_get` (also callable as `g8.api.call("get_company_sites_visited_companies__company_id__sites_visited_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+Pages people at this company visited on your site.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | Company business key. |
+| `query.days` | `integer` | no | Lookback window. Bounded here rather than left open: the query is an unindexed analytics scan and an unbounded window is a cheap way to exhaust it. default `90` |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanySitesVisited({ path: { company_id: 123 } });
+```
+
+---
+
+<a id="op-getcompanysynthesisreadiness"></a>
+
+### `g8.api.companies.getCompanySynthesisReadiness(input)`
+
+**Get Company Synthesis Readiness**
+
+- HTTP: `GET /api/v1/companies/{company_id}/synthesis-readiness`
+- operationId: `get_company_synthesis_readiness_companies__company_id__synthesis_readiness_get` (also callable as `g8.api.call("get_company_synthesis_readiness_companies__company_id__synthesis_readiness_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+Whether synthesis can run yet, and what is blocking it.
+
+Worth calling before `retry-synthesis`: `blocking_issues` names what is
+missing, and retrying without fixing it spends credits to fail again.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanySynthesisReadiness({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-getcompanyworkflowstatus"></a>
+
+### `g8.api.companies.getCompanyWorkflowStatus(input)`
+
+**Get Company Workflow Status**
+
+- HTTP: `GET /api/v1/companies/{company_id}/workflow-status`
+- operationId: `get_company_workflow_status_companies__company_id__workflow_status_get` (also callable as `g8.api.call("get_company_workflow_status_companies__company_id__workflow_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+Where this company's intelligence and synthesis workflows stand.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+| `query.include_documents` | `boolean` | no | Also list the documents each workflow produced. default `false` |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.getCompanyWorkflowStatus({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-importcompanies"></a>
+
+### `g8.api.companies.importCompanies(input)`
+
+**Import Companies**
+
+- HTTP: `POST /api/v1/companies/import`
+- operationId: `import_companies_companies_import_post` (also callable as `g8.api.call("import_companies_companies_import_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Create or update companies from a batch of contacts. SPENDS CREDITS.
+
+Contacts are grouped by email domain: a new domain creates a company, a
+known one is updated. Every NEW company then triggers the full
+intelligence pipeline - a site crawl, several model calls and a paid
+enrichment lookup - and every contact triggers a paid person lookup. One
+request with 50 domains and 500 contacts is 50 pipelines plus 550 provider
+calls, so this is the most expensive operation on the company surface.
+
+The body is REQUIRED here. The app declares it optional and then reads
+`data.contacts` unconditionally, so an empty request there is an
+AttributeError and a 500; requiring it makes the same request a 422.
+
+Individual rows can fail without failing the call - read the response
+rather than the status.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ImportCompaniesRequest` | yes | Request body; fields below. |
+
+Body fields (`ImportCompaniesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.contacts` | `Array<CompanyContactImport>` | yes | Contacts to import. |
+| `body.source` | `string` | yes | Where the records came from, recorded on the import. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.companies.importCompanies({
+  body: {
+    contacts: [
+      {
+        email: "jane@acme.com",
+        first_name: "Example",
+        last_name: "Example",
+      },
+    ],
+    source: "example",
+  },
+});
+```
+
+---
+
+<a id="op-listcompanies"></a>
+
+### `g8.api.companies.listCompanies(input?)`
+
+**List Companies**
+
+- HTTP: `GET /api/v1/companies`
+- operationId: `list_companies_companies_get` (also callable as `g8.api.call("list_companies_companies_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+- ★ Hand-written: [`g8.companies.list()`](../sdk-clients.md#g8-companies-list)
+
+List companies with optional filtering and pagination.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.page` | `integer` | no | Page number (1-indexed) default `1` |
+| `query.limit` | `integer` | no | Items per page (max 200) default `50` |
+| `query.domain` | `string \| null` | no | Filter by domain (exact match) |
+| `query.industry` | `string \| null` | no | Filter by industry (partial match) |
+| `query.name` | `string \| null` | no | Filter by company name (partial match) |
+| `query.employee_count_min` | `integer \| null` | no | Minimum employee count |
+| `query.employee_count_max` | `integer \| null` | no | Maximum employee count |
+| `query.country` | `string \| null` | no | Filter by country (exact match) |
+| `query.state` | `string \| null` | no | Filter by state (exact match) |
+| `query.city` | `string \| null` | no | Filter by city (partial match) |
+| `query.description` | `string \| null` | no | Filter by company description (partial match) |
+| `query.revenue_min` | `integer \| null` | no | Minimum annual revenue |
+| `query.revenue_max` | `integer \| null` | no | Maximum annual revenue |
+| `query.founded_year_min` | `integer \| null` | no | Minimum founding year |
+| `query.founded_year_max` | `integer \| null` | no | Maximum founding year |
+| `query.linkedin_followers_min` | `integer \| null` | no | Minimum LinkedIn followers |
+| `query.linkedin_followers_max` | `integer \| null` | no | Maximum LinkedIn followers |
+| `query.include_custom_fields` | `boolean` | no | When true, each company includes a `custom_fields` object of custom column values keyed by column slug. Default false keeps the legacy response shape and adds no extra query. default `false` |
+
+**Returns** `ApiResponse_list_CompanyListItem__`: the envelope `{ data: Array<CompanyListItem>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CompanyListItem` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `city` | `string \| null` | no |  |
+| `country` | `string \| null` | no |  |
+| `custom_fields` | `Record<string, string \| null> \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `domain` | `string \| null` | no |  |
+| `employee_count` | `string \| null` | no |  |
+| `founded_year` | `integer \| null` | no |  |
+| `id` | `integer \| null` | no |  |
+| `industry` | `string \| null` | no |  |
+| `linkedin_followers` | `string \| null` | no |  |
+| `linkedin_url` | `string \| null` | no |  |
+| `logo_url` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `owner_id` | `string \| null` | no |  |
+| `owner_name` | `string \| null` | no |  |
+| `revenue` | `string \| null` | no |  |
+| `state` | `string \| null` | no |  |
+| `website` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.companies.listCompanies();
+```
+
+---
+
+<a id="op-listcompaniesenriched"></a>
+
+### `g8.api.companies.listCompaniesEnriched(input?)`
+
+**List Companies Enriched**
+
+- HTTP: `GET /api/v1/companies/enriched`
+- operationId: `list_companies_enriched_companies_enriched_get` (also callable as `g8.api.call("list_companies_enriched_companies_enriched_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+Companies with their revenue and account overlays joined on.
+
+`GET /companies` returns the base record. This returns the same companies
+with the ABM and revenue overlay fields - tier, score, owner, status -
+coalesced in, which is what the account views are built from.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.skip` | `integer` | no | Rows to skip. default `0` |
+| `query.limit` | `integer` | no | Rows to return. The app defaults this to 10000 - the entire roster in one response. Defaulted to 100 here; raise it deliberately. default `100` |
+| `query.search` | `string \| null` | no | Substring match on name or domain. |
+| `query.status` | `string \| null` | no | Filter by record status, e.g. `prospect`. |
+| `query.website_status` | `string \| null` | no | Filter by website status. |
+
+**Returns** `ApiResponse_CrmCollectionPayload_`: the envelope `{ data: CrmCollectionPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CrmCollectionPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.companies.listCompaniesEnriched();
+```
+
+---
+
+<a id="op-listcompanycolumns"></a>
+
+### `g8.api.companies.listCompanyColumns(input?)`
+
+**List Company Columns**
+
+- HTTP: `GET /api/v1/companies/columns`
+- operationId: `list_company_columns_companies_columns_get` (also callable as `g8.api.call("list_company_columns_companies_columns_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+- ★ Hand-written: [`g8.companies.listColumns()`](../sdk-clients.md#g8-companies-listcolumns)
+
+List custom company columns (table columns + global dynamic columns; +list-scoped if list_id given).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.list_id` | `integer \| null` | no | Optional list ID. When provided, list-specific dynamic columns are included alongside global ones. |
+
+**Returns** `ApiResponse_list_Column__`: the envelope `{ data: Array<Column>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`Column` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `is_global` | `boolean` | yes | Automatically computed: True if object_id is None/empty, False otherwise. |
+| `title` | `string` | yes |  |
+| `data_type` | `ColumnType` | no | default `"text"` |
+| `id` | `integer \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `object_id` | `string \| null` | no |  |
+| `source` | `ColumnSource` | no | default `"contact"` |
+
+**Example**
+
+```ts
+const result = await g8.api.companies.listCompanyColumns();
+```
+
+---
+
+<a id="op-listcompanydocuments"></a>
+
+### `g8.api.companies.listCompanyDocuments(input)`
+
+**List Company Documents**
+
+- HTTP: `GET /api/v1/companies/{company_id}/documents`
+- operationId: `list_company_documents_companies__company_id__documents_get` (also callable as `g8.api.call("list_company_documents_companies__company_id__documents_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+The intelligence documents generated for this company.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+| `query.folder` | `string \| null` | no | Only documents in this folder. |
+
+**Returns** `ApiResponse_CrmCollectionPayload_`: the envelope `{ data: CrmCollectionPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CrmCollectionPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.companies.listCompanyDocuments({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-listcompanypeople"></a>
+
+### `g8.api.companies.listCompanyPeople(input)`
+
+**List Company People**
+
+- HTTP: `GET /api/v1/companies/{company_id}/people`
+- operationId: `list_company_people_companies__company_id__people_get` (also callable as `g8.api.call("list_company_people_companies__company_id__people_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+The people at this company, with their buying-committee roles.
+
+Overlaps `GET /companies/{company_id}/contacts`, which returns the same
+people as contact records. This one is the account-team view: the roles
+and engagement scoring the ABM surface reads.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+
+**Returns** `ApiResponse_CrmCollectionPayload_`: the envelope `{ data: CrmCollectionPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CrmCollectionPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.companies.listCompanyPeople({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-listcompanytasks"></a>
+
+### `g8.api.companies.listCompanyTasks(input)`
+
+**List Company Tasks**
+
+- HTTP: `GET /api/v1/companies/{company_id}/tasks`
+- operationId: `list_company_tasks_companies__company_id__tasks_get` (also callable as `g8.api.call("list_company_tasks_companies__company_id__tasks_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+Tasks attached to this company that the key can see.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | Company id. |
+| `query.task_status` | `string \| null` | no | Only tasks in this status. |
+
+**Returns** `ApiResponse_CrmCollectionPayload_`: the envelope `{ data: CrmCollectionPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CrmCollectionPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.companies.listCompanyTasks({ path: { company_id: 123 } });
+```
+
+---
+
+<a id="op-listcontactsacrosscompanies"></a>
+
+### `g8.api.companies.listContactsAcrossCompanies(input?)`
+
+**List Contacts Across Companies**
+
+- HTTP: `GET /api/v1/companies/contacts`
+- operationId: `list_contacts_across_companies_companies_contacts_get` (also callable as `g8.api.call("list_contacts_across_companies_companies_contacts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+Contacts across EVERY company, with their company and pipeline context.
+
+The buying-committee view: `department`, `buying_role` and `in_pipeline`
+are not available on `GET /contacts`, and each row carries the company it
+belongs to.
+
+Published under `/companies` because that is the surface it belongs to,
+but the rows it returns are CONTACTS and it is filtered by the CONTACT
+record scope. A key holding `companies:read` without contact visibility
+resolves that scope to nothing and gets an empty result rather than a
+company-scoped one - it fails closed, but it is worth knowing which of the
+two scopes actually governs the rows.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.skip` | `integer` | no | default `0` |
+| `query.limit` | `integer` | no | The app defaults this to 10000; 100 here. default `100` |
+| `query.search` | `string \| null` | no | Substring match on name or email. |
+| `query.department` | `string \| null` | no | Filter by job department. |
+| `query.buying_role` | `string \| null` | no | Filter by buying-committee role, e.g. `decision_maker`. |
+| `query.in_pipeline` | `boolean` | no | Only contacts attached to an open deal. default `false` |
+| `query.owner_id` | `string \| null` | no | Filter by contact owner. |
+| `query.sort_by` | `string` | no | name \| title \| company_name \| department \| email \| updated_at default `"updated_at"` |
+| `query.sort_order` | `string` | no | asc \| desc default `"desc"` |
+
+**Returns** `ApiResponse_CrmCollectionPayload_`: the envelope `{ data: CrmCollectionPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CrmCollectionPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.companies.listContactsAcrossCompanies();
+```
+
+---
+
+<a id="op-mergecompany"></a>
+
+### `g8.api.companies.mergeCompany(input)`
+
+**Merge Company**
+
+- HTTP: `POST /api/v1/companies/{company_id}/merge`
+- operationId: `merge_company_companies__company_id__merge_post` (also callable as `g8.api.call("merge_company_companies__company_id__merge_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `companies:delete`
+
+Merge `secondary_id` INTO this company. THE SECONDARY STOPS EXISTING.
+
+Its contacts, deals and activity move onto the survivor. Undo is one merge
+at a time through `POST /duplicates/undo-merge/{merge_history_id}`.
+Preview first. 409 when a blocker refuses the merge.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | The company that SURVIVES the merge. |
+| `body` | `MergeRecordRequest` | yes | Request body; fields below. |
+
+Body fields (`MergeRecordRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.secondary_id` | `integer` | yes | The record merged AWAY. |
+| `body.bulk_criterion` | `string \| null` | no | The bulk criterion, when `trigger` is `bulk_criterion`. |
+| `body.field_overrides` | `Array<MergeFieldOverride>` | no | Decide individual fields instead of the app's rules. |
+| `body.suggestion_id` | `string \| null` | no | The duplicate suggestion this merge acts on, if any. |
+| `body.trigger` | `"manual" \| "bulk_criterion"` | no | What prompted the merge. Recorded on the audit row. default `"manual"` |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.companies.mergeCompany({ path: { company_id: 123 }, body: { secondary_id: 123 } });
+```
+
+---
+
+<a id="op-mergefilteredcompanies"></a>
+
+### `g8.api.companies.mergeFilteredCompanies(input)`
+
+**Merge Filtered Companies**
+
+- HTTP: `POST /api/v1/companies/merge-filtered`
+- operationId: `merge_filtered_companies_companies_merge_filtered_post` (also callable as `g8.api.call("merge_filtered_companies_companies_merge_filtered_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `companies:write`
+
+Add every company matching a filter into `target_list_id`.
+
+Despite the name this does NOT merge duplicate companies together - it
+merges a SELECTION INTO A LIST. `/duplicates` merges records.
+
+A 409 means some companies need a decision; re-send with
+`conflict_resolution`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `MergeFilteredRequest` | yes | Request body; fields below. |
+| `query.filterModel` | `string \| null` | no | Optional per-column filter JSON. |
+| `query.sortModel` | `string \| null` | no | Optional sort JSON. |
+
+Body fields (`MergeFilteredRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.target_list_id` | `integer` | yes | List the matching records are added to. |
+| `body.conflict_resolution` | `"add_all" \| "skip_all" \| "custom" \| null` | no | Required when retrying after a 409. `add_all` takes every warned record, `skip_all` takes none of them, `custom` takes the ids in `include_warned_ids`. Blocked records are excluded either way. |
+| `body.dynamic_column_mapping` | `Record<string, string>` | no | Source-column to target-column mapping for custom columns. |
+| `body.filter` | `Array<FilterCondition>` | no | Conditions selecting the source records. |
+| `body.include_warned_ids` | `Array<string> \| null` | no | With `conflict_resolution=custom`, the warned ids to include. |
+| `body.segmentFilter` | `SegmentFilterGroup \| null` | no | Advanced AND/OR filter tree. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.mergeFilteredCompanies({ body: { target_list_id: 123 } });
+```
+
+---
+
+<a id="op-previewcompanymerge"></a>
+
+### `g8.api.companies.previewCompanyMerge(input)`
+
+**Preview Company Merge**
+
+- HTTP: `GET /api/v1/companies/{company_id}/merge/preview`
+- operationId: `preview_company_merge_companies__company_id__merge_preview_get` (also callable as `g8.api.call("preview_company_merge_companies__company_id__merge_preview_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `companies:read`
+
+Side-by-side comparison and blocker check. Writes nothing.
+
+Both companies are authorised inside the app handler.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | The company that SURVIVES the merge. |
+| `query.secondary` | `integer` | yes | The company that would be merged AWAY. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.previewCompanyMerge({ path: { company_id: 123 }, query: { secondary: 1 } });
+```
+
+---
+
+<a id="op-refreshcompanybillingprefill"></a>
+
+### `g8.api.companies.refreshCompanyBillingPrefill(input)`
+
+**Refresh Company Billing Prefill**
+
+- HTTP: `POST /api/v1/companies/{company_id}/billing-prefill/refresh`
+- operationId: `refresh_company_billing_prefill_companies__company_id__billing_prefill_refresh_post` (also callable as `g8.api.call("refresh_company_billing_prefill_companies__company_id__billing_prefill_refresh_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `companies:write`
+
+Recompute the billing details suggested for this company's quotes.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.refreshCompanyBillingPrefill({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-regeneratecompanydocument"></a>
+
+### `g8.api.companies.regenerateCompanyDocument(input)`
+
+**Regenerate Company Document**
+
+- HTTP: `POST /api/v1/companies/{company_id}/documents/types/{doc_type}/regenerate`
+- operationId: `regenerate_company_document_companies__company_id__documents_types__doc_type__regenerate_post` (also callable as `g8.api.call("regenerate_company_document_companies__company_id__documents_types__doc_type__regenerate_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Throw away this document and generate it again. SPENDS CREDITS.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+| `path.doc_type` | `string` | yes | Document type. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.companies.regenerateCompanyDocument({ path: { company_id: "id", doc_type: "example" } });
+```
+
+---
+
+<a id="op-removecompanycontact"></a>
+
+### `g8.api.companies.removeCompanyContact(input)`
+
+**Remove Company Contact**
+
+- HTTP: `DELETE /api/v1/companies/{company_id}/contacts/{contact_id}`
+- operationId: `remove_company_contact_companies__company_id__contacts__contact_id__delete` (also callable as `g8.api.call("remove_company_contact_companies__company_id__contacts__contact_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `companies:delete`
+
+Unlink a contact from this company. Neither record is deleted.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+| `path.contact_id` | `string` | yes | Contact to unlink from the company. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.companies.removeCompanyContact({ path: { company_id: "id", contact_id: "id" } });
+```
+
+---
+
+<a id="op-retrycompanyintelligence"></a>
+
+### `g8.api.companies.retryCompanyIntelligence(input)`
+
+**Retry Company Intelligence**
+
+- HTTP: `POST /api/v1/companies/{company_id}/retry-intelligence`
+- operationId: `retry_company_intelligence_companies__company_id__retry_intelligence_post` (also callable as `g8.api.call("retry_company_intelligence_companies__company_id__retry_intelligence_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Re-run the intelligence pipeline for this company. SPENDS CREDITS.
+
+A site crawl plus several model calls per document. Omitting `doc_types`
+regenerates the DEFAULT set, so an empty body is the expensive option and
+not the cheap one - name the documents you actually need.
+
+A run stuck for more than half an hour is treated as abandoned and
+restarted, so this is callable again rather than wedged, but that also
+means it can be re-triggered on a cadence. It is tiered `billable`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+| `body` | `IntelligenceRetryRequest \| null` | no | Request body; fields below. |
+
+Body fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.doc_types` | `Array<string> \| null` | no | Document types to generate. Omit for the default set. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.companies.retryCompanyIntelligence({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-retrycompanysynthesis"></a>
+
+### `g8.api.companies.retryCompanySynthesis(input)`
+
+**Retry Company Synthesis**
+
+- HTTP: `POST /api/v1/companies/{company_id}/retry-synthesis`
+- operationId: `retry_company_synthesis_companies__company_id__retry_synthesis_post` (also callable as `g8.api.call("retry_company_synthesis_companies__company_id__retry_synthesis_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Re-run synthesis for this company. SPENDS CREDITS.
+
+Check `synthesis-readiness` first: a run that is missing its inputs spends
+the same credits to produce nothing. A synthesis already marked running is
+refused with a 409 - unlike the intelligence retry beside it there is no
+stale-run reset, so a genuinely stuck run needs support rather than a
+retry loop.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.companies.retryCompanySynthesis({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-saveskillresulttocompany"></a>
+
+### `g8.api.companies.saveSkillResultToCompany(input)`
+
+**Save Skill Result To Company**
+
+- HTTP: `POST /api/v1/companies/{company_id}/documents/from-skill`
+- operationId: `save_skill_result_to_company_companies__company_id__documents_from_skill_post` (also callable as `g8.api.call("save_skill_result_to_company_companies__company_id__documents_from_skill_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `companies:write`
+
+Store a skill run's output on this company as a document.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+| `body` | `SaveSkillResultRequest` | yes | Request body; fields below. |
+
+Body fields (`SaveSkillResultRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.action_name` | `string` | yes | Action within that execution. |
+| `body.content` | `string` | yes | Document body to store. |
+| `body.execution_id` | `string` | yes | The skill execution that produced the content. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.saveSkillResultToCompany({
+  path: { company_id: "id" },
+  body: { action_name: "Example", content: "example", execution_id: "id" },
+});
+```
+
+---
+
+<a id="op-startcompanyworkflow"></a>
+
+### `g8.api.companies.startCompanyWorkflow(input)`
+
+**Start Company Workflow**
+
+- HTTP: `POST /api/v1/companies/{company_id}/workflows/{workflow_type}/start`
+- operationId: `start_company_workflow_companies__company_id__workflows__workflow_type__start_post` (also callable as `g8.api.call("start_company_workflow_companies__company_id__workflows__workflow_type__start_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Start one intelligence workflow for this company. SPENDS CREDITS.
+
+Poll `GET /companies/{company_id}/workflow-status`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+| `path.workflow_type` | `CompanyWorkflowType` | yes | Which workflow to run. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.companies.startCompanyWorkflow({ path: { company_id: "id", workflow_type: "company_intelligence" } });
+```
+
+---
+
+<a id="op-updatecompany"></a>
+
+### `g8.api.companies.updateCompany(input)`
+
+**Update Company**
+
+- HTTP: `PATCH /api/v1/companies/{company_id}`
+- operationId: `update_company_companies__company_id__patch` (also callable as `g8.api.call("update_company_companies__company_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `companies:write`
+- ★ Hand-written: [`g8.companies.update()`](../sdk-clients.md#g8-companies-update)
+
+Update a company's fields (partial update).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | Company ID |
+| `body` | `CompanyUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`CompanyUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.address` | `string \| null` | no |  |
+| `body.city` | `string \| null` | no |  |
+| `body.country` | `string \| null` | no |  |
+| `body.domain` | `string \| null` | no |  |
+| `body.employee_count` | `string \| null` | no |  |
+| `body.industry` | `string \| null` | no |  |
+| `body.linkedin_url` | `string \| null` | no |  |
+| `body.name` | `string \| null` | no |  |
+| `body.phone` | `string \| null` | no |  |
+| `body.state` | `string \| null` | no |  |
+| `body.website` | `string \| null` | no |  |
+| `body.zip` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.companies.updateCompany({ path: { company_id: 123 }, body: {} });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-columnsource"></a>
+
+### `ColumnSource`
+
+Which entity a field in the contact field list belongs to. The ``GET /contacts/columns`` response deliberately combines fields from three provenances into one list (issue #21184): the person record, their employer's company record, and user-created custom columns. Consumers (form-mapping UI, AI-agent field listing, CSV import) need to tell them apart — a company field like ``COMPANY_REVENUE`` describes the employer, not the contact. - ``contact``: a field on the person record (``MashupContact.*``) — the default. - ``company``: a field on the contact's employer (``MashupCompany.*``), surfaced…
+
+Type: `"contact" | "company" | "custom"`.
+
+<a id="type-columntype"></a>
+
+### `ColumnType`
+
+User-selectable dynamic-column data types. Every member must have a physical type in the repos' pg_type_map (contacts/companies CDP repos + enrichment DynamicColumnRepository: int→INTEGER, numeric→NUMERIC, text→TEXT, boolean→BOOLEAN) and belong to the user-owned family in lists/usecases/dynamic_column_write_contract.py — both already list these four. Write paths coerce values per type via shared.infrustructure.db.cdp.dynamic_column_values.coerce_dynamic_value.
+
+Type: `"text" | "int" | "numeric" | "boolean"`.
+
+<a id="type-companycontactimport"></a>
+
+### `CompanyContactImport`
+
+One contact in a company import. Contacts are grouped by email domain, so `email` decides which company a row lands on - `company_name` only names a company that does not exist yet.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `email` | `string` | yes | Email address. Also the company-grouping key. |
+| `first_name` | `string` | yes | First name. |
+| `last_name` | `string` | yes | Last name. |
+| `company_name` | `string \| null` | no | Company name, used only when the domain is unknown. |
+| `company_owner` | `string \| null` | no | Company owner. |
+| `contact_owner` | `string \| null` | no | Contact owner. |
+| `linkedin_url` | `string \| null` | no | LinkedIn profile URL. |
+| `phone` | `string \| null` | no | Phone number. |
+| `role` | `string \| null` | no | Buying-committee role: decision_maker \| influencer \| champion \| end_user \| blocker \| coach. |
+| `title` | `string \| null` | no | Job title. |
+
+<a id="type-createfieldenrichmentinput"></a>
+
+### `CreateFieldEnrichmentInput`
+
+Optional enrichment-pipeline block attached at column-create time. When supplied, `POST /fields` creates a companion `enrichment_configs` row in the same request so the new column is immediately runnable via `POST /enrichment/waterfall/enrich`. Without this block the column exists but has no enrichment plan — calling /waterfall/enrich on it returns 422 (`waterfall_config_missing`). Currently only `type='waterfall'` is supported; AI / formula enrichment will follow once the rest of the agent surface lands.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `email_verification` | `EmailVerificationInput \| null` | no | Optional post-enrichment email verification config. |
+| `field_to_enrich` | `string \| null` | no | Target field identifier. Defaults to the new column's slug. |
+| `name` | `string \| null` | no | Pipeline name. Defaults to `<column title> Enrichment` if omitted. |
+| `providers` | `Array<string> \| null` | no | Ordered list of provider names. Without `target_field`, server maps each to its default email-finder action (legacy). With `target_field`, filters the column template to these providers (correct per-field action preserved). Mutually exclusive with `steps`. |
+| `skip_existing_values` | `boolean` | no | If true, skip rows where the target field is already populated. default `true` |
+| `steps` | `Array<WaterfallStepInput> \| null` | no | Full caller-supplied step list. Persisted verbatim. Mutually exclusive with `providers`. |
+| `target_field` | `string \| null` | no | Kind of data this column holds — CONTACT_DIRECT_PHONE, CONTACT_MOBILE_PHONE, CONTACT_WORK_EMAIL, CONTACT_LINKEDIN_URL, COMPANY_PHONE, ... or a friendly synonym ('phone', 'mobile', 'email', 'linkedin'). When set, the pipeline is built from the server's per-column TEMPLATE so each provider runs its CORRECT action for that data kind (e.g. leadmagic `mobile_finder` for a phone, NOT `email_finder`) —… |
+| `type` | `string` | no | Pipeline kind. Only 'waterfall' is supported today. default `"waterfall"` |
+
+<a id="type-createfieldenrichmentresponse"></a>
+
+### `CreateFieldEnrichmentResponse`
+
+Echo of the companion enrichment config created by `enrichment` block.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `column_id` | `string` | yes | column_id slug to pass to /enrichment/waterfall/enrich |
+| `config_id` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `type` | `string` | yes |  |
+| `email_verification` | `Record<string, unknown> \| null` | no |  |
+| `providers` | `Array<string>` | no |  |
+
+<a id="type-filtercondition"></a>
+
+### `FilterCondition`
+
+One structured filter condition. Mirrors `shared.interfaces.fastapi.dtos.DtoCondition`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `field` | `string` | yes | Field name to apply the condition to. |
+| `operator` | `string` | no | Operator, e.g. `=`, `in`, `like`. default `"="` |
+| `value` | `unknown` | no | Value to compare against. |
+| `value_to` | `unknown \| null` | no | Secondary value, for range operators. |
+
+<a id="type-mergefieldoverride"></a>
+
+### `MergeFieldOverride`
+
+Which side of a merge wins one field.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `field` | `string` | yes | Field name, e.g. `CONTACT_JOB_TITLE`. |
+| `winner` | `"primary" \| "secondary"` | yes | Which record's value to keep. |
+
+<a id="type-segmentfiltergroup"></a>
+
+### `SegmentFilterGroup`
+
+An AND/OR group of leaves and nested groups, at most three groups deep. Mirrors `SegmentFilterGroup` in `contacts.domain.value_objects.ag_grid_models`. `op` is closed because the app REFUSES an unrecognised connector rather than defaulting to AND - defaulting would silently return a different result set, and on a destructive route that is a different set of records acted on. FIXED DEPTH, NOT RECURSIVE. The app's model is self-referencing; the published one deliberately is not, because a schema that reaches itself through `$ref` sends the docs renderer into unbounded recursion. Three group lev…
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `op` | `"AND" \| "OR" \| "and" \| "or"` | yes | Connector for this group. Case-insensitive. |
+| `children` | `Array<SegmentFilterSubgroup \| SegmentFilterLeaf>` | no | Nested groups and/or leaf conditions. |