Data Model

Understanding a handful of core entities makes every Ditio API easier to work with. This page explains what they are and how they reference each other.

Entity hierarchy

Company
└── Project
    └── Work order (task)
        └── Registrations (time, machine usage, mass transport, checklists, incidents)

Core entities

Company

An organization using Ditio, identified by a companyId. Large contractor groups may have several companies in Ditio (parent and subsidiaries), and a project can involve project companies — the company context a subcontractor’s people work under on someone else’s project. Several extraction endpoints accept OwnCompanyDataOnly and ExcludeDataFromSubsidiaries to control which slice of a company structure you get.

Project

The top-level job (e.g. “Prosjekt Fjellhall”), identified by a Ditio id and a human-readable projectNumber that is unique within the company. Everything else — work orders, registrations, documents, plans — belongs to a project. Managed via the Projects API.

Work order (task)

The unit of work inside a project that employees register time against — the API calls it a task. Work orders can be hierarchical (parentActivityId) and carry cost codes for ERP mapping (externalDim01, externalId). Managed via the Work Orders API.

User / employee

A person. Three identifiers show up in the APIs:

Identifier	What it is
`identityId`	The login identity (phone number is the username)
`companyProfileId`	The person’s profile within one company
`employeeNumber`	Your payroll number for the person — unique within the company, and the recommended matching key between systems

A profile has one or more employments (with start/end dates, department, payroll type). The Employees API v5 models employments explicitly; the older Users API v4 flattens them into the user object.

Machine / resource

Machines (excavators, dumpers, trucks) and equipment (attachments, tools) are resources identified by a machineNumber / resourceNumber. Machines have a company-configured type (typeId). Managed via the Machines API; usage records come from Machine Registrations.

Registrations (transactions)

The records produced by field work:

Time registrations — hours logged by a person on a project/work order
Absence registrations — sick leave, vacation, and other time off
Machine registrations — completed machine usage
Checklist and incident registrations — QA/HSE submissions
Payroll lines — the processed result of time and absence data after payroll rules are applied

Registrations flow through an approval pipeline: field entry → approval → (for payroll data) locking and export. Extraction endpoints let you filter on approval state where relevant.

Conventions across the APIs

IDs are strings (MongoDB ObjectIds), e.g. 65f1a2b3c4d5e6f7a8b9c0d1
Dates are ISO 8601: 2026-01-15T00:00:00Z
JSON bodies use camelCase property names
companyId is required on all create operations
PUT replaces, PATCH merges — an omitted field in a PUT resets to its default; an omitted field in a PATCH is left unchanged
DELETE is permanent and refused while dependent data exists — prefer deactivating (active: false / disable endpoints)

Resolving cross-references

Most extraction responses include IDs that reference other entities. Resolve them with the metadata endpoints:

ID field	Resolve with
`userId`	User Metadata
`projectId`	Project Metadata
`resourceId`	Resource Metadata

Overview — the API surfaces and environments
Interactive API reference — full schemas for every entity