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

# Test (default for all examples)
export DITIO_API_BASE="https://core-api.ditio.dev/core"
# Production: export DITIO_API_BASE="https://core-api.ditio.app/core"

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"

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 support@ditio.no 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 '{
    "companyId": "YOUR_COMPANY_ID",
    "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
companyId	string	Your Ditio company ID
machineNumber	string	Your internal machine number (unique within the company)

Optional fields

Field	Type	Description
name	string	Machine name / description
typeId	string	Machine type ID (must match an existing type in your company)
active	bool	Whether the machine is active (default: false)
department	string	Department
costPriceMachine	double	Machine-specific cost price
costPrice	double	General cost price
price	double	Sales price
weight	double	Weight (kg)
capacity	double	Capacity
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)
isEquipment	bool	true for equipment, false for machines (default: false)

Create multiple machines at once

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

Send an array of machines. Each is processed individually — if one fails, the others are still created.

Get machines

What	Endpoint
All machines	GET /api/v4/integration/machines
By ID	GET /api/v4/integration/machines/{id}
By machine number	GET /api/v4/integration/machines/by-machine-number/{machineNumber}

Add ?includeEquipmentDetails=true to any GET endpoint to include linked equipment in the response.

Update a machine (full)

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

Bulk variant: PUT /api/v4/integration/machines/update/array (each item must include id).

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" }'

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}

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

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 '{
    "companyId": "YOUR_COMPANY_ID",
    "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 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

• Equipment 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