@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/fields.md

@@ -0,0 +1,566 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.fields`: Fields
+
+8 operations (3 read, 4 write, 1 destructive).
+
+5 of these also have a hand-written method (`g8.fields`), 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: [fields.d.ts](fields.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`createField`](#op-createfield) ★ | `POST /api/v1/fields` | write | `fields:write` | Create Field |
+| [`createFieldsBatch`](#op-createfieldsbatch) | `POST /api/v1/fields/batch` | write | `fields:write` | Create Fields Batch |
+| [`deleteField`](#op-deletefield) ★ | `DELETE /api/v1/fields/{column_id}` | destructive | `fields:delete` | Delete Field |
+| [`getFieldValue`](#op-getfieldvalue) | `GET /api/v1/fields/{column_id}/values` | read | `fields:read` | Get Field Value |
+| [`listCompanyFields`](#op-listcompanyfields) ★ | `GET /api/v1/fields/companies` | read | `fields:read` | List Company Fields |
+| [`listContactFields`](#op-listcontactfields) ★ | `GET /api/v1/fields` | read | `fields:read` | List Contact Fields |
+| [`setFieldValue`](#op-setfieldvalue) ★ | `PATCH /api/v1/fields/{column_id}/values` | write | `fields:write` | Set Field Value |
+| [`setFieldValuesBatch`](#op-setfieldvaluesbatch) | `PATCH /api/v1/fields/values/batch` | write | `fields:write` | Set Field Values Batch |
+
+---
+
+<a id="op-createfield"></a>
+
+### `g8.api.fields.createField(input)`
+
+**Create Field**
+
+- HTTP: `POST /api/v1/fields`
+- operationId: `create_field_fields_post` (also callable as `g8.api.call("create_field_fields_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `fields:write`
+- ★ Hand-written: [`g8.fields.create()`](../sdk-clients.md#g8-fields-create)
+
+Create a new custom field (column) for contacts or companies.
+
+Set `list_id` to make the field specific to a single list, or omit it to
+create a global field available across every list in the org.
+
+Optionally pass an `enrichment` block to provision a companion waterfall
+pipeline in the same request. Without this block the column exists but
+has no enrichment plan, so `POST /enrichment/waterfall/enrich` later
+returns 422 (`waterfall_config_missing`).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CreateFieldRequest` | yes | Request body; fields below. |
+
+Body fields (`CreateFieldRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.title` | `string` | yes | Column title, e.g. 'Job Level' |
+| `body.data_type` | `string` | no | Column data type. Currently only 'text' is supported; additional types (numeric, date, boolean, select) may be added in future versions. default `"text"` |
+| `body.enrichment` | `CreateFieldEnrichmentInput \| null` | no | Optional enrichment-pipeline block. When supplied, a companion `enrichment_configs` row is created in the same request so the new column is immediately runnable via /enrichment/waterfall/enrich. |
+| `body.entity` | `string` | no | Target entity: 'contacts' or 'companies' default `"contacts"` |
+| `body.list_id` | `integer \| null` | no | If set, field is list-specific; otherwise global across the org |
+
+**Returns** `ApiResponse_CreateFieldResponse_`: the envelope `{ data: CreateFieldResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CreateFieldResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `data_type` | `string` | yes |  |
+| `id` | `integer` | yes |  |
+| `is_global` | `boolean` | yes |  |
+| `name` | `string` | yes |  |
+| `title` | `string` | yes |  |
+| `enrichment` | `CreateFieldEnrichmentResponse \| null` | no | Populated when the request included an `enrichment` block. Use `enrichment.column_id` for subsequent /enrichment/waterfall/enrich calls. |
+| `list_id` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.fields.createField({ body: { title: "Example" } });
+```
+
+---
+
+<a id="op-createfieldsbatch"></a>
+
+### `g8.api.fields.createFieldsBatch(input)`
+
+**Create Fields Batch**
+
+- HTTP: `POST /api/v1/fields/batch`
+- operationId: `create_fields_batch_fields_batch_post` (also callable as `g8.api.call("create_fields_batch_fields_batch_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `fields:write`
+
+Create many custom columns (contacts or companies) in ONE request.
+
+Backed by a single DB transaction with ONE view rebuild for the whole batch
+— the efficient path for setting up a list with dozens of columns at once.
+The single-column `POST /fields` is unchanged; this is purely additive.
+
+Validation is fail-fast: data_types, duplicate titles, and every `enrichment`
+block are checked BEFORE any column is created, so a bad request creates
+nothing. Column creation itself is atomic (all columns or none).
+
+Per-column `enrichment` blocks are applied AFTER the columns commit; if a
+companion enrichment config fails for one column, that column still exists
+and its `results[]` entry reports `ok=false` with the error — the rest of
+the batch is unaffected (mirrors the single endpoint's column-then-config
+ordering, but per-field instead of failing the whole request).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CreateFieldsBatchRequest` | yes | Request body; fields below. |
+
+Body fields (`CreateFieldsBatchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.fields` | `Array<BatchFieldItem>` | yes | Columns to create (1-100). |
+| `body.entity` | `string` | no | Target entity for ALL columns: 'contacts' or 'companies' default `"contacts"` |
+| `body.list_id` | `integer \| null` | no | Shared list scope for all columns. REQUIRED if ANY field carries an `enrichment` block — waterfall pipelines are list-scoped. |
+
+**Returns** `ApiResponse_CreateFieldsBatchResponse_`: the envelope `{ data: CreateFieldsBatchResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CreateFieldsBatchResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `entity` | `string` | yes |  |
+| `results` | `Array<BatchFieldResult>` | yes |  |
+| `total_created` | `integer` | yes |  |
+| `total_requested` | `integer` | yes |  |
+| `list_id` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.fields.createFieldsBatch({ body: { fields: [{ title: "Example" }] } });
+```
+
+---
+
+<a id="op-deletefield"></a>
+
+### `g8.api.fields.deleteField(input)`
+
+**Delete Field**
+
+- HTTP: `DELETE /api/v1/fields/{column_id}`
+- operationId: `delete_field_fields__column_id__delete` (also callable as `g8.api.call("delete_field_fields__column_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `fields:delete`
+- ★ Hand-written: [`g8.fields.delete()`](../sdk-clients.md#g8-fields-delete)
+
+Soft-delete a custom field (column).
+
+Always org-scoped (you can only delete columns in your own org). Pass
+``list_id`` to additionally require that the column belong to a specific
+list — that's the safer default for list-scoped agents since the org may
+have many custom columns across different lists.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.column_id` | `integer` | yes | Column ID to delete |
+| `query.entity` | `string` | no | Target entity: 'contacts' or 'companies' default `"contacts"` |
+| `query.list_id` | `integer \| null` | no | Optional list scope guard. If provided, the column must belong to this list or the request returns 404. Use this to prevent an agent with narrow intent from accidentally deleting a column on a different list in the same org. |
+
+**Returns** `ApiResponse_DeleteFieldResponse_`: the envelope `{ data: DeleteFieldResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeleteFieldResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `column_id` | `integer` | yes |  |
+| `deleted` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.fields.deleteField({ path: { column_id: 123 } });
+```
+
+---
+
+<a id="op-getfieldvalue"></a>
+
+### `g8.api.fields.getFieldValue(input)`
+
+**Get Field Value**
+
+- HTTP: `GET /api/v1/fields/{column_id}/values`
+- operationId: `get_field_value_fields__column_id__values_get` (also callable as `g8.api.call("get_field_value_fields__column_id__values_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `fields:read`
+
+Read a single custom column value for one contact or company row.
+
+The read-side counterpart of ``PATCH /fields/{column_id}/values``. Resolves
+``column_id`` to the underlying ``column_name_db`` from ``dynamic_columns``
+(scoped by ``object_type`` so a contacts column can't be read through the
+companies path), then selects that one value from ``mashup_contact_attrs``
+(or ``mashup_company_attrs`` for companies).
+
+Returns ``value: null`` when the column exists but has never been set for
+that row. Returns 404 when the column or the record does not exist.
+
+Backwards-compat: this is a brand-new route; no existing surface changes.
+Custom column VALUES are also surfaced inline on the contact/company read
+endpoints when ``include_custom_fields=true`` is passed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.column_id` | `integer` | yes | Column ID from g8_list_fields or g8_create_field |
+| `query.record_id` | `integer` | yes | Contact ID (entity='contacts') or company ID (entity='companies') |
+| `query.entity` | `string` | no | Target entity: 'contacts' or 'companies' default `"contacts"` |
+
+**Returns** `ApiResponse_GetFieldValueResponse_`: the envelope `{ data: GetFieldValueResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`GetFieldValueResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `column_id` | `integer` | yes |  |
+| `entity` | `string` | yes |  |
+| `name` | `string` | yes | The underlying column slug (column_name_db). |
+| `record_id` | `integer` | yes |  |
+| `value` | `string \| null` | no | The stored value, or null if the column is unset for this row. |
+
+**Example**
+
+```ts
+const result = await g8.api.fields.getFieldValue({ path: { column_id: 123 }, query: { record_id: 123 } });
+```
+
+---
+
+<a id="op-listcompanyfields"></a>
+
+### `g8.api.fields.listCompanyFields(input?)`
+
+**List Company Fields**
+
+- HTTP: `GET /api/v1/fields/companies`
+- operationId: `list_company_fields_fields_companies_get` (also callable as `g8.api.call("list_company_fields_fields_companies_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `fields:read`
+- ★ Hand-written: [`g8.fields.listCompanyFields()`](../sdk-clients.md#g8-fields-listcompanyfields)
+
+List company fields (base + custom). Optionally include list-specific custom fields.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.list_id` | `integer \| null` | no | List ID to include list-specific custom fields |
+
+**Returns** `ApiResponse_list_FieldResponse__`: the envelope `{ data: Array<FieldResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`FieldResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `title` | `string` | yes |  |
+| `data_type` | `string` | no | default `"text"` |
+| `id` | `integer \| null` | no |  |
+| `is_global` | `boolean` | no | default `true` |
+| `name` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.fields.listCompanyFields();
+```
+
+---
+
+<a id="op-listcontactfields"></a>
+
+### `g8.api.fields.listContactFields(input?)`
+
+**List Contact Fields**
+
+- HTTP: `GET /api/v1/fields`
+- operationId: `list_contact_fields_fields_get` (also callable as `g8.api.call("list_contact_fields_fields_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `fields:read`
+- ★ Hand-written: [`g8.fields.listContactFields()`](../sdk-clients.md#g8-fields-listcontactfields)
+
+List contact fields (base + custom). Optionally include list-specific custom fields.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.list_id` | `integer \| null` | no | List ID to include list-specific custom fields |
+
+**Returns** `ApiResponse_list_FieldResponse__`: the envelope `{ data: Array<FieldResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`FieldResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `title` | `string` | yes |  |
+| `data_type` | `string` | no | default `"text"` |
+| `id` | `integer \| null` | no |  |
+| `is_global` | `boolean` | no | default `true` |
+| `name` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.fields.listContactFields();
+```
+
+---
+
+<a id="op-setfieldvalue"></a>
+
+### `g8.api.fields.setFieldValue(input)`
+
+**Set Field Value**
+
+- HTTP: `PATCH /api/v1/fields/{column_id}/values`
+- operationId: `set_field_value_fields__column_id__values_patch` (also callable as `g8.api.call("set_field_value_fields__column_id__values_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `fields:write`
+- ★ Hand-written: [`g8.fields.setValue()`](../sdk-clients.md#g8-fields-setvalue)
+
+Write a custom column value to a single contact or company row.
+
+Resolves ``column_id`` to the underlying ``column_name_db`` from
+``dynamic_columns``, then performs an ``INSERT ... ON CONFLICT DO UPDATE``
+against ``mashup_contact_attrs`` (or ``mashup_company_attrs`` for companies).
+
+Pass ``value=null`` (or omit it) to clear the column for that row.
+
+Notes:
+    - The column must exist in ``dynamic_columns`` (not soft-deleted) for
+      this org and the matching entity. Returns 404 otherwise.
+    - The record (contact or company) must exist - the underlying foreign
+      key constraint enforces this; a missing record yields a 404.
+    - Custom column writes do NOT trigger view recreation; only column
+      creation does (see ``CdpMashupContactRepository.create_column``).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.column_id` | `integer` | yes | Column ID from g8_list_fields or g8_create_field |
+| `body` | `SetFieldValueRequest` | yes | Request body; fields below. |
+
+Body fields (`SetFieldValueRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.record_id` | `integer` | yes | Contact ID (entity='contacts') or company ID (entity='companies') |
+| `body.entity` | `string` | no | Target entity: 'contacts' or 'companies' default `"contacts"` |
+| `body.value` | `string \| null` | no | Value to write into the custom column. Pass null (or omit) to clear the field. |
+
+**Returns** `ApiResponse_SetFieldValueResponse_`: the envelope `{ data: SetFieldValueResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SetFieldValueResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `column_id` | `integer` | yes |  |
+| `record_id` | `integer` | yes |  |
+| `updated` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+const result = await g8.api.fields.setFieldValue({ path: { column_id: 123 }, body: { record_id: 123 } });
+```
+
+---
+
+<a id="op-setfieldvaluesbatch"></a>
+
+### `g8.api.fields.setFieldValuesBatch(input)`
+
+**Set Field Values Batch**
+
+- HTTP: `PATCH /api/v1/fields/values/batch`
+- operationId: `set_field_values_batch_fields_values_batch_patch` (also callable as `g8.api.call("set_field_values_batch_fields_values_batch_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `fields:write`
+
+Write custom column values to one OR many rows in a single call.
+
+The batch counterpart of ``PATCH /fields/{column_id}/values``. Each row
+carries its own ``record_id`` and a list of ``{column_id, value}`` pairs;
+every row shares the top-level ``entity``. A single-row update is just a
+``rows`` list of length one.
+
+Partial success: each row is applied inside its own SAVEPOINT, so a bad row
+(missing record, unknown column) is reported ``ok: false`` in ``results[]``
+while the remaining rows still commit. Pass ``value=null`` (or omit it) on a
+pair to clear that column for the row.
+
+Limits: 1-500 rows per call; a ``record_id`` may appear only once per call
+(fold that record's writes into one row) - duplicates 400.
+
+Efficiency: all referenced ``column_id``s are resolved in one query and all
+``record_id``s are existence-checked in one query, then each row is written
+with a single multi-column upsert (N+2 statements, not N*M).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SetFieldValuesBatchRequest` | yes | Request body; fields below. |
+
+Body fields (`SetFieldValuesBatchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.rows` | `Array<RowFieldValues>` | yes | Rows to update (1-500). Each carries its own record_id + fields[]. |
+| `body.entity` | `string` | no | Target entity, SHARED across every row: 'contacts' or 'companies'. default `"contacts"` |
+| `body.strict` | `boolean` | no | Opt-in status-code semantics. Default false keeps the historical behaviour: always HTTP 200, per-row outcomes in `results[]`. When true, a batch where EVERY row failed returns 422 and a partially-failed batch returns 207 Multi-Status, so a client that only checks the status code cannot mistake a total failure for success. The response body is identical either way. default `false` |
+
+**Returns** `ApiResponse_SetFieldValuesBatchResponse_`: the envelope `{ data: SetFieldValuesBatchResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SetFieldValuesBatchResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `entity` | `string` | yes |  |
+| `results` | `Array<SetFieldValuesRowResult>` | yes |  |
+| `total_rows_requested` | `integer` | yes |  |
+| `total_rows_updated` | `integer` | yes |  |
+| `total_values_written` | `integer` | yes |  |
+| `all_failed` | `boolean` | no | True when rows were requested and NONE were written. default `false` |
+| `total_rows_failed` | `integer` | no | Rows that could not be written (see results[].error). default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.fields.setFieldValuesBatch({ body: { rows: [{ record_id: 123 }] } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-batchfielditem"></a>
+
+### `BatchFieldItem`
+
+One column in a batch-create request. `title`, `data_type` and the optional `enrichment` block are per-column; `list_id` and `entity` are shared at the parent `CreateFieldsBatchRequest` level (a batch targets one entity and, when enrichment is used, one list).
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `title` | `string` | yes | Column title, e.g. 'Job Level' |
+| `data_type` | `string` | no | Column data type. Currently only 'text' is supported. default `"text"` |
+| `enrichment` | `CreateFieldEnrichmentInput \| null` | no | Optional per-column waterfall enrichment block (identical shape to POST /fields). When supplied, a companion enrichment_configs row is created for that column so it's immediately runnable. |
+
+<a id="type-batchfieldresult"></a>
+
+### `BatchFieldResult`
+
+Per-column outcome inside a batch response.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `title` | `string` | yes |  |
+| `enrichment` | `CreateFieldEnrichmentResponse \| null` | no |  |
+| `error` | `string \| null` | no | Set when the column was created but its companion enrichment config failed. |
+| `id` | `integer \| null` | no |  |
+| `is_global` | `boolean` | no | True when this column was created org-GLOBAL (no list_id was supplied) and will therefore appear on EVERY list in the org. Pass `list_id` to scope columns to one list. default `false` |
+| `list_id` | `integer \| null` | no | The list this column is scoped to, or null when it is org-global. |
+| `name` | `string \| null` | no |  |
+| `ok` | `boolean` | no | default `true` |
+
+<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-rowfieldvalues"></a>
+
+### `RowFieldValues`
+
+One row (contact or company) plus the columns to set on it.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `record_id` | `integer` | yes | Contact ID (entity='contacts') or company ID (entity='companies'). |
+| `fields` | `Array<FieldValueItem>` | no | Column/value pairs to write on this row. Empty = no-op (counts as ok with 0 writes). max items 500 |
+
+<a id="type-setfieldvaluesrowresult"></a>
+
+### `SetFieldValuesRowResult`
+
+Per-row outcome inside a batch value-write response.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `record_id` | `integer` | yes |  |
+| `error` | `string \| null` | no | Set when this row failed (record not found, unknown column, etc.). Other rows still commit. |
+| `ok` | `boolean` | no | default `true` |
+| `updated_columns` | `Array<integer>` | no |  |