Skip to main content
Custom fields add your own structured data to projects: a request reference, the requester, a link to the brief, or the markets a request is for. You define each field once for the workspace, then set values on projects. Select fields offer a fixed list of options, so every project uses the same spelling.

Base URL and authentication

Send a personal access token in the x-api-key header.

Field types

Option values match ignoring case. A field’s key and type cannot change after you create it. A workspace has at most 200 fields, and a select field at most 500 options.

Define a field

The key starts with a lowercase letter and uses lowercase letters, digits, and underscores. Every route that takes {fieldId} also accepts the key, so GET /v1/custom-fields/markets/options lists that field’s options.

Change options

PATCH /v1/custom-fields/{fieldId} with options replaces the whole list, in display order:
  • An entry with id keeps that option and renames it to value. Projects that chose it keep their choice.
  • An entry without id adds an option.
  • Options you leave out are removed, along with every project’s choice of them.
Deleting a field removes every project’s value for it.

Set values on a project

PUT /v1/projects/{projectId}/custom-fields sets the fields you name, keyed by field key or ID. null clears a value, and fields you leave out keep theirs:
The response, like GET on the same path, lists the values set on the project:
A request with any invalid value changes nothing and returns 400 with invalid_body; the message names the field, for example customFields.markets: "Mars" is not an option of this field.

Set values when you create a project

POST /v1/projects accepts the same customFields object, so a request’s project gets its reference and links in the call that creates it, including from a project template:
If a value is invalid, the project is not created.

Next