Skip to main content
Configurable fields in the Cula Tracking API are data points. Each data point is identified by config_id, the stable root ID of its data point config.

​
Data point configs

Data points are never standalone — they belong to a parent object (step, delivery, emission log) or a nested child (payload container, input/output container). The parent’s config declares which data points exist via data_point_configs arrays at each nesting level (see nesting structure). Each config entry declares:
  • type — determines the shape of input_value (see data point types).
  • accepts_input — whether values can be submitted for this data point.
  • is_mandatory — whether the data point must be provided to complete the resource.
  • default_input_value — optional value the server uses when you omit this data point.
Example config snippet
{
  "data_point_configs": [
    {
      "id": "dpc_01abc...",
      "name": "Weight gross",
      "type": "amount",
      "accepts_input": true,
      "is_mandatory": true,
      "default_input_value": { "value": 0, "unit": "kg" },
      "amount_base": "weight"
    },
    {
      "id": "dpc_01def...",
      "name": "Weight net",
      "type": "amount",
      "accepts_input": false,
      "is_mandatory": true
    }
  ]
}
Discover available configs through the parent resource’s config version endpoint (e.g. GET /v1/delivery-configs/{id}/versions/active).

​
accepts_input

  • true — you can submit a value via input_value.
  • false — server-computed from other data points or dependencies. Read-only.
Submitting a value for an accepts_input: false data point returns a validation error.

​
default_input_value

Some data point configs include default_input_value. If you omit that data point from the request, the server pre-fills the data point with the configured default.
Config with a default
{
  "id": "dpc_01abc...",
  "name": "Vehicle count",
  "type": "number",
  "accepts_input": true,
  "is_mandatory": true,
  "default_input_value": 1
}
For a data point with this config, both of these create requests are valid: 
{
  "data_points": []
}
Defaults use the same shape as input_value for the data point type. For example, an amount default is an amount object: 
{
  "default_input_value": { "value": 500, "unit": "kg" }
}
If a mandatory data point has no default_input_value, include it in the request. If a data point has accepts_input: false, do not submit it even if it appears in the config.

​
Input format

When creating or updating a resource, send provided data points as an array of DataPointInput objects: 
{
  "data_points": [
    { "config_id": "dpc_01abc...", "input_value": 42 },
    { "config_id": "dpc_01def...", "input_value": { "value": 500, "unit": "kg" } }
  ]
}
Each object in the array must include both config_id and input_value. To use a config default, omit the whole data point object instead of sending a partial object.

​
Response format

Responses return each data point as a DataPoint object with server-resolved fields: 
{
  "data_points": [
    {
      "config_id": "dpc_01abc...",
      "config_version_id": "dpc_01abc_v2...",
      "name": "Moisture content",
      "input_value": 0.154,
      "result_value": 0.154
    },
    {
      "config_id": "dpc_01def...",
      "config_version_id": "dpc_01def_v1...",
      "name": "Weight",
      "input_value": { "value": 500, "unit": "lbs" },
      "result_value": { "value": 226.796, "unit": "kg" }
    }
  ]
}
  • name — human-readable label from the config.
  • input_value — the value you submitted.
  • result_value — the server-normalized result (e.g. unit conversion from lbs to kg).

​
Data point types

Typeinput_value typeNotes
short_textstringSingle-line text
long_textstringMulti-line text
multi_textstring[]Array of strings
numbernumberNumeric value
percentagenumber0–1
durationnumberDuration in milliseconds
booleanboolean
amount{ value, unit }Amount object — see Amounts and units
timestampstringISO-8601 datetime
materialResourceRef{ id } or { external_id } — see resource identity
container_typeResourceRef{ id } or { external_id } — see resource identity

​
Validation

A data point config may carry an optional validation object. The shape depends on the data point’s type. All validation keys are optional — omit validation entirely if you do not need it. When set, the server rejects any input_value that does not satisfy the constraints.
Data point typevalidation shape (all keys optional)
short_text, long_text{ "max_length": integer }
multi_text{ "min_number_of_items": integer }
number{ "min": number, "max": number }
percentage{ "min": number, "max": number } — values are in the 0..1 scale and an implicit 0..1 cap is always applied; custom min/max may further restrict it.
amount{ "min": Amount, "max": Amount } — Amount is { value, unit }, see Amounts and units.
timestamp{ "min": "ISO-8601", "max": "ISO-8601", "must_be_in_past": boolean, "must_be_in_future": boolean }
duration{ "min": number, "max": number } — milliseconds.
boolean{ "must_be_true": boolean, "must_be_false": boolean }
Other data point types (material, container_type) do not currently expose validation.
Amount min/max
{
  "id": "dpc_01abc...",
  "name": "Weight gross",
  "type": "amount",
  "amount_base": "weight",
  "validation": {
    "min": { "value": 0, "unit": "kg" },
    "max": { "value": 50000, "unit": "kg" }
  }
}
Percentage 0–0.5
{
  "id": "dpc_01def...",
  "name": "Moisture content",
  "type": "percentage",
  "validation": { "min": 0, "max": 0.5 }
}

​
Nesting structure

Data points and their configs are nested at the level of the entity that owns them. The config mirrors the runtime structure — each level that carries data_points at runtime has a corresponding data_point_configs array in the config.
  • Steps — step-level data points, plus container-level data points on input and output containers.
  • Deliveries — delivery-level, leg-level, and payload-level data points.
  • Emission logs — flat list of data points at the log level.
// Step config
{
  "data_point_configs": [...],
  "input_config": {
    "data_point_configs": [...]
  },
  "output_config": {
    "data_point_configs": [...]
  }
}

// Delivery config
{
  "data_point_configs": [...],
  "selectable_transport_emission_log_configs": [
    { "data_point_configs": [...] }
  ],
  "payload_config": {
    "data_point_configs": [...]
  }
}