> ## Documentation Index > Fetch the complete documentation index at: https://terminal49.com/docs/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" } } } } } ``` ## OpenAPI ````yaml post /custom_fields openapi: 3.0.0 info: title: Terminal49 API Reference version: 0.2.0 contact: name: Terminal49 API support url: https://www.terminal49.com email: support@terminal49.com description: >- The Terminal 49 API offers a convenient way to programmatically track your shipments from origin to destination. Please enter your API key into the "Variables" tab before using these endpoints within Postman. x-label: Beta termsOfService: https://www.terminal49.com/terms servers: - url: https://api.terminal49.com/v2 description: Production security: - authorization: [] tags: - name: Containers - name: Custom Field Definitions - name: Custom Field Options - name: Custom Fields - name: Shipments - name: Locations - name: Events - name: Tracking Requests - name: Webhooks - name: Webhook Notifications - name: Ports - name: Metro Areas - name: Terminals - name: Routing (Paid) - name: Documents - name: Email Submissions - name: Document Schemas - name: Search paths: /custom_fields: post: tags: - Custom Fields summary: Create a custom field operationId: post-custom-fields requestBody: content: application/json: schema: type: object properties: data: type: object required: - type - attributes - relationships properties: type: type: string enum: - custom_field attributes: type: object required: - api_slug - value properties: api_slug: type: string value: $ref: '#/components/schemas/custom_field_value' relationships: type: object properties: entity: type: object properties: data: type: object required: - type - id properties: type: type: string enum: - shipment - container id: type: string format: uuid example: data: type: custom_field attributes: api_slug: customer_reference_number value: ABC124 relationships: entity: data: type: shipment id: YOUR_SHIPMENT_ID responses: '201': description: Created content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/custom_field' links: $ref: '#/components/schemas/link-self' components: schemas: custom_field_value: description: Raw custom field value (type depends on definition) nullable: true oneOf: - type: string - type: number - type: boolean - type: array items: type: string - type: object custom_field: title: Custom field type: object properties: id: type: string format: uuid type: type: string enum: - custom_field attributes: type: object properties: api_slug: type: string value: $ref: '#/components/schemas/custom_field_value' display_value: type: string nullable: true description: Formatted value for display required: - api_slug relationships: type: object properties: entity: type: object properties: data: type: object properties: type: type: string enum: - shipment - container - tracking_request id: type: string format: uuid required: - type - id definition: type: object properties: data: type: object properties: type: type: string enum: - custom_field_definition id: type: string format: uuid required: - type - id required: - id - type link-self: title: link type: object properties: self: type: string format: uri securitySchemes: authorization: name: Authorization type: apiKey in: header description: >- Use a Terminal49 API key in the `Authorization` header with the `Token` prefix. `Authorization: Token YOUR_API_KEY` ````