Work that starts
somewhere else

Use read-only keys where you can

If what you're building only displays jobs, like a dashboard or a status page for tenants, give it a read-only key. Then it can't raise jobs or add notes, whatever the code does.

work-orders:read

List jobs, read one, read its timeline.

work-orders:write

Raise a job, add a note, upload a file.

*

Both. What the Full access option grants.

Run this first

curl -s https://workorders.nz/api/v1/integration/ping \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $WORKORDERS_KEY"

Run it before you write any code. It tells you whether the key works, which company's account it belongs to, and what it's allowed to do. It's worth checking the account before you post a job, in case you've pasted the wrong key.

What comes back

{
  "data": {
    "company": { "id": 1, "name": "Demo Plumbing & Gas" },
    "token": {
      "name": "Acme FM platform",
      "abilities": ["*"],
      "expires_at": null
    },
    "server_time": "2026-08-06T22:15:55Z"
  }
}

server_time is our clock. Every timestamp we send is UTC with a trailing Z. If your server's clock is an hour out, it's better to find out here than from jobs filed at the wrong time.

POST /api/v1/integration/work-orders

curl -s -X POST \
  https://workorders.nz/api/v1/integration/work-orders \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $WORKORDERS_KEY" \
  -H 'Idempotency-Key: fm-99213-2026-08-07' \
  -d '{
    "subject": "No hot water, Level 3 kitchen",
    "body": "Reported by the duty manager. The cylinder at 12 Bond Street is cold and there is water on the floor.",
    "requester_name": "Dana Whitfield",
    "requester_email": "dana@acmefm.example",
    "site_address": "12 Bond Street, Wellington",
    "urgency": "high",
    "external_reference": "FM-99213"
  }'

201 Created

{
  "data": {
    "id": 1,
    "reference": "WO-P6J9CE",
    "status": "new",
    "status_label": "New",
    "source": "api",
    "urgency": "high",
    "subject": "No hot water, Level 3 kitchen",
    "summary": null,
    "from": {
      "name": "Dana Whitfield",
      "email": "dana@acmefm.example"
    },
    "site_address": "12 Bond Street, Wellington",
    "assignee": null,
    "created_at": "2026-08-06T22:15:55Z",
    "updated_at": "2026-08-06T22:15:55Z",
    "attachments": []
  }
}

Shortened. The real response also includes the customer, the site and the rest of the job's fields. Store the reference. Every other endpoint uses it, and it's what the customer reads out over the phone. The summary, and the urgency if you didn't send one, are filled in a few seconds later, once the AI has read the description.

The fields

subject required

What's wrong, in one line. Up to 512 characters.

body optional

The description, up to 20,000 characters. You can paste a whole email thread into it. This is what the AI reads to set the urgency and find the site.

requester_name optional

Who reported it: a tenant, a duty manager.

requester_email optional

Who reported it. We find or create a customer record from this, and it's where status emails go.

site_address optional

Where, as written. Kept exactly as sent.

urgency optional

low, normal, high or emergency. Leave it out and the AI sets one from the description.

external_reference optional

Your own id for the job. We keep it alongside ours, so either side can look the job up when someone rings.

attachments optional

Up to 10 files inline, base64-encoded, 5 MB each and 15 MB per request.

Send an Idempotency-Key

References are forgiving

WO-P6J9CE, wo-p6j9ce and p6j9ce all find the same job. If you stored it in lower case, or dropped the prefix, you'll still find the right job.

Polling, not webhooks

There is nothing pushed to you yet. Ask for ?updated_since= with the newest updated_at you've seen, and you'll get everything that has changed since. The time you give is included, so you may see a job twice, but you'll never miss one.

What the API won't do