> ## Documentation Index
> Fetch the complete documentation index at: https://terminal49-vorflux-dev-12120-supported-document-types.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a custom field

> Create a custom field value record in the Terminal49 API, attaching a definition and value to a target shipment, container, or other supported resource.

Use this endpoint to create a custom field value on a shipment or container when you need to send the full JSON:API relationship payload yourself. The field must reference an existing custom field definition.

## Request body

| Parameter                             | Required | Description                                             |
| ------------------------------------- | -------- | ------------------------------------------------------- |
| `data.type`                           | Yes      | Must be `custom_field`                                  |
| `data.attributes.api_slug`            | Yes      | The slug of the custom field definition                 |
| `data.attributes.value`               | Yes      | The field value (must match the definition's data type) |
| `data.relationships.entity.data.type` | Yes      | `shipment` or `container`                               |
| `data.relationships.entity.data.id`   | Yes      | The shipment or container ID                            |

## Value formats by data type

| Data type    | Expected value format                                                                               |
| ------------ | --------------------------------------------------------------------------------------------------- |
| `short_text` | Any string                                                                                          |
| `number`     | Numeric value                                                                                       |
| `date`       | Date string (parsed using definition's `default_format` or flexible parsing)                        |
| `datetime`   | DateTime string                                                                                     |
| `boolean`    | `true` or `false`                                                                                   |
| `enum`       | String matching one of the definition's option values                                               |
| `enum_multi` | Array of strings matching the definition's option values                                            |
| `reference`  | Object identifying the referenced record, for example `{ "type": "shipment", "id": "SHIPMENT_ID" }` |

## Validation

* Values are validated against the definition's data type
* Enum values must match one of the definition's configured options
* Reference values must match the definition's configured `reference_type`
* The `api_slug` must reference a definition belonging to your account or a Terminal49 template

## Example request

```json theme={null}
{
  "data": {
    "type": "custom_field",
    "attributes": {
      "api_slug": "customer_reference_number",
      "value": "ABC124"
    },
    "relationships": {
      "entity": {
        "data": {
          "type": "shipment",
          "id": "YOUR_SHIPMENT_ID"
        }
      }
    }
  }
}
```

## Example response

```json theme={null}
{
  "data": {
    "id": "YOUR_CUSTOM_FIELD_ID",
    "type": "custom_field",
    "attributes": {
      "api_slug": "customer_reference_number",
      "value": "ABC124",
      "display_value": "ABC124"
    },
    "relationships": {
      "entity": {
        "data": {
          "id": "YOUR_SHIPMENT_ID",
          "type": "shipment"
        }
      },
      "definition": {
        "data": {
          "id": "YOUR_DEFINITION_ID",
          "type": "custom_field_definition"
        }
      }
    }
  }
}
```