---
title: "Create a custom field definition"
method: POST
path: "/v1/custom-field-definitions"
tags: ["Custom Fields"]
---

# Create a custom field definition

`POST /v1/custom-field-definitions`

## Request

- Base URL: `https://api.workwing.io`
- URL: `https://api.workwing.io/v1/custom-field-definitions`
- Auth: HTTP bearer

Define a new custom field on jobs, customers or resources for your whole organisation. Requires `create:custom_field_definitions`.

`entity_type`, `field_key` and `field_type` are fixed once created. `is_required` defaults to false; `is_searchable` and `is_filterable` default to true. The new field appears in the layout and form builder palettes; placing it on a form is done in the web app.

Returns 409 when a field with the same key already exists on that entity.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `entity_type` 'T_JOB' | 'T_CUSTOMER' | 'T_RESOURCE', required
  - `field_key` string, required: Stable key the value is stored against (lowercase letters, digits, underscores)
  - `field_type` 'T_TEXT' | 'T_TEXTAREA' | 'T_NUMBER' | 'T_DATE' | 'T_DATETIME' | 'T_BOOLEAN' | 'T_SELECT' | 'T_MULTISELECT' | 'T_URL' | 'T_EMAIL' | 'T_PHONE' | 'T_SCANNER', required
  - `field_label` string, required
  - `field_description` string, nullable
  - `display_section` string, nullable
  - `is_required` boolean
  - `is_searchable` boolean
  - `is_filterable` boolean
  - `field_config` object: Type-specific settings: minLength/maxLength/pattern for text, min/max/step/unit for numbers, minDate/maxDate for dates, options for select and multiselect, allowedBarcodeTypes/scannerHint for scanner.

## Response `201`

Default Response

- object
  - `data` object, required
    - `id` string, uuid, required
    - `entity_type` 'T_JOB' | 'T_CUSTOMER' | 'T_RESOURCE', required
    - `template_id` string, uuid, nullable, required: Set when the field belongs to one job type (defined in the form builder). Null for tenant-wide fields, which is every field created over the API.
    - `field_key` string, required
    - `field_label` string, required
    - `field_description` string, nullable, required
    - `field_type` 'T_TEXT' | 'T_TEXTAREA' | 'T_NUMBER' | 'T_DATE' | 'T_DATETIME' | 'T_BOOLEAN' | 'T_SELECT' | 'T_MULTISELECT' | 'T_URL' | 'T_EMAIL' | 'T_PHONE' | 'T_SCANNER', required
    - `field_config` object, nullable, required: Type-specific settings: minLength/maxLength/pattern for text, min/max/step/unit for numbers, minDate/maxDate for dates, options for select and multiselect, allowedBarcodeTypes/scannerHint for scanner.
    - `display_order` integer, nullable, required
    - `display_section` string, nullable, required
    - `display_width` 'T_FULL' | 'T_HALF' | 'T_THIRD' | 'null', nullable, required
    - `is_required` boolean, nullable, required
    - `is_active` boolean, nullable, required
    - `is_searchable` boolean, nullable, required
    - `is_filterable` boolean, nullable, required
    - `created_at` string, date-time, nullable, required
    - `updated_at` string, date-time, nullable, required
    - `created_by_user_id` string, uuid, nullable, required
  - `meta` object, required
    - `request_id` string, required
    - `timestamp` string, date-time, required

---

[API](https://skmtc.dev/workwing/apis/workwing-api.md) · [All operations](https://skmtc.dev/workwing/apis/workwing-api/llms.txt) · [OpenAPI document](https://skmtc.dev/workwing/apis/workwing-api/revisions/54bb14368a35?raw)