Кастомные поля

У кастомных полей две половины:

Определения — каталог уровня воркспейса (GET /custom_fields), описывающий каждое поле: его id, name и kind.
Значения — хранятся на задаче, в её массиве custom_fields[], когда вы создаёте (POST /tasks), обновляете (PATCH /tasks/{id}) или читаете (GET /tasks/{id}) задачу.

Вы читаете определение, чтобы узнать kind поля, а затем отправляете соответствующее value-поле на задаче.

Откуда берутся поля и какие из них может иметь задача

Кастомные поля определяются один раз на уровне воркспейса, а затем привязываются к отдельным проектам через настройки проекта в веб-приложении Bordio. API здесь работает только на чтение: вы не можете создать поле, изменить его опции или привязать его к проекту через API — это делают администраторы воркспейса в веб-интерфейсе.

Что это означает при работе с задачами:

Задача может хранить значения только для тех кастомных полей, которые привязаны к её проекту.
Точный набор полей, которые вы можете задать на конкретной задаче, — это то, что возвращает GET /custom_fields?project_id=<project_id задачи>. Считайте этот список источником истины для вопроса «какие поля я могу обновить на этой задаче».
Задание значения для поля, которое не привязано к проекту задачи, отклоняется с 422.
Задача без проекта (уровня воркспейса) вообще не может иметь кастомных полей — см. project_required ниже.

Поэтому рабочий процесс всегда один и тот же: прочитайте поля проекта, затем задавайте значения только для этих полей на задачах в этом проекте. Если кто-то добавит или удалит поле для проекта в веб-приложении, это изменение отразится в GET /custom_fields?project_id=... при следующем чтении.

Определение

curl "https://api.bordio.com/public/v1/custom_fields?project_id=proj_6594a1b2c3d4e5f6a7b8c9d0" \
  -H "Authorization: Bearer brd_sk_live_..."

{
  "data": [
    { "id": "cf_aaa", "name": "Story points", "kind": "number" },
    { "id": "cf_bbb", "name": "Budget", "kind": "currency" },
    { "id": "cf_ccc", "name": "Release", "kind": "dropdown", "allow_multiple": false,
      "options": [
        { "id": "cf_option_x1", "value": "v1.0" },
        { "id": "cf_option_x2", "value": "v2.0" }
      ] },
    { "id": "cf_ddd", "name": "Owners", "kind": "people", "allow_multiple": true }
  ]
}

kind сообщает, какое value-поле использовать на задаче (см. таблицу).
allow_multiple присутствует только для dropdown и people.
options присутствует только для dropdown.
Передайте ?project_id=proj_..., чтобы получить поля, доступные в этом проекте. Без него вы получите полный каталог воркспейса. Поле должно быть доступно в проекте задачи, чтобы его можно было задать на этой задаче.

Как значения хранятся на задаче

На задаче каждое значение — это один элемент в custom_fields[]:

{ "custom_field_id": "cf_aaa", "kind": "number", "number_value": 8 }

При чтении (GET /tasks/{id}) каждый элемент несёт kind и ровно одно заполненное value-поле. Поля без значения полностью опускаются из массива.
При записи (POST / PATCH) отправляйте custom_field_id + то одно value-поле, которое соответствует kind поля. Отправлять kind не нужно — он берётся из определения (если вы его отправите, он игнорируется).

custom_fields в PATCH полностью заменяет массив

PATCH /tasks/{id} с массивом custom_fields заменяет все значения кастомных полей на задаче. Любое поле, которое вы не включили, очищается. Это не merge по отдельным полям.

Полностью опустить custom_fields → все значения кастомных полей остаются без изменений.
Отправить custom_fields: [...] → этот массив становится полным набором значений задачи; всё отсутствующее удаляется.

Поэтому чтобы изменить одно поле, сохранив остальные, отправьте полный набор, который должен оказаться на задаче в итоге.

Значения кастомных полей требуют, чтобы задача принадлежала проекту. Их задание на задаче уровня воркспейса (без project_id) завершается с 422 validation_error (project_required).

Формат значения по kind

kind	Value-поле	Формат
`text`	`text_value`	строка (≤ 10000 символов)
`number`	`number_value`	число
`percent`	`percent_value`	число, где `75` означает 75%
`currency`	`currency_value`	объект `{ "currency": <ISO-4217>, "value": <number> }`
`date`	`date_value`	дата-время ISO-8601 или `YYYY-MM-DD` для даты без времени
`checkbox`	`checkbox_value`	булево значение
`email`	`email_value`	строка (≤ 320)
`phone`	`phone_value`	строка (≤ 40)
`url`	`url_value`	строка (≤ 2048)
`dropdown`	`dropdown_value`	массив id опций (`cf_option_...`)
`people`	`people_value`	массив id пользователей (`user_...`)

Разделы ниже показывают payload записи и форму чтения для каждого kind.

text, email, phone, url

Обычные строки. Различаются только максимальной длиной и назначением (email/phone/url не валидируются API по формату — хранится то, что вы отправили).

// запись
{ "custom_field_id": "cf_txt", "text_value": "Needs design review" }
{ "custom_field_id": "cf_eml", "email_value": "ops@acme.com" }

// чтение
{ "custom_field_id": "cf_txt", "kind": "text", "text_value": "Needs design review" }

number

Любое число (целое или дробное). Без единиц измерения.

// запись
{ "custom_field_id": "cf_pts", "number_value": 8 }

// чтение
{ "custom_field_id": "cf_pts", "kind": "number", "number_value": 8 }

percent

Значение percent — это обычное число, представляющее сам процент: 75 означает 75%, а не 0.75. Допускаются дробные значения (33.5 → 33.5%).

// запись — установить прогресс в 75%
{ "custom_field_id": "cf_prog", "percent_value": 75 }

// чтение
{ "custom_field_id": "cf_prog", "kind": "percent", "percent_value": 75 }

currency

Значение currency — это объект, а не число:

{ "currency": "<ISO-4217 code>", "value": <number> }

currency — код ISO-4217, например USD, EUR, GBP (обязательный).
value — числовая сумма (необязательная; опустите её, чтобы записать валюту без суммы).

// запись — установить бюджет 1990.50 USD
{
  "custom_field_id": "cf_budget",
  "currency_value": { "currency": "USD", "value": 1990.5 }
}

// чтение
{
  "custom_field_id": "cf_budget",
  "kind": "currency",
  "currency_value": { "currency": "USD", "value": 1990.5 }
}

date

Дата-время ISO-8601 или YYYY-MM-DD для даты без времени. При чтении значение «только дата» возвращается как YYYY-MM-DD; дата-время возвращается как полная метка времени ISO-8601.

// запись — только дата
{ "custom_field_id": "cf_due", "date_value": "2026-07-01" }
// запись — дата-время
{ "custom_field_id": "cf_due", "date_value": "2026-07-01T09:00:00.000Z" }

// чтение
{ "custom_field_id": "cf_due", "kind": "date", "date_value": "2026-07-01" }

checkbox

Булево значение.

// запись
{ "custom_field_id": "cf_billable", "checkbox_value": true }

// чтение
{ "custom_field_id": "cf_billable", "kind": "checkbox", "checkbox_value": true }

Массив id опций (cf_option_...), взятых из options поля в его определении. Отправляйте массив из одного элемента, если только в определении нет allow_multiple: true.

// запись — одиночный выбор
{ "custom_field_id": "cf_release", "dropdown_value": ["cf_option_x1"] }
// запись — множественный выбор (только при allow_multiple)
{ "custom_field_id": "cf_release", "dropdown_value": ["cf_option_x1", "cf_option_x2"] }

// чтение
{ "custom_field_id": "cf_release", "kind": "dropdown", "dropdown_value": ["cf_option_x1"] }

Каждый id опции должен принадлежать именно этому полю, иначе запрос завершится с 422 validation_error (custom_field_invalid_option).

people

Массив id пользователей (user_...). Каждый должен быть участником воркспейса. Один элемент, если только в определении нет allow_multiple: true.

// запись
{ "custom_field_id": "cf_owners", "people_value": ["user_abc", "user_def"] }

// чтение
{ "custom_field_id": "cf_owners", "kind": "people", "people_value": ["user_abc", "user_def"] }

Разобранный пример: задать несколько полей на задаче

curl -X PATCH https://api.bordio.com/public/v1/tasks/task_6a2918cff58b0a1d387866ee \
  -H "Authorization: Bearer brd_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "custom_fields": [
      { "custom_field_id": "cf_prog",   "percent_value": 75 },
      { "custom_field_id": "cf_budget", "currency_value": { "currency": "USD", "value": 1990.5 } },
      { "custom_field_id": "cf_release","dropdown_value": ["cf_option_x1"] }
    ]
  }'

Читаем задачу обратно:

// GET /tasks/task_6a2918cff58b0a1d387866ee
{
  "data": {
    "id": "task_6a2918cff58b0a1d387866ee",
    "title": "Ship the API",
    "custom_fields": [
      { "custom_field_id": "cf_prog",    "kind": "percent",  "percent_value": 75 },
      { "custom_field_id": "cf_budget",  "kind": "currency", "currency_value": { "currency": "USD", "value": 1990.5 } },
      { "custom_field_id": "cf_release", "kind": "dropdown", "dropdown_value": ["cf_option_x1"] }
    ]
  }
}

Очистка значений

Поскольку custom_fields работает по принципу полной замены массива, оставьте поле вне массива, чтобы очистить его — но помните, что нужно включить все остальные поля, которые вы хотите сохранить.

// сейчас на задаче есть cf_prog, cf_budget, cf_release.
// Этот PATCH сохраняет cf_prog и cf_budget и очищает cf_release:
{
  "custom_fields": [
    { "custom_field_id": "cf_prog",   "percent_value": 75 },
    { "custom_field_id": "cf_budget", "currency_value": { "currency": "USD", "value": 1990.5 } }
  ]
}

Чтобы очистить все кастомные поля, отправьте "custom_fields": [].

Ошибки валидации

Ситуация	HTTP	code
Кастомные поля заданы на задаче без проекта	422	`project_required`
Id опции dropdown не определён на этом поле	422	`custom_field_invalid_option`
Поле недоступно в проекте задачи	422	`validation_error`
Значение people ссылается на не-участника	422	`validation_error`

Все они несут стандартную обёртку ошибки — см. Ошибки.