> ## 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 tracking request custom field

> Create or update a custom field value on a tracking request in the Terminal49 API. Attach internal metadata like references, intake tags, or workflow flags.

Creates or updates a custom field on a tracking request. If a custom field with the specified `api_slug` already exists, it will be updated.

## Path parameters

| Parameter             | Required | Description                    |
| --------------------- | -------- | ------------------------------ |
| `tracking_request_id` | Yes      | The ID of the tracking request |

## 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 value to set (type depends on the definition's data type) |

The tracking request is implied by the path, so do not send `data.relationships.entity` on this endpoint.

## Authorization

Requires `update` permission on the tracking request.

## Response

Returns `201 Created` with the custom field resource on success.

## Behavior

* Uses `find_or_initialize_by` internally, so it creates if missing or updates if it exists
* Values are validated against the definition's data type
* For enum fields, values are validated against the definition's options

## Example request

```json theme={null}
{
  "data": {
    "type": "custom_field",
    "attributes": {
      "api_slug": "customer_reference_number",
      "value": "ABC124"
    }
  }
}
```

## 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_TRACKING_REQUEST_ID",
          "type": "tracking_request"
        }
      },
      "definition": {
        "data": {
          "id": "YOUR_DEFINITION_ID",
          "type": "custom_field_definition"
        }
      }
    }
  }
}
```