Service Orders

A service order is a unit of maintenance work raised against an asset. It captures what work is to be done, when it’s planned and carried out, who is responsible, and how much it’s expected to cost. Service orders give your team and the platform a record of work moving from planned, through execution, to completion.

At a glance

• Represents: a piece of planned or executed maintenance work
• Body: a JSON array of service-order objects
• Keyed by: id — your external identifier, and the upsert key
• Belongs to: an asset (assetId)
• Endpoint: POST /v2/serviceorders, returning a job

Tip

The full field list, required vs. optional flags, and a runnable example payload are in the API Reference under Service Order Import.

What it represents

Each service order describes a job and tracks its lifecycle. The what is a short description and an action: the type of work, the responsible department, and the quantity involved. The when spans several stages — planned, recommended, and actual execution dates — so you can compare delivery against the plan. Three statuses (operational, system, and user) record where the order sits in its workflow.

Service orders also carry cost (estimated, planned, and actual) and references back into your source system, such as functional locations, notification numbers, and purchase-order schedules. The shared geolocation concept describes where the work sits on the network.

Using it

• Import the asset a service order relates to before (or together with) the order. An assetId the platform doesn’t recognise resolves to nothing.
• Keep the id stable across imports. Re-sending an existing id updates the order in place; a new id creates a separate one.
• Use the date fields to reflect the order’s progress from planned through to execution. Set isDeleted to mark an order removed in your source system.
• An assetId that points at nothing passes request validation but fails at job time — see Common Errors.