@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/contacts.md

@@ -0,0 +1,3143 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.contacts`: Contacts
+
+70 operations (36 read, 19 write, 7 destructive, 8 billable).
+
+7 of these also have a hand-written method (`g8.contacts`), 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: [contacts.d.ts](contacts.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`assignContactOwner`](#op-assigncontactowner) | `POST /api/v1/contacts/assign-owner` | write | `contacts:write` | Assign Contact Owner |
+| [`assignContactTags`](#op-assigncontacttags) | `POST /api/v1/contacts/tags/assign` | write | `contacts:write` | Assign Contact Tags |
+| [`batchContactRelated`](#op-batchcontactrelated) | `POST /api/v1/contacts/related` | read | `contacts:read` | Batch Contact Related |
+| [`bulkGetContacts`](#op-bulkgetcontacts) | `POST /api/v1/contacts/bulk-get` | read | `contacts:read` | Bulk Get Contacts |
+| [`bulkUpdateContacts`](#op-bulkupdatecontacts) | `POST /api/v1/contacts/bulk-update` | write | `contacts:write` | Bulk Update Contacts |
+| [`cancelRecordWorkflowExecution`](#op-cancelrecordworkflowexecution) | `POST /api/v1/contacts/workflow-executions/{execution_id}/cancel` | destructive | `contacts:delete` | Cancel Record Workflow Execution |
+| [`createContactColumn`](#op-createcontactcolumn) ★ | `POST /api/v1/contacts/columns/create` | write | `contacts:write` | Create Contact Column |
+| [`createContactTag`](#op-createcontacttag) | `POST /api/v1/contacts/tags` | write | `contacts:write` | Create Contact Tag |
+| [`createContacts`](#op-createcontacts) ★ | `POST /api/v1/contacts` | write | `contacts:write` | Create Contacts |
+| [`decideRecordWorkflowExecution`](#op-deciderecordworkflowexecution) | `POST /api/v1/contacts/workflow-executions/{execution_id}/approve` | write | `contacts:write` | Decide Record Workflow Execution |
+| [`deleteContact`](#op-deletecontact) ★ | `DELETE /api/v1/contacts/{contact_id}` | destructive | `contacts:delete` | Delete Contact |
+| [`deleteContactColumn`](#op-deletecontactcolumn) | `DELETE /api/v1/contacts/columns/{column_id}` | destructive | `contacts:delete` | Delete Contact Column |
+| [`deleteContactDocument`](#op-deletecontactdocument) | `DELETE /api/v1/contacts/{contact_id}/documents/{document_id}` | destructive | `contacts:delete` | Delete Contact Document |
+| [`deleteContactTag`](#op-deletecontacttag) | `DELETE /api/v1/contacts/tags/{tag_id}` | destructive | `contacts:delete` | Delete Contact Tag |
+| [`fetchContacts`](#op-fetchcontacts) | `POST /api/v1/contacts/fetch` | read | `contacts:read` | Fetch Contacts |
+| [`generateAllContactDocuments`](#op-generateallcontactdocuments) | `POST /api/v1/contacts/{contact_id}/documents/generate-all` | billable | `enrichment:run` | Generate All Contact Documents |
+| [`generateContactDocument`](#op-generatecontactdocument) | `POST /api/v1/contacts/{contact_id}/documents/types/{doc_type}/generate` | billable | `enrichment:run` | Generate Contact Document |
+| [`getActivityFeed`](#op-getactivityfeed) | `GET /api/v1/activity-feed` | read | `contacts:read` | Get Activity Feed |
+| [`getContact`](#op-getcontact) ★ | `GET /api/v1/contacts/{contact_id}` | read | `contacts:read` | Get Contact |
+| [`getContactAnalysis`](#op-getcontactanalysis) | `GET /api/v1/contacts/{contact_id}/analysis` | read | `contacts:read` | Get Contact Analysis |
+| [`getContactDashboard`](#op-getcontactdashboard) | `GET /api/v1/contacts/{contact_id}/dashboard` | read | `contacts:read` | Get Contact Dashboard |
+| [`getContactDashboardStats`](#op-getcontactdashboardstats) | `GET /api/v1/contacts/dashboard-stats` | read | `contacts:read` | Get Contact Dashboard Stats |
+| [`getContactDetail`](#op-getcontactdetail) | `GET /api/v1/contacts/{contact_id}/detail` | read | `contacts:read` | Get Contact Detail |
+| [`getContactDocument`](#op-getcontactdocument) | `GET /api/v1/contacts/{contact_id}/documents/types/{doc_type}` | read | `contacts:read` | Get Contact Document |
+| [`getContactEngagementSummary`](#op-getcontactengagementsummary) | `GET /api/v1/contacts/{contact_id}/engagement-summary` | read | `contacts:read` | Get Contact Engagement Summary |
+| [`getContactFormFields`](#op-getcontactformfields) | `GET /api/v1/contacts/form-fields` | read | `contacts:read` | Get Contact Form Fields |
+| [`getContactGenerationStatus`](#op-getcontactgenerationstatus) | `GET /api/v1/contacts/{contact_id}/documents/generation-status` | read | `contacts:read` | Get Contact Generation Status |
+| [`getContactLists`](#op-getcontactlists) | `GET /api/v1/contacts/{contact_id}/lists` | read | `contacts:read` | Get Contact Lists |
+| [`getContactMeetings`](#op-getcontactmeetings) | `GET /api/v1/contacts/{contact_id}/meetings` | read | `contacts:read` | Get Contact Meetings |
+| [`getContactNextBestStep`](#op-getcontactnextbeststep) | `GET /api/v1/contacts/{contact_id}/next-best-step` | billable | `enrichment:run` | Get Contact Next Best Step |
+| [`getContactProfilePictures`](#op-getcontactprofilepictures) | `POST /api/v1/contacts/profile-pictures` | read | `contacts:read` | Get Contact Profile Pictures |
+| [`getContactRowDetail`](#op-getcontactrowdetail) | `GET /api/v1/contacts/row-detail/{record_id}` | read | `contacts:read` | Get Contact Row Detail |
+| [`getContactSequences`](#op-getcontactsequences) | `GET /api/v1/contacts/{contact_id}/sequences` | read | `contacts:read` | Get Contact Sequences |
+| [`getContactSignals`](#op-getcontactsignals) | `GET /api/v1/contacts/{contact_id}/signals` | read | `contacts:read` | Get Contact Signals |
+| [`getContactSitesVisited`](#op-getcontactsitesvisited) | `GET /api/v1/contacts/{contact_id}/sites-visited` | read | `contacts:read` | Get Contact Sites Visited |
+| [`getContactTagIds`](#op-getcontacttagids) | `GET /api/v1/contacts/{contact_id}/tags` | read | `contacts:read` | Get Contact Tag Ids |
+| [`getDuplicateSettings`](#op-getduplicatesettings) | `GET /api/v1/duplicates/settings` | read | `contacts:read` | Get Duplicate Settings |
+| [`getRecordColumnValues`](#op-getrecordcolumnvalues) | `POST /api/v1/contacts/column-values` | read | `contacts:read` | Get Record Column Values |
+| [`listBaseColumns`](#op-listbasecolumns) | `GET /api/v1/contacts/base-columns` | read | `contacts:read` | List Base Columns |
+| [`listColumnNames`](#op-listcolumnnames) | `GET /api/v1/contacts/column-names` | read | `contacts:read` | List Column Names |
+| [`listContactColumnDefinitions`](#op-listcontactcolumndefinitions) | `GET /api/v1/contacts/column-definitions` | read | `contacts:read` | List Contact Column Definitions |
+| [`listContactColumns`](#op-listcontactcolumns) ★ | `GET /api/v1/contacts/columns` | read | `contacts:read` | List Contact Columns |
+| [`listContactDocuments`](#op-listcontactdocuments) | `GET /api/v1/contacts/{contact_id}/documents` | read | `contacts:read` | List Contact Documents |
+| [`listContactTags`](#op-listcontacttags) | `GET /api/v1/contacts/tags` | read | `contacts:read` | List Contact Tags |
+| [`listContacts`](#op-listcontacts) ★ | `GET /api/v1/contacts` | read | `contacts:read` | List Contacts |
+| [`listCustomColumnDefinitions`](#op-listcustomcolumndefinitions) | `GET /api/v1/contacts/custom-column-definitions` | read | `contacts:read` | List Custom Column Definitions |
+| [`listDuplicateDetectionRuns`](#op-listduplicatedetectionruns) | `GET /api/v1/duplicates/detection/runs` | read | `contacts:read` | List Duplicate Detection Runs |
+| [`listRecordWorkflowExecutions`](#op-listrecordworkflowexecutions) | `GET /api/v1/contacts/workflow-executions` | read | `contacts:read` | List Record Workflow Executions |
+| [`listSearchableFields`](#op-listsearchablefields) | `GET /api/v1/contacts/searchable-fields` | read | `contacts:read` | List Searchable Fields |
+| [`mergeContact`](#op-mergecontact) | `POST /api/v1/contacts/{contact_id}/merge` | destructive | `contacts:delete` | Merge Contact |
+| [`mergeContactTags`](#op-mergecontacttags) | `POST /api/v1/contacts/tags/merge` | write | `contacts:write` | Merge Contact Tags |
+| [`mergeFilteredContacts`](#op-mergefilteredcontacts) | `POST /api/v1/contacts/merge-filtered` | write | `contacts:write` | Merge Filtered Contacts |
+| [`pauseRecordWorkflowExecution`](#op-pauserecordworkflowexecution) | `POST /api/v1/contacts/workflow-executions/{execution_id}/pause` | write | `contacts:write` | Pause Record Workflow Execution |
+| [`previewContactMerge`](#op-previewcontactmerge) | `GET /api/v1/contacts/{contact_id}/merge/preview` | read | `contacts:read` | Preview Contact Merge |
+| [`previewDetectionRule`](#op-previewdetectionrule) | `POST /api/v1/duplicates/settings/preview-detection-rule` | read | `contacts:read` | Preview Detection Rule |
+| [`regenerateContactDocument`](#op-regeneratecontactdocument) | `POST /api/v1/contacts/{contact_id}/documents/types/{doc_type}/regenerate` | billable | `enrichment:run` | Regenerate Contact Document |
+| [`resumeRecordWorkflowExecution`](#op-resumerecordworkflowexecution) | `POST /api/v1/contacts/workflow-executions/{execution_id}/resume` | write | `contacts:write` | Resume Record Workflow Execution |
+| [`runDuplicateDetection`](#op-runduplicatedetection) | `POST /api/v1/duplicates/detection/run` | write | `contacts:write` | Run Duplicate Detection |
+| [`runRecordWorkflow`](#op-runrecordworkflow) | `POST /api/v1/contacts/workflow-executions/run` | billable | `enrichment:run` | Run Record Workflow |
+| [`saveSkillResultToContact`](#op-saveskillresulttocontact) | `POST /api/v1/contacts/{contact_id}/documents/from-skill` | write | `contacts:write` | Save Skill Result To Contact |
+| [`triggerAutoMerge`](#op-triggerautomerge) | `POST /api/v1/duplicates/auto-merge` | destructive | `contacts:delete` | Trigger Auto Merge |
+| [`unassignContactTags`](#op-unassigncontacttags) | `POST /api/v1/contacts/tags/unassign` | write | `contacts:write` | Unassign Contact Tags |
+| [`unlockContactInfo`](#op-unlockcontactinfo) | `POST /api/v1/contacts/unlock-info` | billable | `enrichment:run` | Unlock Contact Info |
+| [`updateContact`](#op-updatecontact) ★ | `PATCH /api/v1/contacts/{contact_id}` | write | `contacts:write` | Update Contact |
+| [`updateContactDocument`](#op-updatecontactdocument) | `PUT /api/v1/contacts/{contact_id}/documents/{document_id}` | write | `contacts:write` | Update Contact Document |
+| [`updateContactTag`](#op-updatecontacttag) | `PATCH /api/v1/contacts/tags/{tag_id}` | write | `contacts:write` | Update Contact Tag |
+| [`updateDuplicateSettings`](#op-updateduplicatesettings) | `PUT /api/v1/duplicates/settings` | write | `contacts:write` | Update Duplicate Settings |
+| [`verifyContactEmails`](#op-verifycontactemails) | `POST /api/v1/contacts/verify-email` | billable | `enrichment:run` | Verify Contact Emails |
+| [`verifyContactEmailsAsync`](#op-verifycontactemailsasync) | `POST /api/v1/contacts/verify-email/async` | billable | `enrichment:run` | Verify Contact Emails Async |
+| [`withdrawContactsFromSequences`](#op-withdrawcontactsfromsequences) | `POST /api/v1/contacts/withdraw-from-sequences` | write | `contacts:write` | Withdraw Contacts From Sequences |
+
+---
+
+<a id="op-assigncontactowner"></a>
+
+### `g8.api.contacts.assignContactOwner(input)`
+
+**Assign Contact Owner**
+
+- HTTP: `POST /api/v1/contacts/assign-owner`
+- operationId: `assign_contact_owner_contacts_assign_owner_post` (also callable as `g8.api.call("assign_contact_owner_contacts_assign_owner_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Set the owner on EVERY contact matching a selection.
+
+The selection is resolved server-side, so the number of contacts 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.contacts.assignContactOwner({ body: {} });
+```
+
+---
+
+<a id="op-assigncontacttags"></a>
+
+### `g8.api.contacts.assignContactTags(input)`
+
+**Assign Contact Tags**
+
+- HTTP: `POST /api/v1/contacts/tags/assign`
+- operationId: `assign_contact_tags_contacts_tags_assign_post` (also callable as `g8.api.call("assign_contact_tags_contacts_tags_assign_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Add tags to contacts. Idempotent - re-assigning is not an error.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ContactTagAssignRequest` | yes | Request body; fields below. |
+
+Body fields (`ContactTagAssignRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.tag_ids` | `Array<string>` | yes | min items 1 |
+| `body.contact_ids` | `Array<integer>` | no | Contacts to tag. |
+
+**Returns** `ApiResponse_ContactTagWriteResult_`: the envelope `{ data: ContactTagWriteResult, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.contacts.assignContactTags({ body: { tag_ids: ["id"] } });
+```
+
+---
+
+<a id="op-batchcontactrelated"></a>
+
+### `g8.api.contacts.batchContactRelated(input)`
+
+**Batch Contact Related**
+
+- HTTP: `POST /api/v1/contacts/related`
+- operationId: `batch_contact_related_contacts_related_post` (also callable as `g8.api.call("batch_contact_related_contacts_related_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Sequences and/or lists for up to 100 contacts in ONE request. Writes nothing.
+
+Use this instead of looping `GET /contacts/{contact_id}/sequences` or
+`/lists` per contact: the loop spends one rate-limit slot per contact and
+hits 429 on a large book; this spends one per 100.
+
+Each contact gets exactly what its per-contact route returns, through the
+same access check. A contact that does not exist or is outside the key's
+scope for any requested include comes back `found: false` with no related
+records, rather than failing the batch. POST only because the ids are a
+body; it is tiered as a read.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ContactRelatedBatchRequest` | yes | Request body; fields below. |
+
+Body fields (`ContactRelatedBatchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.contact_ids` | `Array<integer>` | yes | Up to 100 contact ids, the same ids the per-contact routes take. Duplicates are read once; the response keeps first-seen order. min items 1, max items 100 |
+| `body.include` | `Array<"sequences" \| "lists">` | no | Related records to return per contact. `sequences` matches `GET /contacts/{contact_id}/sequences`; `lists` matches `GET /contacts/{contact_id}/lists` (keyed on the contact primary key). min items 1 |
+
+**Returns** `ApiResponse_ContactRelatedBatchResponse_`: the envelope `{ data: ContactRelatedBatchResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ContactRelatedBatchResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<ContactRelatedItem>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.contacts.batchContactRelated({ body: { contact_ids: [123] } });
+```
+
+---
+
+<a id="op-bulkgetcontacts"></a>
+
+### `g8.api.contacts.bulkGetContacts(input)`
+
+**Bulk Get Contacts**
+
+- HTTP: `POST /api/v1/contacts/bulk-get`
+- operationId: `bulk_get_contacts_contacts_bulk_get_post` (also callable as `g8.api.call("bulk_get_contacts_contacts_bulk_get_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Full records for up to 100 contacts in ONE request. Writes nothing.
+
+Use this instead of looping `GET /contacts/{contact_id}`: `GET /contacts`
+returns 17 fields per contact, and the loop spends one rate-limit slot per
+contact to get the other fields. Each item is exactly what the per-contact
+route returns, through the same access check. A contact that does not exist
+or is outside the key's scope comes back `found: false`, rather than failing
+the batch. POST only because the ids are a body; it is tiered as a read.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ContactBulkGetRequest` | yes | Request body; fields below. |
+
+Body fields (`ContactBulkGetRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.contact_ids` | `Array<integer>` | yes | Up to 100 contact ids, the ids `GET /contacts` returns. Duplicates are read once; the response keeps first-seen order. min items 1, max items 100 |
+| `body.include_custom_fields` | `boolean` | no | When true, each found contact includes a `custom_fields` object keyed by column slug, as `GET /contacts/{contact_id}?include_custom_fields=true` does. default `false` |
+
+**Returns** `ApiResponse_ContactBulkGetResponse_`: the envelope `{ data: ContactBulkGetResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ContactBulkGetResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<ContactBulkGetItem>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.contacts.bulkGetContacts({ body: { contact_ids: [123] } });
+```
+
+---
+
+<a id="op-bulkupdatecontacts"></a>
+
+### `g8.api.contacts.bulkUpdateContacts(input)`
+
+**Bulk Update Contacts**
+
+- HTTP: `POST /api/v1/contacts/bulk-update`
+- operationId: `bulk_update_contacts_contacts_bulk_update_post` (also callable as `g8.api.call("bulk_update_contacts_contacts_bulk_update_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Apply a DIFFERENT change to each of many contacts.
+
+The whole target set is authorised before the first write, so a batch
+containing one contact the key cannot write is refused outright rather
+than half-applied.
+
+After that preflight, individual failures are REPORTED, not fatal: read
+`updated`, `failed` and the per-contact `errors` rather than the HTTP
+status.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `Array<Record<string, unknown>>` | yes | Request body; fields below. |
+
+**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.contacts.bulkUpdateContacts({ body: [{}] });
+```
+
+---
+
+<a id="op-cancelrecordworkflowexecution"></a>
+
+### `g8.api.contacts.cancelRecordWorkflowExecution(input)`
+
+**Cancel Record Workflow Execution**
+
+- HTTP: `POST /api/v1/contacts/workflow-executions/{execution_id}/cancel`
+- operationId: `cancel_record_workflow_execution_contacts_workflow_executions__execution_id__cancel_post` (also callable as `g8.api.call("cancel_record_workflow_execution_contacts_workflow_executions__execution_id__cancel_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `contacts:delete`
+
+Cancel a row workflow. Steps already run are not undone.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.execution_id` | `string` | yes | Workflow execution 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.contacts.cancelRecordWorkflowExecution({ path: { execution_id: "id" } });
+```
+
+---
+
+<a id="op-createcontactcolumn"></a>
+
+### `g8.api.contacts.createContactColumn(input)`
+
+**Create Contact Column**
+
+- HTTP: `POST /api/v1/contacts/columns/create`
+- operationId: `create_contact_column_contacts_columns_create_post` (also callable as `g8.api.call("create_contact_column_contacts_columns_create_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+- ★ Hand-written: [`g8.contacts.createColumn()`](../sdk-clients.md#g8-contacts-createcolumn)
+
+Create a custom contact 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` | `CreateContactColumnRequest` | yes | Request body; fields below. |
+
+Body fields (`CreateContactColumnRequest`):
+
+| 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. 'Lead Score') |
+| `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_CreateContactColumnResponse_`: the envelope `{ data: CreateContactColumnResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CreateContactColumnResponse` 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.contacts.createContactColumn({ body: { created_by: "jane@acme.com", title: "Example" } });
+```
+
+---
+
+<a id="op-createcontacttag"></a>
+
+### `g8.api.contacts.createContactTag(input)`
+
+**Create Contact Tag**
+
+- HTTP: `POST /api/v1/contacts/tags`
+- operationId: `create_contact_tag_contacts_tags_post` (also callable as `g8.api.call("create_contact_tag_contacts_tags_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Create a tag definition.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ContactTagCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`ContactTagCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes | min length 1, max length 50 |
+| `body.color` | `string \| null` | no | Six-digit hex colour, e.g. `#4F46E5`. pattern `^#[0-9A-Fa-f]{6}$` |
+| `body.description` | `string \| null` | no | max length 200 |
+
+**Returns** `ApiResponse_ContactTag_`: the envelope `{ data: ContactTag, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ContactTag` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `archived` | `boolean \| null` | no |  |
+| `color` | `string \| null` | no |  |
+| `contact_count` | `integer \| null` | no | Contacts currently carrying the tag. |
+| `description` | `string \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.contacts.createContactTag({ body: { name: "Example" } });
+```
+
+---
+
+<a id="op-createcontacts"></a>
+
+### `g8.api.contacts.createContacts(input)`
+
+**Create Contacts**
+
+- HTTP: `POST /api/v1/contacts`
+- operationId: `create_contacts_contacts_post` (also callable as `g8.api.call("create_contacts_contacts_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+- ★ Hand-written: [`g8.contacts.create()`](../sdk-clients.md#g8-contacts-create)
+
+Create a contact, optionally adding it to a list.
+
+The contact is created independent of any list. When ``list_id`` is
+provided, the contact is added to that list AFTER it is created; when
+omitted, the contact is created standalone. A company is resolved and
+attached from ``company_domain`` when supplied.
+
+Duplicate handling: when the submitted ``work_email`` / ``linkedin_url``
+(or the deterministic identity hash) already matches an existing contact,
+the handler does NOT overwrite it — it writes nothing and skips the
+``list_id`` linkage. This endpoint mirrors the in-app create and responds
+``409 Conflict`` with the matched ``contact_id`` and a ``field_diff`` under
+``detail`` (rather than a misleading ``201`` success). The 409 is NOT
+cached under the ``Idempotency-Key``, so a later create of the same
+identity is re-evaluated fresh. The 409 ``detail`` also carries ``hint``,
+``upsert`` and ``update``, which name the idempotent create-or-update route
+``PUT /contacts/assert`` and the ``PATCH /contacts/{id}`` for the matched
+contact. To create-or-update in one call, use ``PUT /contacts/assert``.
+
+Supports optional Stripe-style idempotency via the ``Idempotency-Key``
+header — a safe retry of the same key replays the first SUCCESSFUL response
+(flagged ``Idempotent-Replay: true``) rather than creating duplicate
+contacts.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ContactCreateRequest` | yes | Request body; fields below. |
+| `headers.Idempotency-Key` | `string \| null` | no | Optional. Retrying a create with the same key returns the first response instead of creating a duplicate (cached 24h). Omit for the existing non-idempotent behavior. |
+
+Body fields (`ContactCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.city` | `string \| null` | no | City |
+| `body.company_domain` | `string \| null` | no | Company domain for matching |
+| `body.company_id` | `integer \| null` | no | Existing company id (mashup_companies.id) to attach |
+| `body.country` | `string \| null` | no | Country |
+| `body.create_missing_fields` | `boolean` | no | When true, custom_fields keys that match no existing column are created as NEW custom columns (list-scoped when list_id is set) and then written. default `false` |
+| `body.custom_fields` | `Record<string, string \| null> \| null` | no | Custom column values keyed by the column's display title (e.g. 'Followup 1'), its slug (e.g. 'udo_followup_1_ab12cd34'), or a case/space variant of the title. Keys matching no existing column are reported in the response's `custom_fields.ignored` unless `create_missing_fields` is true. |
+| `body.direct_phone` | `string \| null` | no | Direct phone number |
+| `body.first_name` | `string \| null` | no | Contact first name |
+| `body.job_department` | `string \| null` | no | Department |
+| `body.job_title` | `string \| null` | no | Job title |
+| `body.last_name` | `string \| null` | no | Contact last name |
+| `body.linkedin_url` | `string \| null` | no | LinkedIn profile URL |
+| `body.list_id` | `integer \| null` | no | Optional target list ID. When provided, the contact is added to this list after it is created; omit to create the contact without a list. |
+| `body.mobile_phone` | `string \| null` | no | Mobile phone number |
+| `body.personal_emails` | `string \| null` | no | Personal email addresses |
+| `body.seniority_level` | `string \| null` | no | Seniority level |
+| `body.state` | `string \| null` | no | State/Province |
+| `body.work_email` | `string \| null` | no | Work email address |
+
+**Returns** `ApiResponse_ContactCreateResponse_`: the envelope `{ data: ContactCreateResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ContactCreateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `count` | `integer` | yes |  |
+| `status` | `string` | yes |  |
+| `company_attached` | `boolean` | no | default `false` |
+| `contact_id` | `integer \| null` | no |  |
+| `custom_fields` | `CustomFieldWriteReport` | no |  |
+| `merged` | `boolean` | no | default `false` |
+| `validation_errors` | `Array<string>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.contacts.createContacts({ body: {} });
+```
+
+---
+
+<a id="op-deciderecordworkflowexecution"></a>
+
+### `g8.api.contacts.decideRecordWorkflowExecution(input)`
+
+**Decide Record Workflow Execution**
+
+- HTTP: `POST /api/v1/contacts/workflow-executions/{execution_id}/approve`
+- operationId: `decide_record_workflow_execution_contacts_workflow_executions__execution_id__approve_post` (also callable as `g8.api.call("decide_record_workflow_execution_contacts_workflow_executions__execution_id__approve_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Approve or reject a row workflow paused at an approval step.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.execution_id` | `string` | yes | Workflow execution id. |
+| `body` | `ApproveExecutionRequest` | yes | Request body; fields below. |
+
+Body fields (`ApproveExecutionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.decision` | `"approve" \| "reject"` | yes | Approve or reject the paused step. |
+| `body.reason` | `string \| null` | no | Recorded with a rejection. |
+
+**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.contacts.decideRecordWorkflowExecution({ path: { execution_id: "id" }, body: { decision: "approve" } });
+```
+
+---
+
+<a id="op-deletecontact"></a>
+
+### `g8.api.contacts.deleteContact(input)`
+
+**Delete Contact**
+
+- HTTP: `DELETE /api/v1/contacts/{contact_id}`
+- operationId: `delete_contact_contacts__contact_id__delete` (also callable as `g8.api.call("delete_contact_contacts__contact_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `contacts:delete`
+- ★ Hand-written: [`g8.contacts.delete()`](../sdk-clients.md#g8-contacts-delete)
+
+Soft-delete a contact.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact 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.contacts.deleteContact({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-deletecontactcolumn"></a>
+
+### `g8.api.contacts.deleteContactColumn(input)`
+
+**Delete Contact Column**
+
+- HTTP: `DELETE /api/v1/contacts/columns/{column_id}`
+- operationId: `delete_contact_column_contacts_columns__column_id__delete` (also callable as `g8.api.call("delete_contact_column_contacts_columns__column_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `contacts:delete`
+
+Soft-delete a custom contact 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.contacts.deleteContactColumn({ path: { column_id: 123 } });
+```
+
+---
+
+<a id="op-deletecontactdocument"></a>
+
+### `g8.api.contacts.deleteContactDocument(input)`
+
+**Delete Contact Document**
+
+- HTTP: `DELETE /api/v1/contacts/{contact_id}/documents/{document_id}`
+- operationId: `delete_contact_document_contacts__contact_id__documents__document_id__delete` (also callable as `g8.api.call("delete_contact_document_contacts__contact_id__documents__document_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `contacts:delete`
+
+Delete one generated document PERMANENTLY.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact 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.contacts.deleteContactDocument({ path: { contact_id: 123, document_id: "id" } });
+```
+
+---
+
+<a id="op-deletecontacttag"></a>
+
+### `g8.api.contacts.deleteContactTag(input)`
+
+**Delete Contact Tag**
+
+- HTTP: `DELETE /api/v1/contacts/tags/{tag_id}`
+- operationId: `delete_contact_tag_contacts_tags__tag_id__delete` (also callable as `g8.api.call("delete_contact_tag_contacts_tags__tag_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `contacts:delete`
+
+Delete a tag, optionally reassigning its contacts first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.tag_id` | `string` | yes | Tag id. |
+| `query.reassign_to` | `string \| null` | no | Move every assignment to this tag before deleting. Omit to drop the assignments with the tag. |
+
+**Returns** `ApiResponse_ContactTagWriteResult_`: the envelope `{ data: ContactTagWriteResult, ... }`. `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.contacts.deleteContactTag({ path: { tag_id: "id" } });
+```
+
+---
+
+<a id="op-fetchcontacts"></a>
+
+### `g8.api.contacts.fetchContacts(input)`
+
+**Fetch Contacts**
+
+- HTTP: `POST /api/v1/contacts/fetch`
+- operationId: `fetch_contacts_contacts_fetch_post` (also callable as `g8.api.call("fetch_contacts_contacts_fetch_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Page through contacts, projecting only the columns you name.
+
+A POST because the filter is a body, not because it writes: this reads and
+mutates nothing, and is tiered as a read so a read-only key can call it.
+
+Prefer this over `GET /contacts` when you want a narrow column set -
+naming the columns lets the planner drop joins the full row forces.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `FetchContactsRequest` | yes | Request body; fields below. |
+
+Body fields (`FetchContactsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.filter` | `string \| null` | no | Serialized per-column filter JSON. Omit for no filter. |
+| `body.limit` | `integer` | no | Records per page. default `50`, min 1, max 1000 |
+| `body.mapping_columns` | `Array<string> \| null` | no | Columns to return. Omit for every column. |
+| `body.page` | `integer` | no | Page number (1-indexed). default `1`, min 1 |
+
+**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.contacts.fetchContacts({ body: {} });
+```
+
+---
+
+<a id="op-generateallcontactdocuments"></a>
+
+### `g8.api.contacts.generateAllContactDocuments(input)`
+
+**Generate All Contact Documents**
+
+- HTTP: `POST /api/v1/contacts/{contact_id}/documents/generate-all`
+- operationId: `generate_all_contact_documents_contacts__contact_id__documents_generate_all_post` (also callable as `g8.api.call("generate_all_contact_documents_contacts__contact_id__documents_generate_all_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Generate the full document set for this contact. SPENDS CREDITS.
+
+Enqueues the work and returns immediately; poll
+`/contacts/{contact_id}/documents/generation-status` for progress. Each
+document is a model call, so calling this repeatedly on the same contact
+spends repeatedly.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact primary 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
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.contacts.generateAllContactDocuments({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-generatecontactdocument"></a>
+
+### `g8.api.contacts.generateContactDocument(input)`
+
+**Generate Contact Document**
+
+- HTTP: `POST /api/v1/contacts/{contact_id}/documents/types/{doc_type}/generate`
+- operationId: `generate_contact_document_contacts__contact_id__documents_types__doc_type__generate_post` (also callable as `g8.api.call("generate_contact_document_contacts__contact_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. Unknown types are a 400.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact 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.contacts.generateContactDocument({ path: { contact_id: 123, doc_type: "example" } });
+```
+
+---
+
+<a id="op-getactivityfeed"></a>
+
+### `g8.api.contacts.getActivityFeed(input)`
+
+**Get Activity Feed**
+
+- HTTP: `GET /api/v1/activity-feed`
+- operationId: `get_activity_feed_activity_feed_get` (also callable as `g8.api.call("get_activity_feed_activity_feed_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+One timeline over everything that happened to a record.
+
+Replaces four separate per-type reads. `entity_type` decides which record
+scope authorises the call, and all four are resolved from the CALLING
+KEY'S OWN credential scopes - so a key without `deals:read` resolves the
+deal scope to nothing and cannot read a deal's feed through this path,
+even though the key gate on the route is `contacts:read`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.entity_type` | `string` | yes | contact \| company \| deal \| team_member |
+| `query.entity_id` | `string` | yes | Id of that record. |
+| `query.types` | `string \| null` | no | Comma-separated subset of task,note,email,call,meeting,sms,chat,stage_change,quote,record_change,deal. Omit for all. |
+| `query.source` | `string` | no | manual \| crm \| system \| dialer \| automation \| api \| all default `"all"` |
+| `query.since` | `string \| null` | no | ISO 8601 cursor; returns events at or after it. |
+| `query.limit` | `integer` | no | default `50` |
+
+**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.contacts.getActivityFeed({ query: { entity_type: "example", entity_id: "id" } });
+```
+
+---
+
+<a id="op-getcontact"></a>
+
+### `g8.api.contacts.getContact(input)`
+
+**Get Contact**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}`
+- operationId: `get_contact_contacts__contact_id__get` (also callable as `g8.api.call("get_contact_contacts__contact_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+- ★ Hand-written: [`g8.contacts.get()`](../sdk-clients.md#g8-contacts-get)
+
+Get detailed information about a single contact.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact 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_ContactResponse_`: the envelope `{ data: ContactResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ContactResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `integer` | yes |  |
+| `about` | `string \| null` | no |  |
+| `city` | `string \| null` | no |  |
+| `company` | `ContactCompanySummary \| null` | no |  |
+| `confidence_score` | `number \| null` | no |  |
+| `country` | `string \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `custom_fields` | `Record<string, string \| null> \| null` | no |  |
+| `direct_phone` | `string \| null` | no |  |
+| `facebook_url` | `string \| null` | no |  |
+| `first_name` | `string \| null` | no |  |
+| `full_name` | `string \| null` | no |  |
+| `job_department` | `string \| null` | no |  |
+| `job_title` | `string \| null` | no |  |
+| `last_name` | `string \| null` | no |  |
+| `linkedin_url` | `string \| null` | no |  |
+| `meta_data` | `Record<string, unknown> \| null` | no |  |
+| `mobile_phone` | `string \| null` | no |  |
+| `personal_emails` | `unknown \| null` | no |  |
+| `seniority_level` | `string \| null` | no |  |
+| `state` | `string \| null` | no |  |
+| `twitter_url` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+| `work_email` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.contacts.getContact({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getcontactanalysis"></a>
+
+### `g8.api.contacts.getContactAnalysis(input)`
+
+**Get Contact Analysis**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/analysis`
+- operationId: `get_contact_analysis_contacts__contact_id__analysis_get` (also callable as `g8.api.call("get_contact_analysis_contacts__contact_id__analysis_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Engagement trend over 7/30/60 days and the strategy it suggests.
+
+Rule-based over recorded events, cached briefly. No model call, no spend.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact 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.contacts.getContactAnalysis({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getcontactdashboard"></a>
+
+### `g8.api.contacts.getContactDashboard(input)`
+
+**Get Contact Dashboard**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/dashboard`
+- operationId: `get_contact_dashboard_contacts__contact_id__dashboard_get` (also callable as `g8.api.call("get_contact_dashboard_contacts__contact_id__dashboard_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Everything the contact detail view shows, in one call.
+
+Open-shaped: this is a composed view whose panels grow with the product.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact primary 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.contacts.getContactDashboard({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getcontactdashboardstats"></a>
+
+### `g8.api.contacts.getContactDashboardStats(input?)`
+
+**Get Contact Dashboard Stats**
+
+- HTTP: `GET /api/v1/contacts/dashboard-stats`
+- operationId: `get_contact_dashboard_stats_contacts_dashboard_stats_get` (also callable as `g8.api.call("get_contact_dashboard_stats_contacts_dashboard_stats_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Counts and distributions across the contacts this key can see.
+
+Scoped, not org-wide: a key narrowed away from contacts gets its own
+narrower totals rather than the organisation's.
+
+**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.contacts.getContactDashboardStats();
+```
+
+---
+
+<a id="op-getcontactdetail"></a>
+
+### `g8.api.contacts.getContactDetail(input)`
+
+**Get Contact Detail**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/detail`
+- operationId: `get_contact_detail_contacts__contact_id__detail_get` (also callable as `g8.api.call("get_contact_detail_contacts__contact_id__detail_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+The composed contact record the app's detail page renders.
+
+404 when the contact does not exist OR is outside the key's scope - the
+two are deliberately indistinguishable.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact 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.contacts.getContactDetail({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getcontactdocument"></a>
+
+### `g8.api.contacts.getContactDocument(input)`
+
+**Get Contact Document**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/documents/types/{doc_type}`
+- operationId: `get_contact_document_contacts__contact_id__documents_types__doc_type__get` (also callable as `g8.api.call("get_contact_document_contacts__contact_id__documents_types__doc_type__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+The current document of one type for this contact.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact id. |
+| `path.doc_type` | `string` | yes | Document type, e.g. `contact_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
+const result = await g8.api.contacts.getContactDocument({ path: { contact_id: 123, doc_type: "example" } });
+```
+
+---
+
+<a id="op-getcontactengagementsummary"></a>
+
+### `g8.api.contacts.getContactEngagementSummary(input)`
+
+**Get Contact Engagement Summary**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/engagement-summary`
+- operationId: `get_contact_engagement_summary_contacts__contact_id__engagement_summary_get` (also callable as `g8.api.call("get_contact_engagement_summary_contacts__contact_id__engagement_summary_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+How much this contact has engaged: emails, calls, meetings, visits.
+
+Gated on `id_kind="pk"` because the handler counts against
+`mashup_contacts.id`. A gate resolving any other namespace would authorise
+a different row than it serves.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact primary 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.contacts.getContactEngagementSummary({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getcontactformfields"></a>
+
+### `g8.api.contacts.getContactFormFields(input?)`
+
+**Get Contact Form Fields**
+
+- HTTP: `GET /api/v1/contacts/form-fields`
+- operationId: `get_contact_form_fields_contacts_form_fields_get` (also callable as `g8.api.call("get_contact_form_fields_contacts_form_fields_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Fields grouped the way the contact form presents them.
+
+Same underlying columns as the schema reads above, arranged into labelled
+groups with a `required` flag - what to render, rather than what exists.
+
+**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.contacts.getContactFormFields();
+```
+
+---
+
+<a id="op-getcontactgenerationstatus"></a>
+
+### `g8.api.contacts.getContactGenerationStatus(input)`
+
+**Get Contact Generation Status**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/documents/generation-status`
+- operationId: `get_contact_generation_status_contacts__contact_id__documents_generation_status_get` (also callable as `g8.api.call("get_contact_generation_status_contacts__contact_id__documents_generation_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Progress of this contact's document generation. Reads only.
+
+Named for the app route it proxies, which means the path contains
+`generate` - the tier heuristic reads that as an active GET and would
+publish a status poll as a credit spend. It is corrected by an explicit
+entry in `build_scope_policy.py::READ_ONLY_ACTIVE_GET_ROUTES` rather than
+by spelling the path around the matcher.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact primary 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.contacts.getContactGenerationStatus({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getcontactlists"></a>
+
+### `g8.api.contacts.getContactLists(input)`
+
+**Get Contact Lists**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/lists`
+- operationId: `get_contact_lists_contacts__contact_id__lists_get` (also callable as `g8.api.call("get_contact_lists_contacts__contact_id__lists_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+The lists this contact belongs to that the key can see.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact primary key (`mashup_contacts.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.contacts.getContactLists({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getcontactmeetings"></a>
+
+### `g8.api.contacts.getContactMeetings(input)`
+
+**Get Contact Meetings**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/meetings`
+- operationId: `get_contact_meetings_contacts__contact_id__meetings_get` (also callable as `g8.api.call("get_contact_meetings_contacts__contact_id__meetings_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Meetings booked with this contact, past and upcoming.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact 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.contacts.getContactMeetings({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getcontactnextbeststep"></a>
+
+### `g8.api.contacts.getContactNextBestStep(input)`
+
+**Get Contact Next Best Step**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/next-best-step`
+- operationId: `get_contact_next_best_step_contacts__contact_id__next_best_step_get` (also callable as `g8.api.call("get_contact_next_best_step_contacts__contact_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 contact, 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 contact's engagement state, so
+activity on the record invalidates it. Tiered `billable` for that reason
+rather than as an ordinary read - polling it per contact is real spend.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact primary 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
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.contacts.getContactNextBestStep({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getcontactprofilepictures"></a>
+
+### `g8.api.contacts.getContactProfilePictures(input)`
+
+**Get Contact Profile Pictures**
+
+- HTTP: `POST /api/v1/contacts/profile-pictures`
+- operationId: `get_contact_profile_pictures_contacts_profile_pictures_post` (also callable as `g8.api.call("get_contact_profile_pictures_contacts_profile_pictures_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Resolve profile photos for a batch of LinkedIn URLs.
+
+A missing key in the result means "no allow-listed photo for that URL",
+not "the lookup failed" - roughly half of contacts have one. Soft-fails to
+an empty map rather than erroring, so it is safe on a render path.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ProfilePicturesRequest` | yes | Request body; fields below. |
+
+Body fields (`ProfilePicturesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.linkedin_urls` | `Array<string>` | no | LinkedIn profile URLs (deduplicated, max 200). max items 200 |
+
+**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.contacts.getContactProfilePictures({ body: {} });
+```
+
+---
+
+<a id="op-getcontactrowdetail"></a>
+
+### `g8.api.contacts.getContactRowDetail(input)`
+
+**Get Contact Row Detail**
+
+- HTTP: `GET /api/v1/contacts/row-detail/{record_id}`
+- operationId: `get_contact_row_detail_contacts_row_detail__record_id__get` (also callable as `g8.api.call("get_contact_row_detail_contacts_row_detail__record_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Which workflows have run against this record, and what they produced.
+
+Carries the execution timeline, each run's outputs, and the actions
+currently available on the row. The workflow-permission gate is the app's
+own, including its soak behaviour - while the enforcement flag is off a
+caller without `workflows:read` is logged and allowed, because that
+permission is not yet held by every role.
+
+Under `/contacts/` because the record scope it enforces is the CONTACT
+one, but `record_id` is whatever the list holds: a companies list reads
+company rows through this path.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.record_id` | `integer` | yes | Record primary key. |
+| `query.list_id` | `integer` | yes | Required: the list the record is read through. |
+
+**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.contacts.getContactRowDetail({ path: { record_id: 123 }, query: { list_id: 123 } });
+```
+
+---
+
+<a id="op-getcontactsequences"></a>
+
+### `g8.api.contacts.getContactSequences(input)`
+
+**Get Contact Sequences**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/sequences`
+- operationId: `get_contact_sequences_contacts__contact_id__sequences_get` (also callable as `g8.api.call("get_contact_sequences_contacts__contact_id__sequences_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Every sequence this contact is or was enrolled in, with its step and state.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact 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.contacts.getContactSequences({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getcontactsignals"></a>
+
+### `g8.api.contacts.getContactSignals(input)`
+
+**Get Contact Signals**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/signals`
+- operationId: `get_contact_signals_contacts__contact_id__signals_get` (also callable as `g8.api.call("get_contact_signals_contacts__contact_id__signals_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Buying signals recorded against this contact.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact 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.contacts.getContactSignals({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getcontactsitesvisited"></a>
+
+### `g8.api.contacts.getContactSitesVisited(input)`
+
+**Get Contact Sites Visited**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/sites-visited`
+- operationId: `get_contact_sites_visited_contacts__contact_id__sites_visited_get` (also callable as `g8.api.call("get_contact_sites_visited_contacts__contact_id__sites_visited_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Pages this contact visited on your site.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact primary 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.contacts.getContactSitesVisited({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getcontacttagids"></a>
+
+### `g8.api.contacts.getContactTagIds(input)`
+
+**Get Contact Tag Ids**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/tags`
+- operationId: `get_contact_tag_ids_contacts__contact_id__tags_get` (also callable as `g8.api.call("get_contact_tag_ids_contacts__contact_id__tags_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+The ids of the tags on this contact. Resolve names with `GET /contacts/tags`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact 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.contacts.getContactTagIds({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getduplicatesettings"></a>
+
+### `g8.api.contacts.getDuplicateSettings(input?)`
+
+**Get Duplicate Settings**
+
+- HTTP: `GET /api/v1/duplicates/settings`
+- operationId: `get_duplicate_settings_duplicates_settings_get` (also callable as `g8.api.call("get_duplicate_settings_duplicates_settings_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+The org's merge rules: field winners, auto-merge, detection-rule overrides.
+
+Admin-only in the app (manage scope on every governed object); the same
+check runs here, inside the handler.
+
+**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.contacts.getDuplicateSettings();
+```
+
+---
+
+<a id="op-getrecordcolumnvalues"></a>
+
+### `g8.api.contacts.getRecordColumnValues(input)`
+
+**Get Record Column Values**
+
+- HTTP: `POST /api/v1/contacts/column-values`
+- operationId: `get_record_column_values_contacts_column_values_post` (also callable as `g8.api.call("get_record_column_values_contacts_column_values_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Every column value for one row, resolved through a list.
+
+The list is required, not optional: it decides whether `record_id` names a
+contact or a company and which list-scoped custom columns apply. Reading
+the same id through two different lists can legitimately return different
+columns.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `RecordColumnValuesRequest` | yes | Request body; fields below. |
+
+Body fields (`RecordColumnValuesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.list_id` | `integer` | yes | List the record is read through. |
+| `body.record_id` | `integer` | yes | Record primary 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.contacts.getRecordColumnValues({ body: { list_id: 123, record_id: 123 } });
+```
+
+---
+
+<a id="op-listbasecolumns"></a>
+
+### `g8.api.contacts.listBaseColumns(input)`
+
+**List Base Columns**
+
+- HTTP: `GET /api/v1/contacts/base-columns`
+- operationId: `list_base_columns_contacts_base_columns_get` (also callable as `g8.api.call("list_base_columns_contacts_base_columns_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+The real DATABASE columns behind a list.
+
+Excludes the composite and enrichment columns the grid displays, so what
+comes back is what can actually be written to and filtered on.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.list_id` | `integer` | yes | Required: the list decides which base columns exist. |
+
+**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.contacts.listBaseColumns({ query: { list_id: 123 } });
+```
+
+---
+
+<a id="op-listcolumnnames"></a>
+
+### `g8.api.contacts.listColumnNames(input?)`
+
+**List Column Names**
+
+- HTTP: `GET /api/v1/contacts/column-names`
+- operationId: `list_column_names_contacts_column_names_get` (also callable as `g8.api.call("list_column_names_contacts_column_names_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Column names only, as a flat list of strings.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.list_id` | `integer \| null` | no | Include this list's own columns. |
+
+**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.contacts.listColumnNames();
+```
+
+---
+
+<a id="op-listcontactcolumndefinitions"></a>
+
+### `g8.api.contacts.listContactColumnDefinitions(input?)`
+
+**List Contact Column Definitions**
+
+- HTTP: `GET /api/v1/contacts/column-definitions`
+- operationId: `list_contact_column_definitions_contacts_column_definitions_get` (also callable as `g8.api.call("list_contact_column_definitions_contacts_column_definitions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Every column the grid can show, with its type and display name.
+
+The richest of the schema reads here: it carries base columns, custom
+columns and enrichment columns together. `GET /contacts/columns` returns
+the custom columns alone.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.list_id` | `integer \| null` | no | Include the columns specific to this list. The list also decides whether contact or company columns are returned - a companies list returns company columns from this contacts path. |
+
+**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.contacts.listContactColumnDefinitions();
+```
+
+---
+
+<a id="op-listcontactcolumns"></a>
+
+### `g8.api.contacts.listContactColumns(input?)`
+
+**List Contact Columns**
+
+- HTTP: `GET /api/v1/contacts/columns`
+- operationId: `list_contact_columns_contacts_columns_get` (also callable as `g8.api.call("list_contact_columns_contacts_columns_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+- ★ Hand-written: [`g8.contacts.listColumns()`](../sdk-clients.md#g8-contacts-listcolumns)
+
+List custom contact 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.contacts.listContactColumns();
+```
+
+---
+
+<a id="op-listcontactdocuments"></a>
+
+### `g8.api.contacts.listContactDocuments(input)`
+
+**List Contact Documents**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/documents`
+- operationId: `list_contact_documents_contacts__contact_id__documents_get` (also callable as `g8.api.call("list_contact_documents_contacts__contact_id__documents_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+The documents graph8 has generated about this contact.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact 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.contacts.listContactDocuments({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-listcontacttags"></a>
+
+### `g8.api.contacts.listContactTags(input?)`
+
+**List Contact Tags**
+
+- HTTP: `GET /api/v1/contacts/tags`
+- operationId: `list_contact_tags_contacts_tags_get` (also callable as `g8.api.call("list_contact_tags_contacts_tags_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Org tag definitions with per-tag contact counts.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.include_archived` | `boolean` | no | Include archived tags. default `false` |
+
+**Returns** `ApiResponse_ContactTagListResponse_`: the envelope `{ data: ContactTagListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ContactTagListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `tags` | `Array<ContactTag>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.contacts.listContactTags();
+```
+
+---
+
+<a id="op-listcontacts"></a>
+
+### `g8.api.contacts.listContacts(input?)`
+
+**List Contacts**
+
+- HTTP: `GET /api/v1/contacts`
+- operationId: `list_contacts_contacts_get` (also callable as `g8.api.call("list_contacts_contacts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+- ★ Hand-written: [`g8.contacts.list()`](../sdk-clients.md#g8-contacts-list), [`g8.contacts.listDetailed()`](../sdk-clients.md#g8-contacts-listdetailed)
+
+List contacts 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.email` | `string \| null` | no | Filter by work email (exact match) |
+| `query.list_id` | `integer \| null` | no | Filter by list ID |
+| `query.name` | `string \| null` | no | Filter by first or last name (partial match) |
+| `query.job_title` | `string \| null` | no | Filter by job title (partial match) |
+| `query.seniority_level` | `string \| null` | no | Filter by seniority level (exact match) |
+| `query.company_name` | `string \| null` | no | Filter by company name (partial match) |
+| `query.company_id` | `integer \| null` | no | Filter by company ID |
+| `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.job_department` | `string \| null` | no | Filter by job department (partial match) |
+| `query.industry` | `string \| null` | no | Filter by company industry (partial match) |
+| `query.include_custom_fields` | `boolean` | no | When true, each contact 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_ContactListItem__`: the envelope `{ data: Array<ContactListItem>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ContactListItem` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `city` | `string \| null` | no |  |
+| `company_id` | `integer \| null` | no |  |
+| `country` | `string \| null` | no |  |
+| `custom_fields` | `Record<string, string \| null> \| null` | no |  |
+| `direct_phone` | `string \| null` | no |  |
+| `first_name` | `string \| null` | no |  |
+| `id` | `integer \| null` | no |  |
+| `job_department` | `string \| null` | no |  |
+| `job_title` | `string \| null` | no |  |
+| `last_name` | `string \| null` | no |  |
+| `linkedin_url` | `string \| null` | no |  |
+| `mobile_phone` | `string \| null` | no |  |
+| `owner_id` | `string \| null` | no |  |
+| `owner_name` | `string \| null` | no |  |
+| `seniority_level` | `string \| null` | no |  |
+| `state` | `string \| null` | no |  |
+| `work_email` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.contacts.listContacts();
+```
+
+---
+
+<a id="op-listcustomcolumndefinitions"></a>
+
+### `g8.api.contacts.listCustomColumnDefinitions(input?)`
+
+**List Custom Column Definitions**
+
+- HTTP: `GET /api/v1/contacts/custom-column-definitions`
+- operationId: `list_custom_column_definitions_contacts_custom_column_definitions_get` (also callable as `g8.api.call("list_custom_column_definitions_contacts_custom_column_definitions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+The org's custom columns as `{column_id, name}` pairs.
+
+The flat form: enough to build a field picker, and the source of the ids
+other calls accept.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.entity_type` | `string` | no | `contact` or `company`. Anything else is refused. default `"contact"` |
+
+**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.contacts.listCustomColumnDefinitions();
+```
+
+---
+
+<a id="op-listduplicatedetectionruns"></a>
+
+### `g8.api.contacts.listDuplicateDetectionRuns(input?)`
+
+**List Duplicate Detection Runs**
+
+- HTTP: `GET /api/v1/duplicates/detection/runs`
+- operationId: `list_duplicate_detection_runs_duplicates_detection_runs_get` (also callable as `g8.api.call("list_duplicate_detection_runs_duplicates_detection_runs_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Recent duplicate-detection runs - when the last check ran and what it found.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.entity_type` | `"contact" \| "company" \| "deal" \| null` | no | Only runs for this record type. |
+| `query.limit` | `integer` | no | How many runs, newest first. default `10` |
+
+**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.contacts.listDuplicateDetectionRuns();
+```
+
+---
+
+<a id="op-listrecordworkflowexecutions"></a>
+
+### `g8.api.contacts.listRecordWorkflowExecutions(input)`
+
+**List Record Workflow Executions**
+
+- HTTP: `GET /api/v1/contacts/workflow-executions`
+- operationId: `list_record_workflow_executions_contacts_workflow_executions_get` (also callable as `g8.api.call("list_record_workflow_executions_contacts_workflow_executions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Workflow runs for one row of a list, newest first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.list_id` | `integer` | yes | The list the row belongs to. |
+| `query.record_id` | `integer` | yes | The row (contact) id. |
+| `query.workflow_id` | `string \| null` | no | Only runs of this workflow. |
+| `query.status` | `string \| null` | no | Only this status. |
+| `query.include_events` | `boolean` | no | Include each run's step events. default `false` |
+
+**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.contacts.listRecordWorkflowExecutions({ query: { list_id: 123, record_id: 123 } });
+```
+
+---
+
+<a id="op-listsearchablefields"></a>
+
+### `g8.api.contacts.listSearchableFields(input?)`
+
+**List Searchable Fields**
+
+- HTTP: `GET /api/v1/contacts/searchable-fields`
+- operationId: `list_searchable_fields_contacts_searchable_fields_get` (also callable as `g8.api.call("list_searchable_fields_contacts_searchable_fields_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Which fields can be searched, and what each one COSTS.
+
+Every entry carries a `tier` derived from the org's real indexes -
+`fast`, `text_search` or `full_scan` - plus the operators that column's
+live type supports. Index coverage is per-org, so this is the only honest
+way to know a custom-column search is a full table scan before running it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.entity_type` | `string` | no | `contact` or `company`. Anything else is refused. default `"contact"` |
+
+**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.contacts.listSearchableFields();
+```
+
+---
+
+<a id="op-mergecontact"></a>
+
+### `g8.api.contacts.mergeContact(input)`
+
+**Merge Contact**
+
+- HTTP: `POST /api/v1/contacts/{contact_id}/merge`
+- operationId: `merge_contact_contacts__contact_id__merge_post` (also callable as `g8.api.call("merge_contact_contacts__contact_id__merge_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `contacts:delete`
+
+Merge `secondary_id` INTO this contact. THE SECONDARY STOPS EXISTING.
+
+Both contacts must be writable by the key; the handler checks both.
+Undo is one merge at a time via `POST /duplicates/undo-merge/{id}`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | The contact 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.contacts.mergeContact({ path: { contact_id: 123 }, body: { secondary_id: 123 } });
+```
+
+---
+
+<a id="op-mergecontacttags"></a>
+
+### `g8.api.contacts.mergeContactTags(input)`
+
+**Merge Contact Tags**
+
+- HTTP: `POST /api/v1/contacts/tags/merge`
+- operationId: `merge_contact_tags_contacts_tags_merge_post` (also callable as `g8.api.call("merge_contact_tags_contacts_tags_merge_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Fold one or more tags into a target. The sources are removed.
+
+No shadowing risk against `/{tag_id}`: that path has no POST, so the
+literal `merge` segment cannot be read as a tag id whatever the order.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ContactTagMergeRequest` | yes | Request body; fields below. |
+
+Body fields (`ContactTagMergeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.source_tag_ids` | `Array<string>` | yes | Tags to fold in. Removed on success. min items 1 |
+| `body.target_tag_id` | `string` | yes | Tag that survives and absorbs the assignments. |
+
+**Returns** `ApiResponse_ContactTagWriteResult_`: the envelope `{ data: ContactTagWriteResult, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.contacts.mergeContactTags({ body: { source_tag_ids: ["id"], target_tag_id: "id" } });
+```
+
+---
+
+<a id="op-mergefilteredcontacts"></a>
+
+### `g8.api.contacts.mergeFilteredContacts(input)`
+
+**Merge Filtered Contacts**
+
+- HTTP: `POST /api/v1/contacts/merge-filtered`
+- operationId: `merge_filtered_contacts_contacts_merge_filtered_post` (also callable as `g8.api.call("merge_filtered_contacts_contacts_merge_filtered_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Add every contact matching a filter into `target_list_id`.
+
+Despite the name this does NOT merge duplicate contacts together - it
+merges a SELECTION INTO A LIST. `/duplicates` is the surface that merges
+records.
+
+A 409 means some contacts need a decision before they can be added; re-send
+with `conflict_resolution`. Blocked contacts are never added regardless.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `MergeFilteredRequest` | yes | Request body; fields below. |
+| `query.filterModel` | `string \| null` | no | Optional per-column filter JSON, applied alongside `filter`. |
+| `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.contacts.mergeFilteredContacts({ body: { target_list_id: 123 } });
+```
+
+---
+
+<a id="op-pauserecordworkflowexecution"></a>
+
+### `g8.api.contacts.pauseRecordWorkflowExecution(input)`
+
+**Pause Record Workflow Execution**
+
+- HTTP: `POST /api/v1/contacts/workflow-executions/{execution_id}/pause`
+- operationId: `pause_record_workflow_execution_contacts_workflow_executions__execution_id__pause_post` (also callable as `g8.api.call("pause_record_workflow_execution_contacts_workflow_executions__execution_id__pause_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Pause a running row workflow at its next step boundary.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.execution_id` | `string` | yes | Workflow execution 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.contacts.pauseRecordWorkflowExecution({ path: { execution_id: "id" } });
+```
+
+---
+
+<a id="op-previewcontactmerge"></a>
+
+### `g8.api.contacts.previewContactMerge(input)`
+
+**Preview Contact Merge**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/merge/preview`
+- operationId: `preview_contact_merge_contacts__contact_id__merge_preview_get` (also callable as `g8.api.call("preview_contact_merge_contacts__contact_id__merge_preview_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Side-by-side comparison and blocker check. Writes nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | The contact that SURVIVES the merge. |
+| `query.secondary` | `integer` | yes | The contact 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.contacts.previewContactMerge({ path: { contact_id: 123 }, query: { secondary: 1 } });
+```
+
+---
+
+<a id="op-previewdetectionrule"></a>
+
+### `g8.api.contacts.previewDetectionRule(input)`
+
+**Preview Detection Rule**
+
+- HTTP: `POST /api/v1/duplicates/settings/preview-detection-rule`
+- operationId: `preview_detection_rule_duplicates_settings_preview_detection_rule_post` (also callable as `g8.api.call("preview_detection_rule_duplicates_settings_preview_detection_rule_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `contacts:read`
+
+Dry-run a duplicate-detection rule. Writes nothing.
+
+Returns the pair count the rule would match plus a small sample, which is
+the only way to size a rule before auto-merge acts on it. A POST because
+the rule is a body; tiered a read so a read-only key can check a rule
+before someone saves it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `PreviewDetectionRuleRequest` | yes | Request body; fields below. |
+
+Body fields (`PreviewDetectionRuleRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.entity_type` | `"contact" \| "company" \| "deal"` | yes | Object the rule matches on. |
+| `body.field` | `string` | yes | Column the rule compares. |
+| `body.match_mode` | `"exact" \| "normalized" \| "fuzzy_levenshtein" \| "domain_match" \| "phone_e164" \| "linkedin_handle"` | yes | How two values are considered equal. |
+| `body.rule_name` | `string` | yes | Name for the rule being previewed. |
+| `body.template` | `string` | yes | Platform rule template the rule is built from. |
+| `body.confidence_bucket` | `"high" \| "medium" \| "low" \| null` | no | Override the default confidence bucket. |
+| `body.score` | `integer \| null` | no | Override the platform default score for this rule. |
+
+**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.contacts.previewDetectionRule({
+  body: {
+    entity_type: "contact",
+    field: "example",
+    match_mode: "exact",
+    rule_name: "Example",
+    template: "example",
+  },
+});
+```
+
+---
+
+<a id="op-regeneratecontactdocument"></a>
+
+### `g8.api.contacts.regenerateContactDocument(input)`
+
+**Regenerate Contact Document**
+
+- HTTP: `POST /api/v1/contacts/{contact_id}/documents/types/{doc_type}/regenerate`
+- operationId: `regenerate_contact_document_contacts__contact_id__documents_types__doc_type__regenerate_post` (also callable as `g8.api.call("regenerate_contact_document_contacts__contact_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.contact_id` | `integer` | yes | Contact 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.contacts.regenerateContactDocument({ path: { contact_id: 123, doc_type: "example" } });
+```
+
+---
+
+<a id="op-resumerecordworkflowexecution"></a>
+
+### `g8.api.contacts.resumeRecordWorkflowExecution(input)`
+
+**Resume Record Workflow Execution**
+
+- HTTP: `POST /api/v1/contacts/workflow-executions/{execution_id}/resume`
+- operationId: `resume_record_workflow_execution_contacts_workflow_executions__execution_id__resume_post` (also callable as `g8.api.call("resume_record_workflow_execution_contacts_workflow_executions__execution_id__resume_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Resume a paused row workflow.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.execution_id` | `string` | yes | Workflow execution 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.contacts.resumeRecordWorkflowExecution({ path: { execution_id: "id" } });
+```
+
+---
+
+<a id="op-runduplicatedetection"></a>
+
+### `g8.api.contacts.runDuplicateDetection(input)`
+
+**Run Duplicate Detection**
+
+- HTTP: `POST /api/v1/duplicates/detection/run`
+- operationId: `run_duplicate_detection_duplicates_detection_run_post` (also callable as `g8.api.call("run_duplicate_detection_duplicates_detection_run_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Scan the org for duplicates of one record type now. Admin-only.
+
+Rate-limited by the app to once per 15 minutes per record type (429 with
+the wait). Finds suggestions only - nothing is merged.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `RunDetectionRequest` | yes | Request body; fields below. |
+
+Body fields (`RunDetectionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.entity_type` | `"contact" \| "company" \| "deal"` | yes | What to scan. |
+
+**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.contacts.runDuplicateDetection({ body: { entity_type: "contact" } });
+```
+
+---
+
+<a id="op-runrecordworkflow"></a>
+
+### `g8.api.contacts.runRecordWorkflow(input)`
+
+**Run Record Workflow**
+
+- HTTP: `POST /api/v1/contacts/workflow-executions/run`
+- operationId: `run_record_workflow_contacts_workflow_executions_run_post` (also callable as `g8.api.call("run_record_workflow_contacts_workflow_executions_run_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Run a list workflow over rows. SPENDS CREDITS when its steps enrich or call a model.
+
+`run_mode=all` runs over every row in the list, so the spend is bounded
+by the list, not the request.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `RunRecordWorkflowRequest` | yes | Request body; fields below. |
+
+Body fields (`RunRecordWorkflowRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.list_id` | `integer` | yes | List (workbench) the workflow belongs to. |
+| `body.record_ids` | `Array<integer>` | yes | Rows to run it on, for `selected`. |
+| `body.workflow_id` | `string` | yes | Workflow to run. |
+| `body.run_mode` | `"selected" \| "filtered" \| "all"` | no | Which rows to run on. default `"selected"` |
+
+**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.contacts.runRecordWorkflow({ body: { list_id: 123, record_ids: [123], workflow_id: "id" } });
+```
+
+---
+
+<a id="op-saveskillresulttocontact"></a>
+
+### `g8.api.contacts.saveSkillResultToContact(input)`
+
+**Save Skill Result To Contact**
+
+- HTTP: `POST /api/v1/contacts/{contact_id}/documents/from-skill`
+- operationId: `save_skill_result_to_contact_contacts__contact_id__documents_from_skill_post` (also callable as `g8.api.call("save_skill_result_to_contact_contacts__contact_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: `contacts:write`
+
+Store a skill run's output on this contact as a document.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact primary key. |
+| `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.contacts.saveSkillResultToContact({
+  path: { contact_id: 123 },
+  body: { action_name: "Example", content: "example", execution_id: "id" },
+});
+```
+
+---
+
+<a id="op-triggerautomerge"></a>
+
+### `g8.api.contacts.triggerAutoMerge(input)`
+
+**Trigger Auto Merge**
+
+- HTTP: `POST /api/v1/duplicates/auto-merge`
+- operationId: `trigger_auto_merge_duplicates_auto_merge_post` (also callable as `g8.api.call("trigger_auto_merge_duplicates_auto_merge_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `contacts:delete`
+
+Run auto-merge once. RECORDS ARE DESTROYED.
+
+Each merge removes one record and moves its data onto the survivor. The
+only way back is `POST /duplicates/undo-merge/{merge_history_id}`, one
+merge at a time. Send `dry_run=true` first.
+
+A 200 does NOT by itself mean anything merged: if the org has auto-merge
+disabled or is in shadow mode the response says so instead of failing,
+which is the app's behaviour and is preserved here. Read the body.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `AutoMergeRequest` | yes | Request body; fields below. |
+
+Body fields (`AutoMergeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.entity_type` | `"contact" \| "company"` | yes | Object to merge. |
+| `body.dry_run` | `boolean` | no | Report what would merge without merging it. 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
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.contacts.triggerAutoMerge({ body: { entity_type: "contact" } });
+```
+
+---
+
+<a id="op-unassigncontacttags"></a>
+
+### `g8.api.contacts.unassignContactTags(input)`
+
+**Unassign Contact Tags**
+
+- HTTP: `POST /api/v1/contacts/tags/unassign`
+- operationId: `unassign_contact_tags_contacts_tags_unassign_post` (also callable as `g8.api.call("unassign_contact_tags_contacts_tags_unassign_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Remove tags from contacts. The tag definitions survive.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ContactTagAssignRequest` | yes | Request body; fields below. |
+
+Body fields (`ContactTagAssignRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.tag_ids` | `Array<string>` | yes | min items 1 |
+| `body.contact_ids` | `Array<integer>` | no | Contacts to tag. |
+
+**Returns** `ApiResponse_ContactTagWriteResult_`: the envelope `{ data: ContactTagWriteResult, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.contacts.unassignContactTags({ body: { tag_ids: ["id"] } });
+```
+
+---
+
+<a id="op-unlockcontactinfo"></a>
+
+### `g8.api.contacts.unlockContactInfo(input)`
+
+**Unlock Contact Info**
+
+- HTTP: `POST /api/v1/contacts/unlock-info`
+- operationId: `unlock_contact_info_contacts_unlock_info_post` (also callable as `g8.api.call("unlock_contact_info_contacts_unlock_info_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Reveal withheld contact details. CHARGES CREDITS.
+
+Returns `credits_charged`. Contacts already unlocked are not charged
+again, so re-sending the same ids is safe - but `all_matching` resolves an
+unbounded selection, and every newly-unlocked contact in it is billed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `UnlockContactInfoRequest` | yes | Request body; fields below. |
+| `query.filterModel` | `string \| null` | no | Per-column filter JSON, resolved against `list_id`. |
+
+Body fields (`UnlockContactInfoRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.allMatching` | `boolean` | no | Resolve the complete matching set server-side. default `false` |
+| `body.contact_ids` | `Array<integer> \| null` | no | Contacts to unlock (max 1000). max items 1000 |
+| `body.filterModel` | `Record<string, unknown>` | no | Per-column filters. |
+| `body.list_id` | `integer \| null` | no | Unlock the contacts in this list. |
+| `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
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.contacts.unlockContactInfo({ body: {} });
+```
+
+---
+
+<a id="op-updatecontact"></a>
+
+### `g8.api.contacts.updateContact(input)`
+
+**Update Contact**
+
+- HTTP: `PATCH /api/v1/contacts/{contact_id}`
+- operationId: `update_contact_contacts__contact_id__patch` (also callable as `g8.api.call("update_contact_contacts__contact_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+- ★ Hand-written: [`g8.contacts.update()`](../sdk-clients.md#g8-contacts-update)
+
+Update a contact's fields (partial update).
+
+Company link (both optional; a contact may have no company): ``company_id``
+attaches an EXISTING company (mashup_companies.id) directly; ``company_domain``
+resolves-or-creates a company from its domain. ``company_id`` wins if both
+are given. Every other field is a plain column update. Provide any subset;
+at least one field (plain or company) is required.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact ID |
+| `body` | `ContactUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`ContactUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.city` | `string \| null` | no |  |
+| `body.company_domain` | `string \| null` | no |  |
+| `body.company_id` | `integer \| null` | no |  |
+| `body.country` | `string \| null` | no |  |
+| `body.direct_phone` | `string \| null` | no |  |
+| `body.first_name` | `string \| null` | no |  |
+| `body.job_department` | `string \| null` | no |  |
+| `body.job_title` | `string \| null` | no |  |
+| `body.last_name` | `string \| null` | no |  |
+| `body.linkedin_url` | `string \| null` | no |  |
+| `body.mobile_phone` | `string \| null` | no |  |
+| `body.seniority_level` | `string \| null` | no |  |
+| `body.state` | `string \| null` | no |  |
+| `body.work_email` | `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.contacts.updateContact({ path: { contact_id: 123 }, body: {} });
+```
+
+---
+
+<a id="op-updatecontactdocument"></a>
+
+### `g8.api.contacts.updateContactDocument(input)`
+
+**Update Contact Document**
+
+- HTTP: `PUT /api/v1/contacts/{contact_id}/documents/{document_id}`
+- operationId: `update_contact_document_contacts__contact_id__documents__document_id__put` (also callable as `g8.api.call("update_contact_document_contacts__contact_id__documents__document_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Edit a generated document's content or structured data by hand.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact id. |
+| `path.document_id` | `string` | yes | Document id. |
+| `body` | `ContactDocumentUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`ContactDocumentUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.content` | `string \| null` | no | Replacement document body. |
+| `body.structured_data` | `Record<string, unknown> \| null` | no | Replacement structured payload. |
+
+**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.contacts.updateContactDocument({ path: { contact_id: 123, document_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updatecontacttag"></a>
+
+### `g8.api.contacts.updateContactTag(input)`
+
+**Update Contact Tag**
+
+- HTTP: `PATCH /api/v1/contacts/tags/{tag_id}`
+- operationId: `update_contact_tag_contacts_tags__tag_id__patch` (also callable as `g8.api.call("update_contact_tag_contacts_tags__tag_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Rename, recolour, redescribe or archive a tag. Omitted fields stay.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.tag_id` | `string` | yes | Tag id. |
+| `body` | `ContactTagUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`ContactTagUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.archived` | `boolean \| null` | no | Archive without deleting. |
+| `body.color` | `string \| null` | no | pattern `^#[0-9A-Fa-f]{6}$` |
+| `body.description` | `string \| null` | no | max length 200 |
+| `body.name` | `string \| null` | no | min length 1, max length 50 |
+
+**Returns** `ApiResponse_ContactTag_`: the envelope `{ data: ContactTag, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ContactTag` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `archived` | `boolean \| null` | no |  |
+| `color` | `string \| null` | no |  |
+| `contact_count` | `integer \| null` | no | Contacts currently carrying the tag. |
+| `description` | `string \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.contacts.updateContactTag({ path: { tag_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updateduplicatesettings"></a>
+
+### `g8.api.contacts.updateDuplicateSettings(input)`
+
+**Update Duplicate Settings**
+
+- HTTP: `PUT /api/v1/duplicates/settings`
+- operationId: `update_duplicate_settings_duplicates_settings_put` (also callable as `g8.api.call("update_duplicate_settings_duplicates_settings_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+REPLACE the org's merge settings wholesale. Partial updates are not supported.
+
+Read with `GET /duplicates/settings`, change what you need, and send the
+whole tree back - a missing section falls back to the platform default.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `Record<string, unknown>` | yes | Request body; fields below. |
+
+**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.contacts.updateDuplicateSettings({ body: {} });
+```
+
+---
+
+<a id="op-verifycontactemails"></a>
+
+### `g8.api.contacts.verifyContactEmails(input)`
+
+**Verify Contact Emails**
+
+- HTTP: `POST /api/v1/contacts/verify-email`
+- operationId: `verify_contact_emails_contacts_verify_email_post` (also callable as `g8.api.call("verify_contact_emails_contacts_verify_email_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Re-check deliverability for a batch of contacts. SPENDS CREDITS.
+
+Synchronous: one call to the verification service, and the result is
+written back onto each contact. Capped at 1000 contacts - use
+`/contacts/verify-email/async` for a whole list.
+
+Different from `POST /enrichment/verify-email`, which checks one arbitrary
+address and stores nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `VerifyContactEmailRequest` | yes | Request body; fields below. |
+| `query.list_id` | `integer \| null` | no | Restrict a filtered selection to this list. |
+| `query.filterModel` | `string \| null` | no | Per-column filter JSON. With `list_id`, verifies every matching contact instead of the ids in the body. |
+
+Body fields (`VerifyContactEmailRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.contact_pks` | `Array<integer>` | no | Contact primary keys (max 1000). Empty verifies nothing. max items 1000 |
+
+**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
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.contacts.verifyContactEmails({ body: {} });
+```
+
+---
+
+<a id="op-verifycontactemailsasync"></a>
+
+### `g8.api.contacts.verifyContactEmailsAsync(input)`
+
+**Verify Contact Emails Async**
+
+- HTTP: `POST /api/v1/contacts/verify-email/async`
+- operationId: `verify_contact_emails_async_contacts_verify_email_async_post` (also callable as `g8.api.call("verify_contact_emails_async_contacts_verify_email_async_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `enrichment:run`
+
+Queue verification for a whole list or filtered selection. SPENDS CREDITS.
+
+Returns the number of contacts and addresses ACCEPTED, not verified - the
+results land on the contacts as the job runs. `all_matching` resolves the
+selection server-side, so the cost is not bounded by anything in the
+request; send the filter you actually mean.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `VerifyContactEmailAsyncRequest` | yes | Request body; fields below. |
+
+Body fields (`VerifyContactEmailAsyncRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.allMatching` | `boolean` | no | Resolve the complete matching set server-side, not just a page. default `false` |
+| `body.filterModel` | `Record<string, unknown>` | no | Per-column filters, keyed by column name. |
+| `body.list_id` | `integer \| null` | no | Restrict the selection to this list. |
+| `body.segmentFilter` | `SegmentFilterGroup \| null` | no | Advanced cross-column 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
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.contacts.verifyContactEmailsAsync({ body: {} });
+```
+
+---
+
+<a id="op-withdrawcontactsfromsequences"></a>
+
+### `g8.api.contacts.withdrawContactsFromSequences(input)`
+
+**Withdraw Contacts From Sequences**
+
+- HTTP: `POST /api/v1/contacts/withdraw-from-sequences`
+- operationId: `withdraw_contacts_from_sequences_contacts_withdraw_from_sequences_post` (also callable as `g8.api.call("withdraw_contacts_from_sequences_contacts_withdraw_from_sequences_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `contacts:write`
+
+Take contacts OUT of a sequence. They stop receiving its steps.
+
+`remove_all=true` withdraws them from EVERY sequence they are enrolled in
+and ignores `sequence_id` - the wider blast radius of the two, and never
+the default.
+
+`response` is REQUIRED by the app handler rather than decoration: it sets
+a status on it for the partial-withdrawal case, so omitting it is an
+AttributeError on every call.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `WithdrawFromSequencesRequest` | yes | Request body; fields below. |
+
+Body fields (`WithdrawFromSequencesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.contact_ids` | `Array<integer>` | no | Contact primary keys to withdraw (max 5000). max items 5000 |
+| `body.remove_all` | `boolean` | no | Withdraw from EVERY enrolled sequence. Ignores `sequence_id`. default `false` |
+| `body.sequence_id` | `string \| null` | no | Sequence to withdraw from. Required unless `remove_all` is true. |
+| `body.source` | `string \| null` | no | Origin label recorded on the resulting event. default `"workflow"`, max length 64 |
+| `body.target_state` | `string \| null` | no | Terminal state to record: removed \| completed \| not_interested. default `"removed"` |
+
+**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.contacts.withdrawContactsFromSequences({ 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-contactbulkgetitem"></a>
+
+### `ContactBulkGetItem`
+
+One contact: the full record, or `found: false`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `contact_id` | `integer` | yes |  |
+| `found` | `boolean` | yes | False when the contact does not exist or is outside this key's scope (indistinguishable on purpose, like the per-contact 404). |
+| `contact` | `ContactResponse \| null` | no | The same record `GET /contacts/{contact_id}` returns. Null when not found. |
+
+<a id="type-contactcompanysummary"></a>
+
+### `ContactCompanySummary`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `city` | `string \| null` | no |  |
+| `country` | `string \| null` | no |  |
+| `domain` | `string \| null` | no |  |
+| `employee_count` | `string \| null` | no |  |
+| `id` | `integer \| null` | no |  |
+| `industry` | `string \| null` | no |  |
+| `linkedin_url` | `string \| null` | no |  |
+| `logo_url` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `state` | `string \| null` | no |  |
+| `website` | `string \| null` | no |  |
+
+<a id="type-contactrelateditem"></a>
+
+### `ContactRelatedItem`
+
+One contact's related records. A field is present only when requested.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `contact_id` | `integer` | yes |  |
+| `found` | `boolean` | yes | False when the contact does not exist or is outside this key's scope (indistinguishable on purpose, like the per-contact 404). |
+| `lists` | `Array<Record<string, unknown>> \| null` | no |  |
+| `sequences` | `Array<Record<string, unknown>> \| null` | no |  |
+
+<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-customfieldwritereport"></a>
+
+### `CustomFieldWriteReport`
+
+How a write path handled the request's custom (dynamic) column keys. Shared by every Developer API write surface that accepts custom columns (``POST /contacts``, ``PUT /contacts/assert[/batch]``, ``PUT /companies/assert[/batch]``). Every field defaults to empty, so a client that ignores this object sees no behavioural change. It exists because these keys were previously dropped with NO caller-visible signal — the only trace was a server-side ``logger.warning`` in ``append_to_audience``.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created` | `Array<string>` | no | Caller keys for which a NEW custom column was created by this request. |
+| `ignored` | `Array<string>` | no | Caller keys that matched no custom column and were NOT written. Create the column first (POST /fields) or pass create_missing_fields=true. |
+| `written` | `Array<string>` | no | Caller keys that resolved to a custom column and were written. |
+
+<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. |