Machines & Equipment

The Machines API lets you register and manage machines (excavators, loaders, dumpers, trucks) and equipment (smaller tools and attachments) in Ditio — typically as a sync from your fleet management or asset system, so machine hours and usage in Ditio always reference the right fleet numbers.

Base URL: api/v4/integration/machines · Scope: ditioapiv3

Examples use the environment variables from Environments and default to the test environment.

Understanding machine types

Every machine in Ditio has a type (e.g. loader, dumper, truck). Machine types are configured per company and each type has a typeId — a string identifier like "hjullaster" or "dumper".

When creating a machine, you send the typeId string — not a numeric ID. The type must already exist in your Ditio company; otherwise the API returns the error MachineService.machineTypeInvalid.

Look up your company’s valid types via the API:

curl "$DITIO_API_BASE/api/MachineType" \
  -H "Authorization: Bearer $TOKEN" \
  -H "case: camel-case"

/api/MachineType is an older endpoint and is not in the interactive reference. It answers in PascalCase (TypeId, Description) unless you send the case: camel-case header, as above, which switches the response to camelCase (typeId, description).

Common examples (actual types depend on your company’s configuration):

typeId	Description
hjullaster	Wheel loader
beltemaskin	Tracked excavator
hjulgraver	Wheeled excavator
dumper	Dumper
lastebil	Truck
tippbil	Tipper truck
bil	Car
firmabil	Company car
traktor	Tractor
minidumper	Mini dumper

Contact [email protected] if you need new machine types added for your company.

Create a machine

POST /api/v4/integration/machines

curl -X POST "$DITIO_API_BASE/api/v4/integration/machines" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "machineNumber": "M-001",
    "name": "Volvo EC220E",
    "typeId": "beltemaskin",
    "active": true,
    "buildYear": 2022,
    "weight": 22000,
    "serialNumber": "VCEC220EL00012345",
    "registrationNumber": "AB 12345",
    "costPrice": 450.00
  }'

Required fields

Field	Type	Description
machineNumber	string	Your internal machine number (unique within the company)
typeId	string	Machine type ID. Required for machines: it must match an existing type in the machine’s company, or the request fails with MachineService.machineTypeInvalid. Not validated for equipment

Optional fields

Field	Type	Description
companyId	string	Ditio company that owns the machine. Defaults to the company of your API client. Another company must be part of your company structure; a machine created for another company gets price and costPrice set to 0
name	string	Machine name / description. Stored in title case on create ("VOLVO ec220e" becomes "Volvo Ec220e")
active	bool	Whether the machine is active (default: false)
department	string	Department. Stored in title case on create, like name
costPriceMachine	double	Machine-specific cost price
costPrice	double	General cost price
price	double	Sales price
weight	double	Weight (kg)
capacity	double	Capacity
capacityUnitId	string	Unit for capacity. Standard values: stk, rs, m3, m2, m, km, tonn, time, minutter, liter
note	string	Notes
buildYear	int	Year built
emissionClass	string	Emission class
hourMeter	double	Current hour meter reading
serviceDate	datetime	Last service date
purchasedDate	datetime	Purchase date
serialNumber	string	Serial number
engineNumber	string	Engine number
registrationNumber	string	Registration / license plate number
responsibleId	string	Responsible person (Ditio user ID)
responsibleEmployeeNumber	string	Responsible person (employee number)
blockCheckIn	bool	Block users from checking in on this machine (default: false). Machines only — ignored for equipment
blockCheckInMessage	string	Message shown to users when check-in is blocked. Machines only
isEquipment	bool	true for equipment, false for machines (default: false)

Response

Create, update and the GET endpoints return the machine with the fields above, plus:

Field	Type	Description
id	string	Ditio id. Use it in the {id} routes
isIntegrationMachine	bool	Marks machines created through this API. Set by Ditio; any value you send is ignored, and write responses always return true
equipmentDetails	array	Equipment linked to the machine, as { id, resourceNumber, name }. Only present when you pass includeEquipmentDetails=true

Create multiple machines at once

POST /api/v4/integration/machines/create/array

Send an array of machines. They are created one at a time, in order, and the response is the array of created machines.

The first failure stops the request

If one item fails, the request returns an error for that item and stops. Items before it are already saved; items after it are not processed. The error response does not list the saved items, so read the machines back (for example by machine number) before you retry, or the retry will create duplicates. PUT /update/array behaves the same way.

Get machines

What	Endpoint	Returns
All machines	GET /api/v4/integration/machines	Machines and equipment owned by your API client’s own company. Machines and equipment owned by other companies in your structure are not included
By ID	GET /api/v4/integration/machines/{id}	One machine or piece of equipment. An unknown id returns 500
By machine number	GET /api/v4/integration/machines/by-machine-number/{machineNumber}	One machine (not equipment) owned by the main company of your structure or one of its subsidiaries. No match returns 200 with the body null; more than one match returns 400

Add ?includeEquipmentDetails=true to any GET endpoint to include linked equipment (equipmentDetails) on each machine.

Update a machine

PUT /api/v4/integration/machines/{id}

PUT is not a full replace: any field you omit, or send as null, keeps its stored value. To clear a stored text field, send an empty string (""). name and department are stored as sent on update; title casing is applied only on create.

To update equipment, include "isEquipment": true in the body. Without it the id is looked up as a machine.

An unknown machine id returns 404; an unknown equipment id returns 400.

Bulk variant: PUT /api/v4/integration/machines/update/array (each item must include id). Like the create array, it stops at the first failure.

Update a machine (partial)

PATCH /api/v4/integration/machines/{id}

curl -X PATCH "$DITIO_API_BASE/api/v4/integration/machines/68a1b2c3d4e5f6a7b8c9d0e4" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "hourMeter": 4200, "serviceDate": "2026-06-01T00:00:00Z" }'

PATCH applies the fields you send to the stored machine or equipment. An unknown id returns 500.

Block check-in on a machine

Machines can be blocked for check-in (for example while under service). Set blockCheckIn and optionally blockCheckInMessage:

curl -X PATCH "$DITIO_API_BASE/api/v4/integration/machines/68a1b2c3d4e5f6a7b8c9d0e4" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "blockCheckIn": true, "blockCheckInMessage": "Under service until further notice" }'

Send "blockCheckIn": false to allow check-in again.

Note

If a PUT or PATCH payload does not include blockCheckIn / blockCheckInMessage, the stored values are left unchanged — existing sync integrations that don’t send these fields will never overwrite a block configured in Ditio Web. JSON null is treated the same as omitting the field; to clear a stored blockCheckInMessage, send an empty string (""). These fields apply to machines only — for equipment they are ignored and returned as null.

Update machine ESG fields

PATCH /api/v4/integration/machines/{id}/esg

Updates ESG-relevant fuel fields on a machine. Send at least one supported field.

curl -X PATCH "$DITIO_API_BASE/api/v4/integration/machines/68a1b2c3d4e5f6a7b8c9d0e4/esg" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "fuelConsumptionRate": 12.5, "fuelConsumptionUnit": 0, "fuelType": 1 }'

• fuelConsumptionUnit: 0 = L/hour, 1 = L/km, 2 = kWh/hour, 3 = kWh/km, 4 = kg/hour, 5 = kg/km
• fuelType: 0 = none, 1 = diesel, 2 = biodiesel, 3 = gasoline, 4 = electric, 5 = gas, 6 = natural gas, 7 = dyed diesel

Delete a machine

DELETE /api/v4/integration/machines/{id}

Returns 204 on success. An unknown id returns 500.

Check deletability first:

curl "$DITIO_API_BASE/api/v4/integration/machines/is-machine-deletable/68a1b2c3d4e5f6a7b8c9d0e4" \
  -H "Authorization: Bearer $TOKEN"
# Returns: true or false

Caution

Deleting a machine permanently removes it and all related data. This cannot be undone — prefer deactivating (active: false).

Machines vs equipment

	Machines	Equipment
What	Standalone vehicles and heavy machinery	Smaller tools, attachments, accessories
Examples	Excavator, loader, dumper, truck	Hydraulic hammer, tilt rotator, GPS unit
isEquipment	false (default)	true
Type validation	typeId is validated — must match an existing type	typeId is not validated
Linking	Equipment can be linked to machines	Linked to a parent machine
Stored fields	All fields above	Only machineNumber, name, department, typeId, costPrice, price and active; other fields are ignored

To create equipment, set isEquipment: true:

curl -X POST "$DITIO_API_BASE/api/v4/integration/machines" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "machineNumber": "EQ-001",
    "name": "Rammer S21 hydraulisk hammer",
    "isEquipment": true,
    "active": true
  }'

Common integration patterns

Sync your fleet from an external system

1. Fetch machine types first via GET /api/MachineType (with the case: camel-case header) to know which typeId values are valid
2. Create machines with matching typeId values
3. Periodically update hour meters and service dates via PATCH
4. Deactivate retired machines by patching active: false instead of deleting

Map your machine categories to Ditio types

If your system uses different category names, maintain a mapping table:

Your system	Ditio typeId
Excavator (tracked)	beltemaskin
Excavator (wheeled)	hjulgraver
Wheel loader	hjullaster
Articulated hauler	dumper
Truck	lastebil
Passenger vehicle	bil

Related

• Machine Data guide — exporting machine usage and the resource catalogue
• Machine Registrations — extract completed usage records for your machines
• Machine Integration guide — pushing machine telemetry into Ditio