Overview

The Ditio API lets you integrate your systems with Ditio’s construction platform. Whether you need to create projects and employees from your ERP, export time and payroll data, push machine telemetry from your fleet, or pull site photos for an archive — the API provides programmatic access to your Ditio data.

Environments

Ditio has a test and a production environment, each with its own hosts and its own credentials. Build against test first; the hosts, environment variables and rules for each are in Environments. Ditio Web for administrators is at https://core.ditio.app/#/.

What you can do

Goal	Endpoint / tool	Docs
Create and manage projects	api/v4/integration/projects	Projects
Create and manage work orders (tasks)	api/v4/integration/tasks	Work Orders
Create and manage employees (v4)	api/v4/integration/users	Users
Create and manage employees (v5)	api/v5/integration/employees	Employees v5
Read project personnel and their roles	api/v4/integration/projects/personnel, api/v4/integration/projects/{id}/personnel	Projects
Create and manage machines and equipment	api/v4/integration/machines	Machines
Manage user certificates	api/v4/integration/certificates	Certificates
Attach documents to projects & work orders	api/v4/integration/{projects,tasks}/{id}/documents	Documents
Push absences from your payroll or HR system	api/integration/absences	Absences
Export payroll data	api/payroll-export	Payroll Export
Extract time, absence, HSE, and metadata	/v1/... on the reporting base	Data Extraction
Extract mass transport (haul) trips	/v1/flow-trip-registrations	Mass Transport Registrations
Extract project images	/v1/images	Image Extraction
Connect Power BI	Power BI template	Power BI
Azure AD single sign-on	Azure Portal	Azure AD SSO
Automatic user provisioning	SCIM 2.0	SCIM Provisioning

The API surfaces

Integration API (read-write)

The partner-facing read-write surface on the Integration API base ($DITIO_API_BASE):

• api/v4/integration/* and api/v5/integration/*: projects, project personnel, work orders, users and employees, machines, certificates, and documents
• api/integration/absences: absences from your payroll or HR system
• api/payroll-export: payroll export

Data Extraction API (read-only)

Paginated, read-only extraction endpoints under /v1/... on the reporting base. Designed for BI tools, payroll integrators, and data warehouses. The extraction endpoints support cursor-based pagination with ContinuationToken and incremental sync with ModifiedSince. The one exception is /v1/item-registrations/web-query, which returns the whole result as semicolon-separated text for Power BI, without paging; see Pagination.

Mass Transport API (machine telemetry)

Write endpoints for pushing excavator states and weight measures from fleet management, telematics, and weighbridge systems. See Machine Integration.

Each surface has its own base URL and token scope — see Which scope for which host.

Typical integration flow

Most integrations set up data in this order:

1. Projects     →  Create your projects first
2. Work orders  →  Add work orders (tasks) to each project
3. Users        →  Create employee accounts
4. Machines     →  Register machines and equipment

Projects must exist before you can add work orders to them. Users and machines can be created independently.

Common conventions

• All requests require a valid Bearer token in the Authorization header
• Request and response bodies are JSON with camelCase property names on the Integration API and the Data Extraction API. Older lookup endpoints such as /api/projects, /api/resources (see Reference Data) and /api/MachineType answer in PascalCase unless you send the header case: camel-case
• Dates are in ISO 8601 format: 2026-01-15T00:00:00Z
• IDs are strings; see Data Model
• companyId is your Ditio company ID. Projects and machines fall back to your API client’s company when you leave it out on create
• PATCH updates only the fields you send. Several PUT endpoints also leave omitted fields unchanged, so check the endpoint’s reference page before relying on PUT to clear a field
• DELETE on a project is refused while the project has registrations; see Data Model. Prefer deactivating (active: false)

Status codes, error bodies and retry strategy are covered in Error Handling.

Code examples

Ready-made code examples and Postman collections:

• GitHub samples: ditioas/Ditio.Core.Samples.Integrations
• Postman collections: in the samples repo, or on request from [email protected]

Next steps

• Authentication — create API credentials and get a token
• Quickstart — your first API calls in five minutes
• Pagination — how extraction paging works