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)      — the unit registrations book against
    ├── Registrations          — time, absence, items, machine usage,
    │                            mass transport trips, checklists,
    │                            incidents, feed posts
    ├── People & machines      — the employees and resources on the project
    └── Attachments            — images, documents, generated PDFs

Most registrations reference a project, a work order (task), the person who made them, and often a machine/resource — a field check-in establishes that context before the data is submitted.

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. Each registration type has its own extraction endpoint on the reporting base unless noted:

Registration	What it is	Where to pull it
Time registrations	Hours logged by a person on a project/work order	Time Registrations
Absence registrations	Sick leave, vacation, and other time off	Absence Registrations
Item registrations	Consumed materials and items booked to a project/task (from the app’s item cart)	Power Query Examples — Power BI export
Machine registrations	Completed machine usage	Machine Registrations
Mass transport trips	Haul cycles (load → dump) with mass type, quantity, distance, and GPS	Mass Transport Registrations
Checklist submissions	Filled QA and safety checklist instances	Safety Reporting
Incident reports	HSE deviations and safety incidents (RUH)	Safety Reporting
Feed posts	Free-text updates and tickets posted to the project feed	see Feed and posts below
Payroll lines	The processed result of time and absence data after payroll rules run	Payroll Lines

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.

Feed and posts

Every project has a feed — the chronological stream field workers and office staff see in the app. Time registrations, incidents, and checklists all surface in the feed, and a feed post is a free-text entry (an update, question, or ticket) a user writes directly to it, optionally with photos.

Feed posts are not currently exposed as a standalone extraction endpoint. The photos attached to them are available through Image Extraction with Sources=feed.

Images and attachments

Photos and files live throughout Ditio — attached to feed posts, incidents, and checklists, and uploaded as project or work-order documents. They are all backed by the same file-reference model and reachable several ways:

Image Extraction — one paginated stream of every image in a project (feed posts, incidents, checklists), each with GPS coordinates, uploader, and project/task context.
Checklist and incident attachments — files uploaded inside a submission are on the record’s sections[].attachments[] / sections[].images[].
Documents — files attached to projects and work orders through the integration API.
PDF Extraction — the PDF Ditio generates for a submitted checklist, incident, or absence, via the record’s pdfUrl.

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