Skip to main content
Twine’s data model is built around a small set of core entities - Employee, Organizational Unit, Project, and Customer. Each entity carries a set of properties that describe it. The defining characteristic of these properties is that they are date-tracked: rather than storing only the current value, Twine records values by when they take effect. The depth of history available depends on what the source system exposes - refer to the relevant integration page for details.

Employee

The primary entity. Covers identity, employment, compensation, organisational structure, and more.

Organizational Unit

Nodes in a company’s structure - departments, divisions, teams, and similar.

Project

Project entities. Supported in Twine but not yet available through the public API.

Customer

Customer entities. Supported in Twine but not yet available through the public API.

​
Dated Properties

Every property on a Twine entity is represented as an array of Dated Properties, sorted in descending order by valid_from. This means the most recently effective value is always first in the list.
The first entry is the latest value by effective date - not necessarily the current value. A property can have a future-dated entry at the top of the list if a change has already been recorded but has not yet taken effect.
Each dated property has three fields:
FieldTypeDescription
valid_fromdate or nullThe date from which this value is effective. null means the value has been valid since the beginning of time - used for properties where history is not meaningful, such as first_name.
valueany or nullThe value itself. A null value signals that the property is no longer active from valid_from onwards - for example, a salary_amount entry with value: null and valid_from: 2021-01-01 means the salary ended on 2020-12-31.
idstring or nullA discriminator for properties that can have multiple simultaneous values. null by default. Used when a single property can hold several independent values at the same point in time - such as different benefit types. The id is derived from the source system (often an external ID or a combination of fields), or can be set explicitly using the Data Engine.

​
Example

A salary_amount history might look like this: 
[
  { "valid_from": "2024-01-01", "value": 55000, "id": null },
  { "valid_from": "2022-06-01", "value": 50000, "id": null },
  { "valid_from": null,         "value": 45000, "id": null }
]
The first entry is the most recently effective salary. If today is before 2024-01-01, the current salary is the 50 000 entry - but 55 000 still appears first in the list. A terminated salary would look like this: 
[
  { "valid_from": "2021-01-01", "value": null,  "id": null },
  { "valid_from": "2019-03-01", "value": 50000, "id": null }
]
The null value entry on 2021-01-01 signals that the salary ended on 2020-12-31.

​
Properties with multiple simultaneous values

When a property can hold more than one value at the same time - such as cost centre allocations or benefits - the id field segments them. Each distinct id represents an independent value series, with its own history: 
[
  { "valid_from": "2023-01-01", "value": "premium",  "id": "benefit_001" },
  { "valid_from": "2023-01-01", "value": "standard", "id": "benefit_002" },
  { "valid_from": "2021-06-01", "value": "basic",    "id": "benefit_001" }
]

​
List properties

Some properties hold an array as their value rather than a scalar - for example, team_id, which lists all teams an employee belongs to. These behave identically to scalar dated properties, except that value is an array.
A rework of how certain list properties are modelled is currently being evaluated. This may affect how values are stored and tracked for properties such as team_id.

​
Custom Properties

Every entity supports a custom_properties map. Each key in the map is a property name defined by the customer, and its value is an array of dated properties following the same structure as built-in properties - including support for the id discriminator. Custom properties are used when Twine’s built-in property set does not cover a field that a customer needs to transfer. They behave identically to built-in properties in the Data Engine and in domain mappings.

​
Computed Properties

Some properties are automatically derived from other properties unless you explicitly map them yourself. For example, manager_id is resolved from source_external_manager_id - Twine looks up the employee whose source_external_id matches the value in source_external_manager_id and populates manager_id with their Twine UUID. If you provide an explicit mapping for a computed property, the automatic derivation is skipped entirely and your mapping takes precedence.

​
Source Properties

Properties prefixed with source_ (such as source_external_id and source_organizational_unit_external_ids) are internal tracking fields that Twine uses to maintain references back to records in the originating system. They are exposed in the API but should not be relied upon for business logic if a more semantically meaningful property exists. Use them only when no suitable alternative is available. The most important source property is source_external_id. It must always be mapped to the primary key of the entity in the remote system. Twine relies on it to identify and match records across syncs, and computed properties like manager_id depend on it being present and correct.