Connect a system to Orbitify
Another system (an ERP, a maintenance system, a building's controls, a site's gateway) works with a company in Orbitify through a connection: an account of its own with roles, as a person has them. Everything a connection may do is described here, built from the code, so it is always current.
Start
- Practise in a test company first. The company's administrator makes one in Settings > Connected systems: a copy of the company's kinds, fields, flows, roles and teams, and of its locations and assets when asked, with no real work.
- Connect the system there (Connect a system), give it the roles it needs, and make a key. A key works only in the company it was made in.
- Send the key as Authorization: Bearer, and an Idempotency-Key with every change: a change sent again with the same key is answered from the first time and never made twice.
- When it works, connect it in the real company with a key of its own.
curl -X POST "https://dashboard.orbitify.ai/api/ops/actions/request.raise" \
-H "Authorization: Bearer $KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"dryRun": true, "params": {"summary": "Pump P-1 is leaking", "classKey": "fault", "assetId": "erp:P-100"}}'Changes are actions
- Every change is an action, POST /ops/actions/<action>, checked as a person's would be: roles, the plan, approvals and the flow's rules. It is kept in the history under the connection's name and who connected it.
- Send dryRun: true to see what it would do; nothing is kept.
- A refusal says why in words (message), in the language of Accept-Language.
- Ids may be ours or the other system's, written system:id (erp:WO-55120). A create sent with outsideId is made once: sent again, it answers with the record made before.
Reading
- GET /ops/registry gives the company's kinds, fields and the steps of each flow: the keys an action takes.
- One request, work order or asset: GET /ops/requests/<id>, /ops/work-orders/<id>, /ops/assets/<id>. A connection reads only what its roles may see.
- GET /ops/test-company says whether the key works in a test company (testOf).
Readings from a system
Up to 1,000 readings a call, POST /ops/readings/batch, each matched to exactly one asset by our id, its number, code, serial or system:id. A key made for readings only opens this.
Live data from a site
A site's gateway or a trend log sends with a live data key, made on a source's page in Settings > Live data sources, which opens POST /ops/live/ingest only. Up to 5,000 readings a call, as JSON, Telegraf's JSON or CSV. A reading of a tag at a time already kept is kept once, so a buffer may be sent again; no Idempotency-Key. Nothing ever writes back to a control system.
curl -X POST "https://dashboard.orbitify.ai/api/ops/live/ingest" \
-H "Authorization: Bearer $LIVE_KEY" -H "Content-Type: application/json" \
-d '{"readings": [{"tag": "INV-03.Temp_Bearing", "at": "2026-10-23T14:02:00Z", "value": 71.5}]}'Hearing what happens
- What happens is sent to the https addresses a connection hears at, signed as Standard Webhooks 1.0 says, and kept 30 days in the event list, GET /ops/events, oldest first, paged by seq.
- Check webhook-signature: HMAC-SHA256 of "webhook-id.webhook-timestamp.body" with the secret's bytes. The standard's own libraries do it.
- An event says what changed and where to look, never the record: read the record for its values. Order is not guaranteed: drop an event whose version is older than one already seen.
- A failed delivery is tried again for about three days; 410 switches the address off.
Limits and safety
- 120 calls a minute per key and 600 per company; past them, 429 with Retry-After.
- A connection that suddenly changes far more than usual is paused until an administrator resumes it.
- Keys end after a year unless renewed, and each connection is reviewed every six months by the person who answers for it.
Versions and changes
- This API's version is 2026-10-24, the day it went live. It only grows: new actions, fields, values and events are added; nothing a connected system uses is taken away or changed. Ignore fields and values you do not know.
- Send Orbitify-Version: 2026-10-24 to pin it; the answer says the version it used. A new version comes only for a change that cannot be made without breaking, and the version before keeps working for at least 6 months.
- An action being retired answers with Deprecation and Sunset headers and a link to what replaces it. Whoever answers for each connection still using it is emailed when it is announced, 30 days before and 7 days before it stops.
- Events only grow too: an event whose content must change becomes a new kind of event, and the old one goes on as it was.
curl "https://dashboard.orbitify.ai/api/ops/registry" \
-H "Authorization: Bearer $KEY" \
-H "Orbitify-Version: 2026-10-24"API changelog
Connect your other systems
Settings now has Connected systems. Each system you connect gets its own account with the roles you choose, keys that last a year, and a record of everything it changed. Your systems can create and update records under the same rules as people, and hear what changes through signed webhooks or an events feed. A safety switch pauses a connection that suddenly changes far more than usual, and tells your administrators.
A public page for developers
Developers building an integration can now read the developers page without signing in. It lists every action, read and event with examples, and links to the API description they can load into their own tools. It is built from the live platform, so it is always current.
A dated version for the connector API
Send the Orbitify-Version header, such as Orbitify-Version: 2026-10-24, to name the version your integration was written for; every answer says which version it followed. The API changes only by adding. A change that cannot be made by adding comes as a new version, announced at least 6 months before the older one ends, and a call to an action on its way out answers with the Deprecation and Sunset headers and a link to what to do.
Reference
Operations shown: 32. Version 2026-10-24
Requests
POST/api/ops/actions/request.assignPass request to a team
Give a request to a team, the people who will sort it or do the work. To give work to a person, make a work order for the request and assign that (work_order.create, work_order.assign).
| Name | Type | What it is |
|---|---|---|
expectedVersion | integer | |
teamId | id: ours or system:id |
{
"target": "bms:ALM-88213",
"params": {
"teamId": "3f1c2a9e-0000-4000-8000-000000000001"
}
}POST/api/ops/actions/request.raiseRaise request
Raise a request (a ticket, a call-out, a fault report): report a fault, a need or a finding at a location or on an asset. Use it when someone reports something wrong or needed; it is not yet work for anyone (make a work order for that). Routing rules choose the team, time targets start and the right people are told, as for a person. It needs a summary, the kind of request and where it is: a location, an asset at one, or both (people in the app are refused with neither; a connected system may still leave both out). Raising it for someone else (reportedById) needs the right to raise requests for someone else (a connected system needs only to raise requests). Coming from another system, send outsideId with that system's ticket id so a repeat makes nothing twice.
| Name | Type | What it is |
|---|---|---|
classKey* | string | The kind of request, a key from GET /api/ops/registry (classes of kind request), never a work order's kind such as corrective |
summary* | string | Its title: what is wrong or needed, in one short line |
assetId | id: ours or system:id | The asset it is about (or system:id); its location is taken when locationId is left out |
attrs | object | Values for the kind's own fields, by field key (GET /api/ops/registry) |
details | string | Its description: what was seen, since when, anything that helps the team; optional |
detectionMethod | string | How it was found, such as an alarm or an inspection |
entityId | id: ours or system:id | a legal entity in the company's group; null: its place's, or the one above |
findingIds | array | |
impact | string | ONE (one asset or room), SEVERAL or SITE (the whole site): with the company's grid, the severity is worked out from it and the severity said (its urgency) |
incidentTypeId | id: ours or system:id | |
internal | boolean | |
locationId | id: ours or system:id | Where: a location id (or system:id). Give a location, an asset at one, or both (needed in the app; a connected system may leave both out) |
photos | array | of {url, name, contentType, sizeBytes}: photos, videos or PDFs of the fault, uploaded first (POST /api/ops/uploads |
punchListId | id: ours or system:id | a punch list it is an item of: its place, team and kind unless given here |
reportedById | id: ours or system:id | who reported it, when someone raises it for them: a person who called or wrote; needs the right to raise requests for someone else |
reportedVia | string | APP | PHONE | CHAT | EMAIL | ON_SITE (how it came in; APP when left out)One of: APP, PHONE, CHAT, EMAIL, ON_SITE |
severity | string | How bad it is; the company's own words for each are in GET /api/ops/settingsOne of: MINOR, MODERATE, MAJOR, CRITICAL |
teamId | id: ours or system:id | A team to give it to; left out, the company's routing rules choose |
outsideId | string | The other system's id for it, system:id; it is then made once |
{
"params": {
"summary": "Water leaking under the plant room door",
"details": "A puddle by the door since this morning; it seems to come from the pipe above the ceiling.",
"classKey": "leak",
"locationId": "9e8d7c6b-0000-4000-8000-000000000014",
"severity": "MODERATE"
}
}POST/api/ops/actions/request.transitionChange request status
Move a request to another step of its flow: start it, put it on hold, mark it fixed, confirm it, close or cancel it. The steps it may go to next are on its read (GET /api/ops/requests/{id}, next) and GET /api/ops/requests/{id}/checks says what each would need. The flow's rules hold: required fields, who may make the move, approvals.
| Name | Type | What it is |
|---|---|---|
to* | string | The key of the step to move to, one of the request's next steps |
attrs | object | |
expectedVersion | integer | |
note | string | Why, kept with the move |
{
"target": "bms:ALM-88213",
"params": {
"to": "closed",
"note": "Alarm cleared at the source"
}
}POST/api/ops/actions/request.updateEdit request
Change what a request says: its summary (title), description (details), severity, kind, location, asset or fields. Use it to correct or add to a request; a new severity, kind or place matches its time target again. Not its step (request.transition) nor its team (request.assign). A closed or cancelled request stays as it was.
| Name | Type | What it is |
|---|---|---|
assetId | id: ours or system:id | null takes the asset off |
attrs | object | fields to change; null removes one |
classKey | string | |
details | string | its description; empty takes it off |
entityId | id: ours or system:id | a legal entity in the company's group; null: its place's, or the one above |
expectedVersion | integer | The version you read; the change is refused when someone changed it since |
impact | string | ONE | SEVERAL | SITEOne of: ONE, SEVERAL, SITE |
locationId | id: ours or system:id | |
severity | string | MINOR | MODERATE | MAJOR | CRITICAL (its urgency, with the company's grid)One of: MINOR, MODERATE, MAJOR, CRITICAL |
summary | string | its title |
{
"target": "bms:ALM-88213",
"params": {
"severity": "CRITICAL"
}
}Work orders
POST/api/ops/actions/cost.addAdd a cost to a work order
Add a cost to a work order (the target): parts, a purchase, a subcontractor, travel, other; in any currency, at the latest rate kept. Parts from the store are charged by issuing them (part.issue), not here.
| Name | Type | What it is |
|---|---|---|
amount* | number | |
description* | string | |
kind* | string | PART | PURCHASE | SUBCONTRACT | TRAVEL | OTHEROne of: PART, PURCHASE, SUBCONTRACT, TRAVEL, OTHER |
currency | string | Its currency (ISO 4217); the company's when left out |
incurredOn | string (date) | |
rate | number | Its rate to the company's currency; the latest kept when left out |
vendorId | id: ours or system:id |
{
"target": "erp:WO-55120",
"params": {
"kind": "SUBCONTRACT",
"description": "Crane hire, half a day",
"amount": 450,
"currency": "EUR"
}
}POST/api/ops/actions/message.addWrite a message
Add a message to a request or a work order (the target): words and files (photos, videos, PDFs uploaded first) the people on it read. Shared messages are seen by the client's people too; a note for the company only is shared false. Use it to tell the people on the work something, or to answer a question on it.
| Name | Type | What it is |
|---|---|---|
body | string | |
files | array | of {url, name, contentType, sizeBytes}: photos, videos or PDFs uploaded first |
objectKind | string | request | work_order (request when left out)One of: request, work_order |
shared | boolean | seen by the client's people; on for a request, off for a work order when left out |
{
"target": "bms:ALM-88213",
"params": {
"objectKind": "request",
"body": "The alarm came back at 14:02"
}
}POST/api/ops/actions/time.logLog time on a work order
Log time worked on a work order (the target) for a person who is on it: how long and on which day. Logging someone else's time needs the right to assign the work.
| Name | Type | What it is |
|---|---|---|
personId* | id: ours or system:id | |
time* | string | How long: 1h30, 90m, 1.5h or 0:45 |
note | string | |
workedOn | string (date) | The day it was worked; today when left out |
{
"target": "erp:WO-55120",
"params": {
"time": "1h30",
"workedOn": "2026-11-03",
"personId": "5b2d7c1e-0000-4000-8000-000000000002"
}
}POST/api/ops/actions/work_order.assignAssign work order
Give a work order to a team, a person, or both, and set who else is on it (crewIds, the whole list). Use it to dispatch work to a technician. The certificates the work needs are checked for each person.
| Name | Type | What it is |
|---|---|---|
assigneeId | id: ours or system:id | |
crewIds | array | everyone else on the work order besides its person: the whole list; [] for nobody |
deadline | string (date) | |
expectedVersion | integer | |
note | string | a few words more on the reason |
reason | string | when assigneeId is not suggestedId: KNOWS_THE_SITE | AVAILABLE_SOONER | CLIENT_ASKED | TRAINING | SHARING_WORK | OTHEROne of: when, AVAILABLE_SOONER, CLIENT_ASKED, TRAINING, SHARING_WORK, OTHER |
suggestedId | id: ours or system:id | who "Who could do it" put first, when the screen showed it |
teamId | id: ours or system:id |
{
"target": "erp:WO-55120",
"params": {
"assigneeId": "5b2d7c1e-0000-4000-8000-000000000002"
}
}POST/api/ops/actions/work_order.createCreate work order
Make a work order (a job): work for someone to do at a location or on assets, optionally answering requests, with the tasks of its kind and a checklist. Use it when a request needs work, or to plan corrective or preventive work directly. Approval rules, certificates and permits hold as for a person. Needs a title; give the kind, where, the requests it answers, a priority and a due date when known. Coming from another system, send outsideId with that system's order number so a repeat makes nothing twice.
| Name | Type | What it is |
|---|---|---|
title* | string | What is to be done, in one line |
assetId | id: ours or system:id | |
assetIds | array | the assets it is about, in order: a round of several |
assigneeId | id: ours or system:id | |
attrs | object | |
checklistId | id: ours or system:id | a checklist whose tasks it also gets, after its kind's (V331 |
classKey | string | The kind of work, a key from GET /api/ops/registry (classes of kind work_order) |
deadline | string (date) | When it is due: a day (2026-11-03) or a time |
description | string | |
entityId | id: ours or system:id | a legal entity in the company's group; null: its place's, or the one above |
estimatedHours | number | the hours the work should take (V317 |
locationId | id: ours or system:id | |
move | boolean | Take requests already on another open work order off it; left out, people in the app are refused and a connected system moves it |
parentId | id: ours or system:id | |
priority | string | Left out with requests: their worst severity sets it, as the company's settings map themOne of: ROUTINE, PLANNED, URGENT, EMERGENCY |
projectId | id: ours or system:id | |
requestIds | array | Requests it answers (ids or system:id); they follow it and close when it is done |
tasks | array | Tasks to add after its kind's: each {title, kind: CHECK|READING|TEXT|CHOICE|PHOTO, required, unit} |
teamId | id: ours or system:id | |
outsideId | string | The other system's id for it, system:id; it is then made once |
{
"params": {
"title": "Fix the leak under the plant room door",
"classKey": "corrective",
"requestIds": [
"8d4f6b2a-0000-4000-8000-000000000011"
],
"priority": "URGENT",
"deadline": "2026-11-04"
}
}POST/api/ops/actions/work_order.record_tasksRecord several tasks of a work order
Record several tasks of a work order at once, each by its id or its title: done or not, a reading's value, a note. Use it when a technician reports a few things together. All or nothing.
| Name | Type | What it is |
|---|---|---|
tasks* | array | of {taskId or title, done, value, note, readAt} |
{
"target": "erp:WO-55120",
"params": {
"tasks": [
{
"title": "Suction pressure",
"value": 4.2
},
{
"title": "Discharge pressure",
"value": 15.8
},
{
"title": "Belt tension checked",
"done": true
}
]
}
}POST/api/ops/actions/work_order.schedulePlan a work order on the schedule
Put a work order on the schedule (a start and hours), or take it off; optionally give it to a person. Use it to plan who does what on which day; GET /api/ops/schedule shows the board. Warns for a client that agrees visits first, a day fuller than the person works, or a due date before the day.
| Name | Type | What it is |
|---|---|---|
assigneeId | id: ours or system:id | give it to this person (leave out to keep its person |
hours | string | how long it takes, in hours (empty: not said) |
start | string | when it starts: 2026-10-09T09:00 (in timeZone), a day (2026-10-09: when the person's day starts), or empty to take it off the schedule |
timeZone | string | the zone start is written in, such as Europe/London (else the person's own, else UTC) |
{
"target": "erp:WO-55120",
"params": {
"start": "2026-11-04T08:00",
"hours": 2,
"timeZone": "Europe/London"
}
}POST/api/ops/actions/work_order.transitionChange work order status
Move a work order to another step of its flow: send it out, start, put on hold, finish, close or cancel it. The steps it may go to next are on its read (GET /api/ops/work-orders/{id}, next) and GET /api/ops/work-orders/{id}/checks says what each would need. Required tasks, failure reports, permits, agreed visits, certificates and approvals hold as for a person.
| Name | Type | What it is |
|---|---|---|
to* | string | |
attrs | object | |
expectedVersion | integer | |
whatWasDone | string | what was done, kept as a shared message on the work order and on each request it finishes |
{
"target": "erp:WO-55120",
"params": {
"to": "completed"
}
}POST/api/ops/actions/work_order.updateEdit work order
Change what a work order says: title, description, priority, deadline, kind, location, fields, estimated hours. Not its step (work_order.transition), people (work_order.assign) or schedule (work_order.schedule).
| Name | Type | What it is |
|---|---|---|
attrs | object | fields to change; null removes one |
classKey | string | |
deadline | string (date) | YYYY-MM-DD) or time; null takes it off |
description | string | |
entityId | id: ours or system:id | a legal entity in the company's group; null: its place's, or the one above |
estimatedHours | number | the hours the work should take; null takes it off (V317 |
expectedVersion | integer | The version you read; the change is refused when someone changed it since |
locationId | id: ours or system:id | |
priority | string | ROUTINE | PLANNED | URGENT | EMERGENCYOne of: ROUTINE, PLANNED, URGENT, EMERGENCY |
title | string |
{
"target": "erp:WO-55120",
"params": {
"deadline": "2026-12-05"
}
}Tasks
POST/api/ops/actions/task.recordRecord a task
Record one task of a work order (the task is the target): done or not, its answer or reading, a note. Out of range readings are marked. For several tasks at once, work_order.record_tasks.
| Name | Type | What it is |
|---|---|---|
done | boolean | |
note | string | |
photos | array | |
readAt | string (date-time) | a reading was taken: 2026-10-16T09:30 (UTC unless it says its offset); empty: now |
removePhotoIds | array | |
value | number | string |
{
"targetId": "7a0e5f3c-0000-4000-8000-000000000003",
"params": {
"value": 61.5,
"done": true
}
}Assets and readings
POST/api/ops/actions/asset.createAdd asset
Add an asset (a piece of equipment, infrastructure, a vehicle or a tool) to the register at a location or inside another asset. Use it when something new is installed or found that is not on the register; asset.register also records its warranty, value, spare parts and maintenance plan in one go. A serial number another asset has is refused. Coming from another system, send outsideId with that system's asset id so a repeat makes nothing twice.
| Name | Type | What it is |
|---|---|---|
name* | string | |
attrs | object | |
builtOn | string (date) | when it was built |
classKey | string | The kind of asset, a key from GET /api/ops/registry (classes of kind asset) |
code | string | |
defaultWorkKindKey | string | the kind of work a work order about it is when nobody says |
groupId | id: ours or system:id | its asset group (V317 |
installedOn | string (date) | |
investedOn | string (date) | when it was paid for |
locationId | id: ours or system:id | |
manufacturer | string | |
model | string | |
ownerEntityId | id: ours or system:id | a legal entity in the company's group; null: its place's |
parentAssetId | id: ours or system:id | |
projectId | id: ours or system:id | |
serialNumber | string | |
yearlyCost | number | what keeping it costs a year |
yearlyCostCurrency | string | default: the company's |
outsideId | string | The other system's id for it, system:id; it is then made once |
{
"params": {
"name": "Chilled water pump 3",
"classKey": "pump",
"locationId": "9e8d7c6b-0000-4000-8000-000000000014",
"manufacturer": "Northside Pumps",
"model": "NB 65-200",
"serialNumber": "SN-77811"
}
}POST/api/ops/actions/asset.moveMove asset
Move an asset to another location or inside another asset; its history keeps where it was and why (moved, removed, returned, swapped under warranty). To put a spare in an asset's place, asset.replace.
| Name | Type | What it is |
|---|---|---|
expectedVersion | integer | |
locationId | id: ours or system:id | |
note | string | |
parentAssetId | id: ours or system:id | |
reason | string | MOVED | REMOVED | RETURNED | WARRANTY_SWAP (why, for its history)One of: MOVED, REMOVED, RETURNED, WARRANTY_SWAP |
{
"target": "erp:EQ-1042",
"params": {
"locationId": "erp:WORKSHOP",
"reason": "REMOVED",
"note": "Sent for repair"
}
}POST/api/ops/actions/asset.updateEdit asset
Change what an asset's record says: name, code, kind, make, model, serial number, dates, fields, group. Not where it is (asset.move) nor who looks after it (asset.set_care).
| Name | Type | What it is |
|---|---|---|
attrs | object | |
builtOn | string (date) | |
classKey | string | |
code | string | |
defaultWorkKindKey | string | |
expectedVersion | integer | |
groupId | id: ours or system:id | its asset group (V317); null: none |
installedOn | string (date) | |
investedOn | string (date) | |
manufacturer | string | |
model | string | |
name | string | |
ownerEntityId | id: ours or system:id | a legal entity in the company's group; null: its place's |
serialNumber | string | |
yearlyCost | number | |
yearlyCostCurrency | string |
{
"target": "erp:EQ-1042",
"params": {
"serialNumber": "SN-77810-B"
}
}POST/api/ops/actions/reading.recordRecord a reading of an asset
Record one reading on an asset with no work order (a meter, a counter, a gauge, a measurement): what was read, its value and unit, when. Maintenance by meter and condition rules count it. For many at once, reading.record_batch; on a work order, record its reading task instead (task.record).
| Name | Type | What it is |
|---|---|---|
assetId* | id: ours or system:id | the asset read (or the target |
title* | string | what was read, such as Running hours (as a reading task names it |
value* | number | |
note | string | |
readAt | string (date-time) | it was read: 2026-10-16T09:30 (UTC unless it says its offset); empty: now |
unit | string | its unit, such as h (empty: none |
{
"params": {
"assetId": "bms:AHU-3",
"title": "Running hours",
"value": 18234,
"unit": "h",
"readAt": "2026-11-03T06:00Z"
}
}POST/api/ops/readings/batchSend readings
Record up to 1,000 readings at once. Each is matched to exactly one asset by our id, its number, its code, its serial or system:id; a reading that matches none, or more than one, is refused alone with why, and the rest are kept. readAt is required and never in the future; a unit must match the readings before it. A key made for readings only opens this and nothing else.
| Name | Type | What it is |
|---|---|---|
readings* | array | |
dryRun | boolean |
{
"readings": [
{
"asset": "AST-00128",
"title": "Energy",
"value": 50213.4,
"unit": "kWh",
"readAt": "2026-11-03T06:00Z"
},
{
"asset": "bms:AHU-3",
"title": "Running hours",
"value": 18240,
"unit": "h",
"readAt": "2026-11-03T06:00Z"
}
]
}Live data from sites
POST/api/ops/live/ingestSend a site's live readings
Up to 5,000 readings a call, 4 MB at most, with a key of purpose LIVE (made on the source's page in Settings > Live data sources), which opens this and nothing else. A reading of a tag at a time already kept is kept once, so a buffer may be sent again after an outage; no Idempotency-Key. Also accepted: a bare array of readings, Telegraf's JSON ({"metrics": [...]}, each field the tag <device>.<field>) and CSV (text/csv, lines of tag,at,value[,quality], a header line allowed).
| Name | Type | What it is |
|---|---|---|
readings* | array |
{
"readings": [
{
"tag": "INV-03.Temp_Bearing",
"at": "2026-10-23T14:02:00Z",
"value": 71.5
},
{
"tag": "INV-03.Power",
"at": "2026-10-23T14:02:00Z",
"value": 412,
"quality": "good"
}
]
}Locations
POST/api/ops/actions/location.createCreate location
Add a location (a building, a floor, a room, an area, a site) inside another, with its kind, code and fields; optionally its pin or outline on the map. Coming from another system, send outsideId with that system's id so a repeat makes nothing twice.
| Name | Type | What it is |
|---|---|---|
name* | string | |
attrs | object | |
classKey | string | |
clientCode | string | |
code | string | |
entityId | id: ours or system:id | a legal entity in the company's group; null: its place's, or the one above |
outline | object | GeoJSON polygon |
parentId | id: ours or system:id | The location it is inside (or system:id); a project's own location at the top |
point | array | [longitude, latitude] |
projectId | id: ours or system:id | |
outsideId | string | The other system's id for it, system:id; it is then made once |
{
"params": {
"name": "Plant room 2",
"code": "PR-2",
"parentId": "erp:BLOCK-B",
"outsideId": "erp:LOC-2201"
}
}POST/api/ops/actions/location.updateUpdate location
Change what a location's record says: name, code, kind, fields. A project's own location is renamed with the project. Its client is set by location.set_client; a project's stage and settings by workspace.configure.
| Name | Type | What it is |
|---|---|---|
attrs | object | |
classKey | string | |
code | string | |
costCentreId | id: ours or system:id | |
entityId | id: ours or system:id | a legal entity in the company's group; null: its place's, or the one above |
name | string | |
status | string |
{
"target": "erp:LOC-2201",
"params": {
"code": "B-PR-2"
}
}Parts, suppliers and stock
POST/api/ops/actions/part.saveSave a part
Add a spare part or a service to the catalogue, or change one (the target): code, name, unit, usual price, default supplier, whether it is tracked one by one by serial number. Codes are unique. Use it before parts are stocked, reserved or bought.
| Name | Type | What it is |
|---|---|---|
code* | string | |
name* | string | |
active | boolean | |
defaultPrice | number | |
defaultVendorId | id: ours or system:id | |
description | string | |
kind | string | PART (kept in stores) | SERVICE (bought or charged, never stocked)One of: PART, SERVICE |
priceCurrency | string | |
tracked | boolean | tracked one by one, each with its serial number (repaired and used again |
unit | string | |
outsideId | string | Another system's id for what this makes, written system:id; sent again, it answers with the record made before |
{
"params": {
"code": "FLT-600",
"name": "Bag filter 600x600",
"unit": "each",
"defaultPrice": 32.5,
"priceCurrency": "EUR"
}
}POST/api/ops/actions/purchase_order.receiveReceive what came of a purchase order
Receive what came on an issued purchase order (the target): some lines, everything, or what was wrong with it (damaged, wrong item, short, refused). Parts go into stock at the order's price; anything else for a work order becomes its cost. Whoever issued the order is told of problems.
| Name | Type | What it is |
|---|---|---|
all | boolean | |
lines | array | of {lineId, quantity, serials: for a part tracked one by one, each one's serial number} |
note | string | |
problems | array | of {lineId, kind: DAMAGED, WRONG_ITEM, SHORT, REFUSED or OTHER, quantity, note} |
receivedOn | string (date) | |
storeId | id: ours or system:id |
{
"target": "erp:PO-7781",
"params": {
"all": true,
"receivedOn": "2026-11-03"
}
}POST/api/ops/actions/stock.receiveReceive parts into a storeroom
Receive parts into a store (by id or code), at a cost, without a purchase order (for an order, purchase_order.receive). The average cost follows. A part tracked one by one names each serial received.
| Name | Type | What it is |
|---|---|---|
quantity* | number | |
currency | string | |
note | string | |
partCode | string | |
partId | id: ours or system:id | |
rate | number | |
serials | array | a part tracked one by one, the serial number of each one received |
spotCode | string | |
spotId | id: ours or system:id | |
storeCode | string | |
storeId | id: ours or system:id | |
unitCost | number | |
vendorId | id: ours or system:id |
{
"params": {
"storeCode": "MAIN",
"partCode": "FLT-600",
"quantity": 10,
"unitCost": 31.8,
"currency": "EUR"
}
}POST/api/ops/actions/vendor.saveSave a vendor
Add a supplier, or change one (the target): names, contacts, currency, payment terms, tax number, bank details.
| Name | Type | What it is |
|---|---|---|
name* | string | |
active | boolean | |
address | string | |
bankAccountName | string | whose account it is |
bankAccountNumber | string | |
bankBranch | string | |
bankName | string | |
code | string | |
contactEmail | string | |
contactName | string | |
contactPhone | string | |
currency | string | |
legalName | string | as on its invoices |
localName | string | the legal name in the local language |
paymentTermsDays | integer | |
swiftCode | string | 8 or 11 letters and digits |
taxNumber | string | |
outsideId | string | Another system's id for what this makes, written system:id; sent again, it answers with the record made before |
{
"params": {
"name": "Northside Filters",
"code": "NSF",
"currency": "EUR",
"paymentTermsDays": 30
}
}Events
GET/api/ops/eventsEvents, oldest first
What happened, oldest first, only about records the connection may read. Keep `next` and send it as `after` next time; while `more` is true, ask again at once. Events are kept 30 days.
| Name | Type | What it is |
|---|---|---|
after | integer (int64) | The seq of the last event read; 0 for the first |
types | string | Kinds to keep, comma-separated (request.raised,work_order.transitioned); all when left out |
limit | integer | query |
Reads
GET/api/ops/registryKinds, fields and flows
The company's kinds of location, asset, request and work order (their keys are classKey), their fields (attrs) and the steps of each flow (the keys a move goes to). Reads are under the connection's own rights: what its roles may see.
GET/api/ops/requests/{id}One request
A request with its step and `next`: the steps it may move to now. Reads are under the connection's own rights: what its roles may see.
| Name | Type | What it is |
|---|---|---|
id* | string (uuid) | path |
GET/api/ops/work-orders/{id}One work order
A work order with its step, tasks and `next`. Reads are under the connection's own rights: what its roles may see.
| Name | Type | What it is |
|---|---|---|
id* | string (uuid) | path |
GET/api/ops/assets/{id}One asset
An asset with its location and fields. Reads are under the connection's own rights: what its roles may see.
| Name | Type | What it is |
|---|---|---|
id* | string (uuid) | path |
GET/api/ops/test-companyWhether this is a test company
testOf: the company this is a test of (id and name); null in a real company. Reads are under the connection's own rights: what its roles may see.
Events sent to its addresses (webhooks)
request.raisedrequest.transitionedrequest.assignedrequest.updatedrequest.mergedwork_order.createdwork_order.transitionedwork_order.assignedwork_order.scheduledwork_order.updatedasset.createdasset.updatedasset.movedasset.disposedreading.recordedlocation.createdlocation.updatedreading.batch_recordedstock.receivedstock.movedpurchase_order.issuedpurchase_order.receivedapproval.requestedapproval.approvedapproval.refusedimport.doneconnector.ping