Copy page

Resource Guides

Custom Fields

Custom fields add organization-specific values to elements, tasks, and publications. The API separates reusable custom-field definitions from the values stored on individual resources.

Use this page for v2 custom-field concepts. Use the API reference for exact request schemas, response schemas, status codes, and field-level validation.

Definition Families

Custom-field definitions are scoped by resource family:

Family	Definition endpoints	Value locations
Element custom fields	/api/v2/custom-fields	root element writes and PATCH /api/v2/elements/{id}/custom-fields
Task custom fields	/api/v2/task-custom-fields	task writes and PATCH /api/v2/elements/{id}/tasks/{taskId}/custom-fields
Publication custom fields	/api/v2/publication-custom-fields	publication writes

Definition list endpoints use the shared pagination model. See Querying Lists before implementing list traversal.

Selection Options

Selection choices are managed under plural options paths:

Code
GET    /api/v2/custom-fields/{id}/options/{optionId}
GET    /api/v2/custom-fields/{id}/options/external-id/{externalId}
POST   /api/v2/custom-fields/{id}/options
PUT    /api/v2/custom-fields/{id}/options/{optionId}
PUT    /api/v2/custom-fields/{id}/options/external-id/{externalId}
PATCH  /api/v2/custom-fields/{id}/options/{optionId}
PATCH  /api/v2/custom-fields/{id}/options/external-id/{externalId}
DELETE /api/v2/custom-fields/{id}/options/{optionId}
DELETE /api/v2/custom-fields/{id}/options/external-id/{externalId}

The same option pattern exists under /api/v2/task-custom-fields and /api/v2/publication-custom-fields.

Important rules:

• option create returns 201 Created.
• option delete returns 204 No Content.
• PUT replaces option fields.
• PATCH is presence-aware.
• externalId: null clears the external ID where the field is documented as clearable.
• name: null is invalid.

Value Shape

Element, task, and publication values use a shared shape:

Code
{
  "customFields": [
    {
      "id": 701,
      "value": "Updated summary"
    },
    {
      "id": 702,
      "selectedOptionIds": [7701]
    }
  ]
}

Send the value field that matches the custom-field type:

Value kind	Field
Text	value
Single selection	selectedOptionIds with one ID
Multiple selection	selectedOptionIds
Date	date in yyyy-MM-dd format
Number	number

The API validates the custom-field definition, selected option IDs, scope, and type-specific rules.

Value Write Semantics

For custom-field patch subresources:

• customFields is required.
• customFields: null is invalid.
• each entry requires id.
• omitted custom-field IDs remain unchanged.
• text fields can be cleared by sending value: "" or value: null.
• date and number fields are cleared by sending the entry without a date or number value.
• selection fields are cleared by sending selectedOptionIds: [].
• single-selection fields accept at most one selected option.
• selected option IDs must belong to the addressed custom-field definition.
• Slack and date-time custom-field rows are intentionally hidden from definition reads and are treated as unavailable if addressed in value writes. Public clients should rely only on TEXT, SINGLE_SELECTION, MULTIPLE_SELECTION, DATE, and NUMBER.

The clearing rules above apply only when the field definition allows empty values. Selection and date definitions can opt out with allowEmptyValue: false — covered next.

Empty-Value Fallback Defaults

Additional rules:

• the fallback applies only to entries present in the payload; omitted fields keep patch semantics.
• when a full replacement endpoint treats customFields as replacement state, it removes omitted active, writable current-organization values for that resource scope; foreign-organization, inactive, Slack, and date-time values outside the public write model are preserved.
• a substituted value behaves like an explicitly sent value; a date fallback that matches the stored date is a no-op.
• a selection field without options cannot fall back and keeps clearing semantics.
• fields with allowEmptyValue: true keep the clearing semantics listed above.

Root PUT is different from custom-field patch subresources: when root element replacement includes customFields, the list is treated as replacement state for the current organization's active, writable element custom fields only.

Scope Rules

Custom-field IDs are scoped by organization and placement:

• element custom-field IDs are valid for element values only.
• task custom-field IDs are valid for task values only.
• publication custom-field IDs are valid for publication values only.
• task custom fields can be limited to task formats.
• publication custom fields can be limited to platforms.

When an element is shared across organizations, v2 preserves foreign-organization custom-field values while patching the current organization's values. A current-organization client cannot write foreign-organization custom-field IDs.

Related Migration Notes

For v1 field mappings and client-impacting changes, see Custom-Field Migration.