Skip to main content
POST
/
material-sourcing
Create a material sourcing step
curl --request POST \
  --url https://api.demo.cula.earth/tracking/v1/material-sourcing \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Cula-Organisation-Id: <cula-organisation-id>' \
  --data '
{
  "external_id": "GC-HARVEST-2026-001",
  "config_id": "stc_01kqzcjrpyf27tgeeekpvvx0zt",
  "site": {
    "external_id": "GC-SITE-REFINERY"
  },
  "executed_at": "2026-05-01T14:30:00-05:00",
  "data_points": [
    {
      "config_id": "dpc_01kqzcjrpyf27tgeu1hkzm2wxp",
      "input_value": "GC-LOT-2026-0501"
    },
    {
      "config_id": "dpc_01kqzcjrpyf27tgeu3a94z1yhz",
      "input_value": "Ackerman Farms (James)"
    },
    {
      "config_id": "dpc_01kqzcjrpyf27tgeu5b05a2cbs",
      "input_value": 0.154
    }
  ],
  "output_containers": [
    {
      "data_points": [
        {
          "config_id": "dpc_01kqzcjrpyf27tgeu7c16b3dct",
          "input_value": {
            "value": 52080,
            "unit": "lbs"
          }
        },
        {
          "config_id": "dpc_01kqzcjrpyf27tgeu9d27c4edu",
          "input_value": {
            "value": 47080,
            "unit": "lbs"
          }
        }
      ]
    }
  ],
  "file_ids": []
}
'
{
  "id": "stp_01kqzcjrpxf27tge33jwvjhkff",
  "external_id": "GC-HARVEST-2026-001",
  "config_id": "stc_01kqzcjrpyf27tgeeekpvvx0zt",
  "config_version_id": "scv_01kqzcjrpyf27tgefhb58rc9d4",
  "display_key": "GC-HARVEST-2026-001",
  "site": {
    "id": "ste_01kqzcjrpyf27tge6smsbnhkh5",
    "external_id": "GC-SITE-REFINERY"
  },
  "executed_at": "2026-05-01T19:30:00Z",
  "data_points": [
    {
      "config_id": "dpc_01kqzcjrpyf27tgeu1hkzm2wxp",
      "config_version_id": "dpv_01kqzcjrpyf27tgeuv1hkzm2wxp",
      "name": "Lot number",
      "input_value": "GC-LOT-2026-0501",
      "result_value": "GC-LOT-2026-0501"
    },
    {
      "config_id": "dpc_01kqzcjrpyf27tgeu3a94z1yhz",
      "config_version_id": "dpv_01kqzcjrpyf27tgeuv3a94z1yhz",
      "name": "Supplier name",
      "input_value": "Ackerman Farms (James)",
      "result_value": "Ackerman Farms (James)"
    },
    {
      "config_id": "dpc_01kqzcjrpyf27tgeu5b05a2cbs",
      "config_version_id": "dpv_01kqzcjrpyf27tgeuv5b05a2cbs",
      "name": "Moisture content",
      "input_value": 0.154,
      "result_value": 0.154
    }
  ],
  "output_containers": [
    {
      "id": "mct_01kqzcjrpyf27tgenyy2stmy5z",
      "data_points": [
        {
          "config_id": "dpc_01kqzcjrpyf27tgeu7c16b3dct",
          "config_version_id": "dpv_01kqzcjrpyf27tgeuv7c16b3dct",
          "name": "Weight gross",
          "input_value": {
            "value": 52080,
            "unit": "lbs"
          },
          "result_value": {
            "value": 23621.58,
            "unit": "kg"
          }
        },
        {
          "config_id": "dpc_01kqzcjrpyf27tgeu9d27c4edu",
          "config_version_id": "dpv_01kqzcjrpyf27tgeuv9d27c4edu",
          "name": "Weight net",
          "input_value": {
            "value": 47080,
            "unit": "lbs"
          },
          "result_value": {
            "value": 21353.12,
            "unit": "kg"
          }
        }
      ],
      "contents": [
        {
          "material": {
            "id": "mat_01kqzcjrpyf27tge9dnvsqv8t2"
          },
          "weight_in_kg": 21353.12
        }
      ]
    }
  ],
  "file_ids": [],
  "created_at": "2026-05-06T19:34:00Z",
  "updated_at": "2026-05-06T19:34:00Z"
}

Authorizations

​
Authorization
string
header
required

OAuth2 client credentials flow. Exchange your client_id and client_secret for a short-lived access token, then pass it as a Bearer token in the Authorization header.

Headers

​
Cula-Organisation-Id
string
required

Organisation ID that scopes this request. The authenticated consumer must be authorized for this organisation. Omitting this header returns 400; passing an unauthorised org returns 403.

Body

application/json

Request body for creating a material sourcing step.

​
config_id
string
required

Root step config ID. The server resolves to the active config version. Discover available configs via the config list endpoint.

​
site
object
required

The site where the step was executed.

Example:
{ "id": "ste_01kqzcjrpyf27tge6smsbnhkh5" }
​
executed_at
string<date-time>
required

When the step was executed. ISO-8601 with explicit UTC offset required. Offset-less timestamps are rejected with 422.

​
external_id
string

Partner-assigned identifier. Must be unique within resource type and organisation. Used for idempotency and ext- lookups.

​
display_key
string

Human-readable display identifier.

​
location
object

Optional override location. Set this if the step was executed at a different physical location than the site (e.g. a remote field or temporary storage). Cula uses the distance to attribute additional transport emissions automatically.

​
data_points
object[]

Step-level data points.

​
file_ids
string[]

Complete set of file IDs to attach to this resource when creating it or replacing it with PUT.

​
output_containers
object[]

Output material containers. At least one required. Each container carries its own data points. The server computes material contents from the data point values based on the config.

Minimum array length: 1

Response

Material sourcing step created.

A material sourcing step as returned in responses.

​
id
string
required

Cula-assigned TypeID.

Example:

"stp_01kqzcjrpxf27tge33jwvjhkff"

​
config_id
string
required

Root step config ID.

Example:

"stc_01kqzcjrpyf27tgeeekpvvx0zt"

​
config_version_id
string
required
read-only

Resolved config version used at creation time.

Example:

"scv_01kqzcjrpyf27tgefhb58rc9d4"

​
site
object
required

A resolved resource reference as returned in responses.

​
executed_at
string<date-time>
required

When the step was executed. Stored and returned in UTC.

Example:

"2026-05-01T19:30:00Z"

​
data_points
object[]
required

Step-level resolved data points.

​
file_ids
string[]
required

IDs of files linked to this resource.

Example:
[]
​
created_at
string<date-time>
required
read-only
Example:

"2026-05-06T19:34:00Z"

​
updated_at
string<date-time>
required
read-only
Example:

"2026-05-06T19:34:00Z"

​
output_containers
object[]
required

Output material containers with resolved data points and computed contents.

​
external_id
string | null

Partner-assigned external identifier.

Example:

"GC-HARVEST-2026-001"

​
display_key
string | null

Human-readable display identifier.

Example:

"GC-HARVEST-2026-001"

​
location
object

Override location. If the step was executed at a different physical location than the site, this field captures those coordinates. Cula attributes additional transport emissions for the distance between the site and this location.