Adding Additional Fields

What are additional fields?

Additional fields are optional fields you can enable and populate when you need to store customer-specific or workflow-specific data that is not part of the default OpenTrack data model.

Additional field values can be provided by customers in two ways:

• Bulk upload templates
• API fields

Once enabled, these fields behave like first-class metadata and can be used for searching, filtering, reporting, and integrations.

Enabling additional fields for API use

Additional fields must be enabled on your account before they can be used via the API.

To enable fields for API usage:

1. Go to Settings
2. Select Additional fields
3. Enable the fields you plan to send via the API
4. Save your changes

If an additional field is sent via the API before it is enabled, it will be ignored.

Sending additional fields via the API

Additional fields are sent as key-value pairs using their Field ID.

Example payload

{
  "containerNumber": "OOLU9780604",
  "referenceNumbers": {
    "bookingDate": "01/01/25",
    "poNumber": "PO1234",
    "movementCost": 455.23,
    "factory": "ABC Co, Development Inc.",
    "hotContainer": "Yes"
  }
}

Notes:

• Field IDs are case-sensitive
• Values should match the expected data format
• Fields must be enabled on the account to be accepted

Important: referenceNumbers vs customFields

OpenTrack supports two different “additional field” concepts in the API. They are similar in spirit, but they apply at different levels and should be used for different mapping needs.

Reference numbers

Reference numbers apply to the whole booking or master bill (MBL).

They should be used when the value applies to the shipment overall and should flow to all associated containers.

Example payload

{
  "masterBillNumber": "MEDUHW603714",
  "referenceNumbers": {
    "poNumber": "PO1234",
    "bookingDate": "01/01/25",
    "factory": "ABC Co, Development Inc.",
    "customer": "Customer1"
  }
}

Custom fields

Custom fields should only be sent only on the /containersendpoint and apply only to the container being created or updated.

Use these when the value is container-specific.

Example payload

{
  "containerNumber": "TEMU9663268",
  "customFields": {
    "confirmedSealNumber": "SEAL123",
    "confirmedChassisNumber": "AIMZ843024"
  }
}

Rule of thumb

• If the field should be identical for every container tied to the booking or MBL, use reference numbers.
• If the field can vary container by container, use custom fields.

Supported additional fields

Best practices

• Enable only the fields you actively use
• Keep naming consistent with upstream systems
• Avoid overloading fields with multiple meanings
• Use arrays or comma-separated values consistently for multi-value fields