Fields endpoints

Set a run's field values in one transaction; a JSON number is the canonical, a string is parsed by the field's format. Every operation with parameters, body, responses, errors and examples.

View this page as Markdown

Set a run's field values in one transaction; a JSON number is the canonical, a string is parsed by the field's format.

Base URL https://app.processcart.com/api/v1. Every operation below is also in the OpenAPI document and the interactive reference.

Operation	Method and path	Scope
Set field values	`PATCH /v1/runs/{id}/fields`	Scope `runs:write`

PATCH /v1/runs/{id}/fields

Set field values. Scope runs:write · checked against the key's workflow / folder allowlist (403 not_allowed_for_key outside it) · accepts Idempotency-Key · accepts Expected-Revision (409 revision_mismatch when stale). Operation id setRunFields · open in the API reference.

Writes one to two hundred field values in ONE transaction under the run lock (all-or-nothing — one bad key fails the whole request with every problem listed). A JSON number is the canonical value; a string is parsed by the field's format; null clears. Formula, file and display-text fields are not writable; fields of a completed task must be reopened first. Out-of-bounds values are accepted and flagged in validationError.

Path parameters

Name	Type	Required	Description
`id`	string (uuid)	yes

Request headers

Name	Type	Required	Description
`Idempotency-Key`	string	no	Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored.
`Expected-Revision`	string	no	Optimistic concurrency: the run's `revision` you last saw (from any Run body) — a bare integer (`7`) or the same in double quotes (`"7"`); `*` or no header = no precondition. Checked INSIDE the run lock — a stale value is refused with 409 `revision_mismatch` whose body names `currentRevision`. A list or any other value is a 422. A successful write answers its new `revision` in the body. The API sends no `ETag` and refuses `If-Match` (422): CDN layers evaluate `If-Match` against the response and turn a successful write into a 412.

Request body — application/json, FieldsWrite

Responses

Status	Meaning	Body
200	OK.	Run
401	No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked.	Problem
403	`insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key.	Problem
404	`not_found` — Not found.	Problem
405	The verb is not supported on this path. `method_not_allowed` — Method not allowed.	Problem
409	`idempotency_in_progress` — Request in progress; `revision_mismatch` — Revision mismatch; `run_archived` — Run is archived; `run_trashed` — Run is in Trash; `task_completed` — Task already completed.	Problem
413	`payload_too_large` — Payload too large.	Problem
415	`unsupported_media_type` — Unsupported media type.	Problem
422	`field_not_writable` — Field is not writable; `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed.	Problem
429	`rate_limited` — Too many requests.	Problem
500	`internal_error` — Internal error.	Problem
503	`unavailable` — Service unavailable.	Problem

Errors (every code this operation can answer; see Errors)

401 invalid_api_key — Invalid API key
401 key_revoked — API key revoked
401 unauthorized — Authentication required
403 insufficient_scope — Insufficient scope
403 not_allowed_for_key — Not allowed for this key
403 read_only_key — Read-only key
404 not_found — Not found
405 method_not_allowed — Method not allowed
409 idempotency_in_progress — Request in progress
409 revision_mismatch — Revision mismatch
409 run_archived — Run is archived
409 run_trashed — Run is in Trash
409 task_completed — Task already completed
413 payload_too_large — Payload too large
415 unsupported_media_type — Unsupported media type
422 field_not_writable — Field is not writable
422 idempotency_key_reused — Idempotency key reused
422 validation_failed — Validation failed
429 rate_limited — Too many requests
500 internal_error — Internal error
503 unavailable — Service unavailable

Example request

{
  "amount": "$1,850.00",
  "rate": 0.075,
  "rate_text": "7.5%",
  "memo": "Updated by the API",
  "fee": 400,
  "agree": false,
  "tags": [],
  "source": 42,
  "owner": [
    "61465009-1ab5-4eb6-b4f3-3aae0718d1fb"
  ]
}

Example response (200)

{
  "id": "33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "name": "ORD 2026-10-15 Acme Corp",
  "status": "active",
  "priority": "high",
  "labels": [
    "waiting"
  ],
  "labelDetails": [
    {
      "id": "waiting",
      "name": "Waiting",
      "color": "#f59e0b"
    }
  ],
  "dueAt": "2026-11-01T17:00:00.000Z",
  "keyDate": "2026-10-15",
  "revision": 8,
  "updatedAt": "2026-10-13T01:09:51.829Z",
  "startedAt": "2026-10-13T01:09:28.930Z",
  "startedBy": "api",
  "startedByUserId": null,
  "schedule": null,
  "scheduledFor": null,
  "completedAt": null,
  "deletedAt": null,
  "workflow": {
    "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
    "name": "Order fulfillment"
  },
  "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
  "url": "https://app.processcart.com/runs/33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "tasks": [
    {
      "key": "details",
      "title": "Details",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "review",
      "title": "Review",
      "kind": "approval",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [
        {
          "kind": "user",
          "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
        }
      ],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "stop",
      "title": "Sign-off",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "wrapup",
      "title": "Wrap up",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": true,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    }
  ],
  "fields": [
    {
      "key": "customer",
      "label": "Customer",
      "type": "text",
      "format": "none",
      "taskKey": "details",
      "value": "Ada Lovelace",
      "formatted": "Ada Lovelace",
      "visible": true
    },
    {
      "key": "order_code",
      "label": "Order code",
      "type": "text",
      "format": "custom",
      "taskKey": "details",
      "value": "AB-1234",
      "formatted": "AB-1234",
      "visible": true
    },
    {
      "key": "memo",
      "label": "Memo",
      "type": "textarea",
      "format": null,
      "taskKey": "details",
      "value": "Updated by the API",
      "formatted": "Updated by the API",
      "visible": true
    },
    {
      "key": "quantity",
      "label": "Quantity",
      "type": "number",
      "format": "number",
      "taskKey": "details",
      "value": 1250,
      "formatted": "1,250",
      "visible": true
    },
    {
      "key": "amount",
      "label": "Amount",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 1850,
      "formatted": "$1,850.00",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 400,
      "formatted": "$400.00",
      "visible": true
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": 0.075,
      "formatted": "7.5%",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": 0.075,
      "formatted": "7.5%",
      "visible": true
    },
    {
      "key": "ship_date",
      "label": "Ship date",
      "type": "date",
      "format": "date",
      "taskKey": "details",
      "value": "2026-10-15",
      "formatted": "Oct 15, 2026",
      "visible": true
    },
    {
      "key": "start_time",
      "label": "Start time",
      "type": "time",
      "format": "time",
      "taskKey": "details",
      "value": "14:30",
      "formatted": "2:30 PM",
      "visible": true
    },
    {
      "key": "gift_wrap",
      "label": "Gift wrap",
      "type": "dropdown",
      "format": null,
      "taskKey": "details",
      "value": "Yes",
      "formatted": "Yes",
      "visible": true,
      "choices": [
        "Yes",
        "No"
      ]
    },
    {
      "key": "tags",
      "label": "Tags",
      "type": "multi_choice",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "choices": [
        "A",
        "B",
        "C"
      ]
    },
    {
      "key": "agree",
      "label": "Agree",
      "type": "checkbox",
      "format": null,
      "taskKey": "details",
      "value": false,
      "formatted": "No",
      "visible": true
    },
    {
      "key": "contact_email",
      "label": "Contact email",
      "type": "email",
      "format": "email",
      "taskKey": "details",
      "value": "ada@example.com",
      "formatted": "ada@example.com",
      "visible": true
    },
    {
      "key": "website",
      "label": "Website",
      "type": "url",
      "format": "url",
      "taskKey": "details",
      "value": "https://example.com/",
      "formatted": "https://example.com/",
      "visible": true
    },
    {
      "key": "phone",
      "label": "Phone",
      "type": "phone",
      "format": "phone",
      "taskKey": "details",
      "value": "+14155550100",
      "formatted": "(415) 555-0100",
      "visible": true
    },
    {
      "key": "owner",
      "label": "Owner",
      "type": "members",
      "format": null,
      "taskKey": "details",
      "value": [
        "61465009-1ab5-4eb6-b4f3-3aae0718d1fb"
      ],
      "formatted": "Fixture Member",
      "visible": true
    },
    {
      "key": "steps",
      "label": "Steps",
      "type": "subtasks",
      "format": null,
      "taskKey": "details",
      "value": [
        "photos"
      ],
      "formatted": "1 of 2: Photos",
      "visible": true,
      "items": [
        {
          "key": "photos",
          "label": "Photos"
        },
        {
          "key": "invoice",
          "label": "Invoice"
        }
      ]
    },
    {
      "key": "contract",
      "label": "Contract",
      "type": "file",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "double_amount",
      "label": "Double amount",
      "type": "formula",
      "format": "currency",
      "taskKey": "details",
      "value": 3700,
      "formatted": "$3,700.00",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": 42,
      "formatted": "42",
      "visible": false
    }
  ]
}