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

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