Create a Custom Field

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

{
  "data": {
    "type": "custom_field",
    "attributes": {
      "api_slug": "customer_reference_number",
      "value": "ABC124"
    },
    "relationships": {
      "entity": {
        "data": {
          "type": "shipment",
          "id": "YOUR_SHIPMENT_ID"
        }
      }
    }
  }
}

Example response

{
  "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"
        }
      }
    }
  }
}

Tracking Requests

Shipments

Containers

Documents

Email Submissions

Document Schemas

Document Representations

Search

Webhooks

Webhook Notifications

Custom Field Definitions

Custom Field Options

Custom Fields

Shipping Lines

Metro Areas

Ports

Vessels

Terminals

Parties

Request body

Value formats by data type

Validation

Example request

Example response

​Request body

​Value formats by data type

​Validation

​Example request

​Example response

Request body

Value formats by data type

Validation

Example request

Example response