Field values & typing

Every field in a Run (and in every webhook payload) is one entry of fields[]:

{ "key": "amount", "label": "Amount", "type": "number", "format": "currency", "taskKey": "details",
  "value": 1700.5, "formatted": "$1,700.50", "visible": true }

• value is the canonical value — use it for math, comparisons and filters.
• formatted is the display text exactly as the app shows it (en-US) — use it in documents and messages. It is "" when the field is blank.
• type is the field type from the builder; format is the field's effective format — the axis that decides the JSON shape of value. A text field with a currency format reads and writes as a number, like a number field would.

Rules

• Blank is null. A field with no value reads value: null, formatted: "". A checkbox is the exception: it never reads null — a never-set checkbox reads false.
• Numbers are JSON numbers. A currency value is a number in whole currency units (1700.5 reads "$1,700.50"), never cents and never a string. A percent value is a fraction: 0.125 means 12.5 % and reads "12.5%". A plain number is the number.
• Dates are YYYY-MM-DD with no time zone; times are HH:mm (24-hour); run-level instants (dueAt, updatedAt, …) are ISO 8601 in UTC.
• Strings are normalized: emails lowercased, URLs parsed and re-serialized (a missing scheme is added), US phone numbers as E.164 (+15551234567), text as entered.
• Lists are arrays of strings: multi-choice values are the chosen labels, subtasks the checked item keys, members the member user ids, files the attachment ids.
• Formulas and hidden fields read whatever the engine computed: a number, a string, a boolean, or null (also for a formula error). A formula's formatted follows its format (a currency formula reads "$2,400.00").
• Display Text never appears in fields[] — it carries no value.
• Normalization: after a write, compare against the returned value, not against what you sent. "$1,700.50" comes back as 1700.5; "Jun 25 2026" as "2026-06-25"; "ADA@Example.com" as "ada@example.com".

Writing values

PATCH /v1/runs/{id}/fields takes { "<fieldKey>": value, … } (1–200 keys); POST /v1/runs takes the same map as fields. For every key:

• A JSON number is the canonical: send the fraction for a percent (0.125), whole units for a currency (1700.5). It must be finite.
• A string is a human entry parsed by the field's format: "$1,700.50" → 1700.5; "12.5%" → 0.125; "06/25/2026" → "2026-06-25"; "2:30 PM" → "14:30". A comma is always a thousands separator. For a percent field, a bare "12.5" follows the field's entry mode (whole percents or decimals) — send a JSON number or an explicit % from code. For a text-family field a non-string is refused (never coerced to junk).
• A boolean writes a checkbox (false clears it).
• An array of strings writes a multi-choice (every entry must be one of choices), subtasks (every key one of items), or members field (every id a current member — see Directory); an unknown entry is a 422, never silently dropped.
• null or "" clears the field (a whitespace-only string clears too).
• Hidden fields (not shown in the app, not secret) are writable when no formula computes them — the place to stash an external id.
• Not writable: formula fields, any field a formula computes, Display Text, and File fields (upload through POST /v1/runs/{id}/files — Tasks, approvals & files). A write to one is a 422 field_not_writable whose errors[] names the reason (computed, file or display_text).
• Out-of-bounds values are accepted and flagged on PATCH /v1/runs/{id}/fields (and for non-kickoff fields at start), exactly as in the app: the value is stored, the field's validationError names the problem, and completing the task refuses until it is fixed (422 required_fields_unsatisfied). A dropdown value outside choices and an unparseable string are refused outright. At start, a visible kickoff field that breaks its bounds or rules is refused instead (422, errors[].code invalid_value — see Runs).
• Strings are capped at 10,000 characters and arrays at 200 items of 200 characters; over the cap is refused, never truncated.

The write is all-or-nothing inside the run's lock: one bad key fails the whole request with every problem listed in errors[] (unknown_field, field_not_writable, invalid_value, unparseable, not_a_choice, not_a_member, …) and nothing is written. A field of a completed task is refused with 409 task_completed — reopen the task first. After the write the engine recomputes formulas, visibility, locks and due dates, voids approvals whose reviewed values changed, and records the trail; the answer is the Run with its new revision — send it as Expected-Revision on the next write (Concurrency).

curl -X PATCH https://app.processcart.com/api/v1/runs/{id}/fields \
  -H "Authorization: Bearer pc_live_…" \
  -H "Content-Type: application/json" \
  -H "Expected-Revision: 7" \
  -d '{ "amount": 1800, "discount": "10%", "ship_date": "2026-10-09", "shipping": "Air", "approved": true, "external_ref": "crm-88213" }'

Per-workflow JSON Schema

GET /v1/workflows/{id}/schema turns these rules into JSON Schema (2020-12) for the workflow's published version — one document for the POST /v1/runs body and one for PATCH /v1/runs/{id}/fields — with each property's type, bounds, enum of choices and the custom x-processcart-type / x-processcart-format annotations (Workflows & schema). Generate your types from it rather than from the static OpenAPI document, where value is the union of every canonical shape.

The typing table

The table is generated from the same typing rule the API serializes and validates with (Field typing carries it on its own page).