Work giver API reference
For developers of a work giver's system: send jobs to a contractor's Crewzy with the key they gave you, and take their time, sign-off and invoices back.
This is for the developers of a work giver's system. A contractor on Crewzy makes a key for you under Connect a work giver by API, and gives you the key and the API address. With them you can send that contractor jobs, and take back their time, sign-off and invoices.
Each key belongs to one contractor and to one of your organisations or sites. If you serve many contractors, you hold one key for each.
Calling Crewzy
Every call goes to the API address the contractor gave you, such as https://api.example.com/api/v1/work-giver, with the key as a bearer token: Authorization: Bearer crewzy_wg_.... Requests and answers are JSON.
| Call | What it does |
|---|---|
GET /connection | Checks the key. Answers with the contractor's business name, the name of this connection and the callback address, if one is set. |
PUT /connection | Sets callbackUrl, the https address results go to. Answers with a signingSecret, in this answer only. Calling it again makes a new secret. |
PUT /work-orders/{ref} | Sends a new job, or changes one, under your own reference for it. |
GET /work-orders/{ref} | Where the job stands at the contractor's end. |
Your reference {ref} is up to 100 letters, digits, dots, dashes, colons or underscores. A key only ever sees the jobs it sent.
Sending a job
The body of PUT /work-orders/{ref}:
| Field | What it is |
|---|---|
title | Required. What the job is, up to 200 characters. |
description | More detail, up to 5,000 characters. |
priority | low, normal, high or urgent. |
reference | Your order or purchase order number, shown on the job and the invoice. |
requestedBy | Who asked for the work. |
dueAt | When it is due, as a date and time with its offset, such as 2027-05-03T09:00:00+10:00. |
site | address (required), suburb, postcode and name. Jobs at the same address share one site. |
updatedAt | When the job last changed in your system. Send it: the same stamp twice changes nothing. |
cancelled | true to cancel the job. |
status | approved or rejected for the finished work, or closed. |
Send the whole job each time, not only what changed. A new job answers 201; a change answers 200. Both answer with the ref, the job's status at the contractor's end and flagged.
A job nobody has worked on is cancelled when you cancel it. One with time logged, or already completed, is not cancelled: flagged is true, and the contractor is asked to talk to you about it.
The job's status is one of new, accepted, in_progress, completed, approved, rejected, closed or cancelled.
Results coming back
Crewzy sends each result as a POST to your callback address:
| Type | When | Data |
|---|---|---|
time.recorded | The job is completed | entries: each with worker, startedAt, endedAt and breakMinutes |
job.completed | The job is completed | completedAt, signedBy, notes, and signature as a PNG data address |
invoice.sent | The contractor sends an invoice for the job | number, issuedAt, dueAt, currency, lines, subtotal, tax and total |
Each message is { "id", "type", "ref", "sentAt", "data" }. The id is the same each time the same result is sent again, so you can drop repeats.
Answer with any 2xx once you have it. A 408, 429 or 5xx, or no answer within 15 seconds, is tried again later, up to eight times over about four minutes. Any other answer, including a redirect, is held for the contractor to look at and retry.
Checking the signature
Each message carries a header like Crewzy-Signature: t=1794958800,v1=5d41402a.... To check it:
- Take
tandv1from the header. - Work out the HMAC-SHA256 of
t, a full stop, then the body exactly as it arrived, keyed with your signing secret, written as hex. - Compare it with
v1in constant time. Turn the message away if they differ, or iftis more than five minutes from now.
Errors
| Answer | Why |
|---|---|
400 | The reference, the job or the callback address is not in a form Crewzy takes. error says why, and fields names each field. |
401 | The key is not recognised, or the contractor has disconnected it or made a new one. |
404 | No job with that reference from this key. |
423 | The contractor's business has closed. |
429 | Too many calls from your address: up to 600 a minute. Wait and try again. |