Writing data — field rules & gotchas

This is the section responsible for the most support tickets — read it before you write your first bulk-load script.

custom_fields merges, it doesn’t replace

A PATCH only touches the fields you include. It’s idempotent — sending the same payload twice has the same effect as sending it once. Fields you omit are left exactly as they were.

Dropdowns store the option key, not the display label — the #1 mistake

Every dropdown field is backed by a set of {key, value, csvKey} option definitions (see Field configuration & data mapping). You must send the key, not the human-readable label shown in the UI.

The dangerous part: sending the label instead of the key fails silently. You get a 200 OK, but the field is left blank. Read the field-config to get the option keys — see Field configuration & data mapping.

Example: the aiocStatus field has an option {"key": "aiocApproved", "value": "80 - Closed - AIOC Approved"}.


// Wrong — 200 OK, field stays blank
{ "custom_fields": { "aiocStatus": "80 - Closed - AIOC Approved" } }
// Right
{ "custom_fields": { "aiocStatus": "aiocApproved" } }

Multiselect dropdowns

Arrays of option keys:


{ "custom_fields": { "aiTechnologyType": ["Generative"] } }

URL fields

Arrays of "<label>[separator]<url>" strings — the literal token [separator] is required and is not a placeholder for you to replace:


{ "custom_fields": { "documentationLink": ["Design Doc[separator]https://example.com/doc"] } }

Dates

ISO-8601, always with a time component:


2025-10-31T00:00:00.000Z

If your source data is MM/DD/YYYY, convert it to YYYY-MM-DDT00:00:00.000Z before sending.

Plain strings. user-dropdown fields accept a plain name string.

Skip calculated fields

Fields with type: "calculated" (e.g., a “days open” counter) are computed server-side. Don’t attempt to write to them — there’s nothing to write, since the value is derived every time it’s read.

Unknown keys are accepted silently

If you send a custom_fields key that doesn’t exist in the field configuration, AlignAI accepts it without complaint and stores it as junk data rather than rejecting the request. Always validate your keys against the field-config endpoint before writing — see Field configuration & data mapping.

Known field-key gotchas

cyberJira / eaJira — these Jira-linked fields store the ticket ID only, not the full ticket URL.
Field keys can differ between production and QA. The clearest known example: the same logical comments field is keyed generalComments in production but commentsPlainText in QA. Don’t assume a field key that works in QA will work unchanged in production — pull the field-config for each environment separately and reconcile the differences before you go live.