Skip to main content
POST
Create a material utilization

Authorizations

Authorization
string
header
required

OAuth 2.0 client credentials. Exchange your client_id and client_secret for an access token scoped to the organisation that provides data access.

Headers

Cula-Organisation-Id
string
required

ID of the organisation the request operates on behalf of (e.g. org_...). Must be an organisation the API client has access to.

Example:

"org_01k83mfmhgchya944v86ryvhpq"

Body

application/json
config_id
string
required

The ID of the material utilization config that defines the utilization to create.

Example:

"mutc_01k16bap2kcz0asd2h2dkzz1xj"

occurred_at
string<date-time>

When the utilization took place: an ISO 8601 date-time with an explicit UTC offset (Z or ±hh:mm). Defaults to now if omitted.

Example:

"2026-01-15T08:00:00Z"

external_id
string

An optional custom ID that can be set to an internal ID from your system. This ID must be unique within all objects of the organisation you operate in. You can later use this external ID to reference and query this object. Be aware that you can update this ID later. If you need an immutable ID, use the object ID returned when creating the object.

Required string length: 1 - 100
Pattern: ^[A-Za-z0-9\-_]+$
Example:

"MY-CUSTOM-ID"

site
object

The site the material was applied at, when it differs from the config's site — for example a managed site. Reference it either by its ID or by its external ID, but not both. Defaults to the config's site.

coordinates
object

The coordinates the material was applied at. Defaults to the application site's location.

input_containers
(New Container · object | Existing Container · object)[]

If the config version's input_configs field contains items, you can pass containers that reference a listed config and should be used as inputs here. Several items may name the same config. When the config lists no input configs, pass existing containers by id only.

Maximum array length: 100

Describes a new container to create, based on one of the container configs listed by the config of the object you create.

data_points
object[]

Data points to be set on the material utilization, based on the data_point_configs list of the material utilization config. Included values might affect input containers.

Maximum array length: 100

Response

Material utilization created.

id
string
required

The ID of the material utilization.

Example:

"mut_01kcwnf3gxeezez5jxrhf1k34x"

config_id
string
required

The ID of the config the utilization was created from.

Example:

"mutc_01k16bap2kcz0asd2h2dkzz1xj"

config_version_id
string
required

The ID of the exact config version the utilization was created from.

Example:

"mutcv_01kbr6p08518pexf6rs9segz8j"

external_id
string | null
required

Optional external ID of the utilization.

Example:

"MY-CUSTOM-ID"

display_id
string
required

Human-readable identifier.

Example:

"SNK-2026-01-15-1"

site
object
required

The site the material was applied at.

occurred_at
string<date-time>
required

When the utilization took place.

Example:

"2026-01-15T08:00:00Z"

created_at
string<date-time>
required

When the utilization was recorded in Cula.

Example:

"2026-01-15T08:00:00Z"

coordinates
object | null
required

The coordinates the material was applied at.

data_points
(short_text · object | long_text · object | multi_text · object | number · object | percentage · object | amount · object | timestamp · object | duration · object | boolean · object | material · object | material_batch · object | container_type · object | material_pool · object)[]
required

Data points set on the utilization step itself.

Data point holding a single line of text.

input_containers
object[]
required

The material containers the utilization consumed.

files
object[]
required

Files attached to the material utilization.