---
title: "Create a custom field definition"
method: POST
path: "/custom_field_definitions"
tags: ["Custom Field Definitions"]
---

# Create a custom field definition

`POST /custom_field_definitions`

## Request body

- object
  - `data` object
    - `type` 'custom_field_definition', required
    - `attributes` object, required
      - `entity_type` 'Shipment' | 'Container', required
      - `api_slug` string, required
      - `display_name` string, required
      - `description` string, nullable
      - `data_type` 'short_text' | 'number' | 'date' | 'datetime' | 'boolean' | 'enum' | 'enum_multi' | 'reference', required
      - `reference_type` string, nullable
      - `validation` object, nullable
      - `default_format` string, nullable
      - `default_value` union — Raw custom field value (type depends on definition)
        - string
        - number
        - boolean
        - string[]
        - object

## Response `201`

Created

- object
  - `data` CustomFieldDefinition
    - `id` string, uuid, required
    - `type` 'custom_field_definition', required
    - `attributes` object
      - `entity_type` 'Shipment' | 'Container' | 'TrackingRequest', required
      - `api_slug` string, required
      - `display_name` string, required
      - `description` string, nullable
      - `data_type` 'short_text' | 'number' | 'date' | 'datetime' | 'boolean' | 'enum' | 'enum_multi' | 'reference', required
      - `reference_type` string, nullable
      - `validation` object, nullable
      - `default_format` string, nullable
      - `default_value` union — Raw custom field value (type depends on definition)
        - string
        - number
        - boolean
        - string[]
        - object
  - `links` LinkSelf
    - `self` string, uri

## Changes

- **2026-07-02** `3857867d53f2` — 1 breaking, 1 warning, 2 info
  - removed the enum value `Cargo` of the request property `data/attributes/entity_type`
  - added the new `Container` enum value to the `data/attributes/entity_type` response property for the response status `201`
  - added the new `Container` enum value to the request property `data/attributes/entity_type`
  - removed the `Cargo` enum value from the `data/attributes/entity_type` response property for the response status `201`
- **2026-05-20** `3b798d71b259` — 1 breaking, 1 warning, 2 info
  - removed the enum value `Container` of the request property `data/attributes/entity_type`
  - added the new `Cargo` enum value to the `data/attributes/entity_type` response property for the response status `201`
  - added the new `Cargo` enum value to the request property `data/attributes/entity_type`
  - removed the `Container` enum value from the `data/attributes/entity_type` response property for the response status `201`
- …earlier changes not shown

[Full history](https://skmtc.dev/terminal49/apis/terminal49-api-reference/changes/custom_field_definitions/post.md)

---

[API](https://skmtc.dev/terminal49/apis/terminal49-api-reference.md) · [All operations](https://skmtc.dev/terminal49/apis/terminal49-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/terminal49/terminal49-api-reference/revisions/7350d6a26239/schema)