Skip to content
Optiwork API Docs

Create a custom field definition on a board

POST
/boards/{board}/custom-fields/definitions
curl --request POST \
  --url https://projects.work.optidata.cloud/api/boards/1/custom-fields/definitions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Priority", "type": "select", "description": "Business priority of the task", "is_required": false, "config": { "options": [ { "label": "High", "color": "#ef4444" }, { "label": "Low", "color": "#22c55e" } ] } }'

Defines a new custom field for this board’s cards. name must be unique within the board. config is type-specific (e.g. select options, number format, text max length) and is validated against the chosen type.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
board
required
integer

Board id.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required

Unique within the board (or among global definitions).

string
>= 1 characters <= 60 characters
type
required
string
Allowed values: text number select checkbox date person
description
string | null
<= 250 characters
config

Type-specific configuration; validated against the chosen type.

object | null
is_required
boolean
Example
{
  "name": "Priority",
  "type": "select",
  "description": "Business priority of the task",
  "is_required": false,
  "config": {
    "options": [
      {
        "label": "High",
        "color": "#ef4444"
      },
      {
        "label": "Low",
        "color": "#22c55e"
      }
    ]
  }
}

Responses

Section titled “ Responses ”

201

Section titled “201”

The created definition.

Media typeapplication/json

Definition of a custom field. board_id null (and is_global true) means tenant-wide.

object
id
integer
board_id
integer | null
name
string
>= 1 characters <= 60 characters
type
string
Allowed values: text number select checkbox date person
description
string | null
<= 250 characters
config

Type-specific configuration. Examples — text: {multiline, max_length, placeholder, default_value}; select: {options: [{id, label, color}]}; checkbox: {default_value}.

object | null
order
integer
is_required

Required fields block card interactions (comments, files, timers) until filled.

boolean
is_active
boolean
is_global
boolean
created_at
string format: date-time
updated_at
string format: date-time
deleted_at
string | null format: date-time
Example
{
  "type": "text"
}

401

Section titled “401”

Missing, invalid or expired bearer passport.

Media typeapplication/json
object
error
string
Example
{
  "error": "JWT passport exception: Missing bearer token in request"
}

403

Section titled “403”

The authenticated user lacks the required board permission.

Media typeapplication/json
object
message
string
Example
{
  "message": "This action is unauthorized."
}

404

Section titled “404”

Resource not found, or a nested resource does not belong to its parent in the path.

Media typeapplication/json
object
message
string
Example
{
  "message": "Not found."
}

422

Section titled “422”

Validation failed.

Media typeapplication/json
object
message

First validation error message.

string
errors

Map of field name → list of error messages.

object
key
additional properties
Array<string>
Example
{
  "message": "The name field is required.",
  "errors": {
    "name": [
      "The name field is required."
    ]
  }
}