Entity references

Some operations reference entities (such as units or silos) through an entity reference rather than a single, fixed identifier. An entity reference lets you choose between two equivalent ways of pointing at the same entity, depending on what is most convenient for your integration.

When an operation accepts an entity reference, the request body will typically expose:

• One or more reference fields (for example unitRef, siloRef) that hold the value.
• A refType field that tells the API how to interpret those values.

The same refType applies to every entity reference within the same message.

Reference types

The refType field accepts one of the following values:

Type	Description
Id	The reference value is the permanent unique ScaleAQ identifier of the entity (it might be a generic string like a GUID or a non-negative integer in a string form depending on the entity type). It does not change during the entity's lifecycle.
CodePath	The reference value is a hierarchical path of codes that uniquely identifies the entity within its parent entity. Codes are managed by users and may change over time.

If refType is omitted, it defaults to CodePath.

Id references

When refType is Id, each reference value must be the entity's permanent ScaleAQ identifier as a string. The identifier is the same value returned by the Meta operations (for example unitId from Get site or siloId from Get company).

Example:

{
  "refType": "Id",
  "unitRef": "12345",
  "siloRef": "67890"
}

Use Id references when you want a value that is guaranteed to be stable over the entity's lifetime.

Code path references

When refType is CodePath, each reference value is a path of codes separated by / that together uniquely identify the entity. Each operation specifies the required number of segments — for example a unit on a site uses three segments: companyCode/siteCode/unitCode.

The codes used in the path are the companyCode, siteCode, unitCode and siloCode values returned by the Meta operations.

Each segment must:

• Be non-empty and at most 50 characters long.
• Contain only English letters (A–Z, a–z), digits, and the characters ., _, -.

Example for a three-segment unit reference:

{
  "refType": "CodePath",
  "unitRef": "ACME/BG/Unit-1",
  "siloRef": "ACME/BG/Silo-A"
}

Please note that the codes in the path are case-insensitive. For example, acme/bg/unit-1 is equivalent to ACME/BG/Unit-1.

Use CodePath references when you already have codes in your system for the corresponding entities. This way there is no need for your system to know about the Id of the entity and thus no additional mapping would be required.

info

Keep in mind that code paths can change if a user changes the codes of one of the entities in the path.

When data is received, the code path is always mapped to the underlying entity Id before being stored. This means that once the data has been stored, renaming the code of an entity does not affect any previously stored data — only subsequent API calls need to use the updated code path.

Supported entity types

The number of segments in a code path and whether the corresponding Id is numeric depend on the entity type:

Entity	Code path format	Example (CodePath)	Example (Id)
Company	companyCode	ACME	c4f1e2a8-1234-4abc-9def-1234567890ab
Site	companyCode/siteCode	ACME/BG	1114
Unit	companyCode/siteCode/unitCode	ACME/BG/Unit-1	12345
Silo	companyCode/siteCode/siloCode	ACME/BG/Silo-A	67890