Update a job

PATCH/api/v1/jobs/{id}

Changes an existing job: its customer or property, title, description, price lines (items_attributes), discount, currency, internal notes or how it is billed (billing). Send only the fields to change. The job's visits are scheduled and changed through the visit operations, not here. An active or completed job accepts every field, so a completed job can be priced and invoiced without reopening it. A cancelled job accepts only billing (with lock_version), so it can be set to none ("Don’t invoice"); any other field returns 409. The customer cannot change once the job has an invoice (409). Billing cannot change once a visit has been invoiced (422). A job from a quote whose deposit has been invoiced keeps that invoice's currency: another returns 409 invalid_transition.

Needs an API key, and runs with the access of the member who made the key.
Send an Idempotency-Key. The same key with the same request within 24 hours gives the first answer again and changes nothing.
A connected AI assistant can use it too, as updateJob.

Parameters

In the address

idstring (uuid)required

Headers

Idempotency-Keystringrequired
Unique user-scoped key for safely retrying this mutation for 24 hours.
At least 1 character. Up to 200 characters.

Request body

Sent as application/json.

jobobjectrequired
Fields(10)
- customer_idstring (uuid)
- property_idstring (uuid) or null
- titlestring
- descriptionstring or null
- currencystring
  At least 3 characters. Up to 3 characters.
- discount_centsinteger (int64)
  Integer minor currency units, such as pence.
  At least 0.
- internal_notesstring or null
- billingstring
  Once a visit of the job has been invoiced it can only move between `per_visit` and `monthly`; any other change returns 422.
  One of: on_completion, per_visit, none, monthly. Default: "on_completion".
- lock_versioninteger
  At least 0.
- items_attributesarray of object
  Each item(10)
  idstring (uuid)
  service_idstring (uuid) or null
  positioninteger
  At least 0.
  descriptionstring
  quantitystring
  Matches ^\d{1,9}(\.\d{1,3})?$.
  unit_namestring or null
  unit_price_centsinteger (int64)
  Integer minor currency units, such as pence.
  At least 0.
  tax_rate_basis_pointsinteger
  At least 0. At most 10000.
  tax_inclusiveboolean
  _destroyboolean

Responses

200Job details.

dataobjectrequired
Fields(24)
- lock_versionintegerrequired
  At least 0.
- created_atstring (date-time)required
- updated_atstring (date-time)required
- idstring (uuid)required
- account_idstring (uuid)required
- customer_idstring (uuid)required
- property_idstring (uuid) or null
- source_quote_idstring (uuid) or null
- numberstringrequired
- titlestringrequired
- descriptionstring or null
- statusstringrequired
  One of: active, completed, cancelled.
- billingstringrequired
  `on_completion`: one invoice once the job is complete. `per_visit`: job lines are the price of one visit, and the job is invoiced batch by batch as visits are completed while it stays active. `none`: "Don’t invoice", for work paid another way or done for free; the job is never invoiced. `monthly`: "At month end". Priced and invoiced exactly as `per_visit` is, but its completed visits are meant to wait until their month is over: a visit is due for invoicing once the day it was booked for is before the first day of the current month, in the account's time zone. createMonthEndInvoices invoices every such job at once.
  One of: on_completion, per_visit, none, monthly. Default: "on_completion".
- currencystringrequired
- subtotal_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- discount_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- tax_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- total_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- internal_notesstring or null
- completed_atstring (date-time) or null
- cancelled_atstring (date-time) or null
- archived_atstring (date-time) or null
- itemsarray of objectrequired
  Each item(12)
  idstring (uuid)required
  service_idstring (uuid) or null
  positionintegerrequired
  descriptionstringrequired
  quantitystringrequired
  Matches ^\d{1,9}(\.\d{1,3})?$.
  unit_namestring or null
  unit_price_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
  tax_rate_basis_pointsintegerrequired
  At least 0. At most 10000.
  tax_inclusivebooleanrequired
  subtotal_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
  tax_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
  total_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- repeatsarray of object
  The repeating visits still running on this job, oldest first: every series with dates left to book. A series for part of the year is listed between its seasons, when the job has no visit booked. A series whose every date is booked is not listed; its visits still carry it.
  Each item(8)
  idstring (uuid)required
  intervalintegerrequired
  At least 1. At most 99.
  unitstringrequired
  `weekday` is Monday to Friday, one visit per working day, and needs an interval of 1.
  One of: day, weekday, week, month.
  starts_onstring (date)required
  ends_onstring (date) or null
  season_from_monthinteger or null
  `season_from_month` and `season_to_month` are the first and last month of the part of the year a series runs in, 1 for January to 12 for December, both included. Give both or neither. A season may run over the year end: 11 and 2 is November to February. Dates outside it are skipped; the rhythm is not restarted.
  At least 1. At most 12.
  season_to_monthinteger or null
  `season_from_month` and `season_to_month` are the first and last month of the part of the year a series runs in, 1 for January to 12 for December, both included. Give both or neither. A season may run over the year end: 11 and 2 is November to February. Dates outside it are skipped; the rhythm is not restarted.
  At least 1. At most 12.
  lock_versionintegerrequired
  At least 0.

A refusal answers in the one error shape every operation shares.

Example

A request our own tests send. The ids are made up: put your own in their place.

curl -X PATCH "https://app.tradesender.co.uk/api/v1/jobs/4088bebb-3a71-586f-922c-1612b3fa6557" \
  -H "Authorization: Bearer $TRADESENDER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "job": {
    "internal_notes": "Bring the long-reach trimmer."
  }
}'