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."
    ]
  }
}