Getting work in
Raising jobs from another system
For when another system needs to create jobs itself. How to create an API key, and where to send the developer who builds the connection.
Last updated 10 August 2026.
Is this the right answer?
This page is for when another system already knows about a fault before anyone rings you, such as a facilities platform, a building-management system or a property manager's own software. Instead of someone re-typing each fault into an email, that system can raise the job in WorkOrders itself.
If the system can send email, that's the simpler option, and you won't need anyone to write software. See your own WorkOrders address. Read on if it can't send email, or you'd rather it used the API.
Creating a key
An owner or administrator creates a key under Settings → API keys. A key has:
- a name, saying who or what it's for, so you can tell your keys apart later
- an access level, either read and write or read only
- an optional expiry date.
You'll only see the full key once, when you create it. Copy it into the other system's settings straight away. If it's lost, we can't show it to you again. Create a new key and revoke the old one.
Give each system its own key. You can revoke a key at any time from the same screen, and if two systems share one key, revoking it cuts off both of them.
What to hand your integrator
Once you have the key, send whoever is building the integration to the developer reference. Let them know there's also a full OpenAPI 3.1 specification at /developers/openapi.yaml that they can import into their own tools.
That's all they need. The reference covers the endpoints, what to send and what comes back, the error codes and the rate limits. Our own automated tests check it against the real API, so it stays up to date.
What it can actually do
In short, the other system can raise a job with a subject, a description, who reported it, the site address, an urgency and its own reference number for the job. That reference means both sides can find the job when someone calls about it. It can attach files in the same request.
It can also look up a job to see how it's going, and read the job's timeline to see who did what and when. WorkOrders doesn't send updates out to the other system. Instead, the other system checks back whenever it wants to know what has changed.
It can't assign, complete or reopen a job. Each of those is recorded against a named person on your team, and a company key isn't a person.
Security
A key belongs to your company rather than to a person, and it can only see your company's own jobs.
If a system only needs to check on jobs (a dashboard, say, or a status page for tenants), give it a read-only key. Then it can't raise or change anything, whatever its own code tries to do.
You can revoke any key from Settings → API keys, and it stops working on its very next request.