---
title: "Set Field Values Batch"
method: PATCH
path: "/fields/values/batch"
tags: ["Fields"]
---

# Set Field Values Batch

`PATCH /fields/values/batch`

## Request

- Base URL: `https://be.graph8.com/api/v1`
- URL: `https://be.graph8.com/api/v1/fields/values/batch`
- Auth: HTTP bearer

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

## Headers

- `Authorization` string, nullable
- `X-Target-Org-Id` string, nullable

## Request body

- SetFieldValuesBatchRequest: Write custom column values to one OR many contact/company rows at once.
  - `rows` RowFieldValues[], required: Rows to update (1-500). Each carries its own record_id + fields[].
    - `record_id` integer, required: Contact ID (entity='contacts') or company ID (entity='companies').
    - `fields` FieldValueItem[]: Column/value pairs to write on this row. Empty = no-op (counts as ok with 0 writes).
      - `column_id` integer, required: Column ID from g8_list_fields or g8_create_field.
      - `value` string, nullable: Value to write into the custom column. Pass null (or omit) to clear the field.
  - `entity` string: Target entity, SHARED across every row: 'contacts' or 'companies'.
  - `strict` boolean: 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.

## Response `200`

Successful Response

- ApiResponseSetFieldValuesBatchResponse
  - `data` SetFieldValuesBatchResponse, required
    - `entity` string, required
    - `total_rows_requested` integer, required
    - `total_rows_updated` integer, required
    - `total_values_written` integer, required
    - `results` SetFieldValuesRowResult[], required
      - `record_id` integer, required
      - `ok` boolean
      - `updated_columns` integer[]
      - `error` string, nullable: Set when this row failed (record not found, unknown column, etc.). Other rows still commit.
    - `total_rows_failed` integer: Rows that could not be written (see results[].error).
    - `all_failed` boolean: True when rows were requested and NONE were written.
  - `pagination` PaginationMeta
    - `page` integer, required: Current page number (1-indexed)
    - `limit` integer, required: Items per page
    - `total` integer, required: Total number of items
    - `has_next` boolean, required: Whether there are more pages
    - `next_cursor` string, nullable: Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers.
    - `total_available` integer, nullable: Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search.
    - `total_is_lower_bound` boolean, nullable: Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search.
    - `notes` string[], nullable: Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/graph8/apis/graph8-developer-api.md) · [All operations](https://skmtc.dev/graph8/apis/graph8-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/graph8/apis/graph8-developer-api/revisions/2e7cfa0ca921?raw)