---
title: "Creates a new custom field definition."
method: POST
path: "/customfielddefinitions"
tags: ["customFields"]
---

# Creates a new custom field definition.

`POST /customfielddefinitions`

Creates a new custom field definition. This custom field definition can then be linked to project templates and to tasks.

<Check title="Required Permissions" icon="key">The user must be an admin or have `project-manage-config:write` permissions.</Check>

## Headers

- `Authorization` string, required

## Request body

- CustomFieldDefinitionPostForm
  - `name` string, required — The name of the custom field definition.
  - `type` 'text' | 'number' | 'date' | 'datetime' | 'select' | 'coloredSelect' | 'link' | 'boolean' | 'user' | 'client', required — The type of the custom field definition.
  - `selectionOptions` CustomFieldSelectionOptionsForm[], nullable — The selection options for the custom field definition. Can only be used if the type is 'select'.
    - `value` string, required — The selection value which can be used in a select custom field.
    - `color` 'red' | 'orange' | 'yellow' | 'green' | 'cyan' | 'blue' | 'indigo' | 'purple' | 'steel' — The color of the selection option.
    - `order` number, double, required — The order of the custom field selection option.
  - `order` number, double, nullable — The order of the custom field definition. This value is only used (and required) if the entity is 'project', as the project custom field definitions are globally ordered. To set the order for task custom field definitions, use the endpoint to update the order of a custom field definition for a project/project template.
  - `entity` 'task' | 'project', required — The entity the custom field definition can be linked to.

## Response `200`

OK

- CustomFieldDefinitionWithSelectionOptions
  - `id` string, uuid — The id of the custom field definition.
  - `name` string, nullable — The name of the custom field definition.
  - `entity` 'task' | 'project' — The entity the custom field definition can be linked to.
  - `type` 'text' | 'number' | 'date' | 'datetime' | 'select' | 'coloredSelect' | 'link' | 'boolean' | 'user' | 'client' — The type of the custom field definition.
  - `createdOn` string, date-time — The date this entity was created.
  - `createdBy` string, uuid — The id of the user who created this entity.
  - `updatedOn` string, date-time — The date this entity was last modified.
  - `updatedBy` string, uuid — The id of the user who last modified this entity.
  - `order` number, double, nullable — If it's a project custom field, it's the global order of the custom field definition. Otherwise, it's the order of the custom field definition within a project template or a project.
  - `isExternal` boolean — True if this entity is coming from an external workspace (awork Connect).
  - `selectionOptions` CustomFieldSelectionOption[], nullable — The selection options for this custom field definition.
    - `id` string, uuid — The id of the custom field selection option.
    - `value` string, required — The selection value which can be later used in a select custom field.
    - `color` 'red' | 'orange' | 'yellow' | 'green' | 'cyan' | 'blue' | 'indigo' | 'purple' | 'steel' — The color of the selection option.
    - `order` number, double — The order of the custom field selection option.

## Other responses

- `400` — Bad Request

---

[API](https://skmtc.net/awork-io/apis/api-v1-reference.md) · [All operations](https://skmtc.net/awork-io/apis/api-v1-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/awork-io/api-v1-reference/versions/f784a53f60df/schema)