Help centreOpen the app

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.

CallWhat it does
GET /connectionChecks the key. Answers with the contractor's business name, the name of this connection and the callback address, if one is set.
PUT /connectionSets 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}:

FieldWhat it is
titleRequired. What the job is, up to 200 characters.
descriptionMore detail, up to 5,000 characters.
prioritylow, normal, high or urgent.
referenceYour order or purchase order number, shown on the job and the invoice.
requestedByWho asked for the work.
dueAtWhen it is due, as a date and time with its offset, such as 2027-05-03T09:00:00+10:00.
siteaddress (required), suburb, postcode and name. Jobs at the same address share one site.
updatedAtWhen the job last changed in your system. Send it: the same stamp twice changes nothing.
cancelledtrue to cancel the job.
statusapproved 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:

TypeWhenData
time.recordedThe job is completedentries: each with worker, startedAt, endedAt and breakMinutes
job.completedThe job is completedcompletedAt, signedBy, notes, and signature as a PNG data address
invoice.sentThe contractor sends an invoice for the jobnumber, 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:

  1. Take t and v1 from the header.
  2. 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.
  3. Compare it with v1 in constant time. Turn the message away if they differ, or if t is more than five minutes from now.

Errors

AnswerWhy
400The reference, the job or the callback address is not in a form Crewzy takes. error says why, and fields names each field.
401The key is not recognised, or the contractor has disconnected it or made a new one.
404No job with that reference from this key.
423The contractor's business has closed.
429Too many calls from your address: up to 600 a minute. Wait and try again.

Still stuck? Email support@getcrewzy.com and tell us what you were doing, with the reference from any error message.