Create a job

POST/api/v1/jobs

A job from a quote (source_quote_id) 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 createJob.

Parameters

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(12)
- customer_idstring (uuid)required
- property_idstring (uuid) or null
- titlestringrequired
- 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
- source_quote_idstring (uuid)
  An accepted quote this job carries out, so a job and its first visit are booked from a quote in one request. The quote must be accepted and not converted already, and its customer and property must match the job's. It is linked as convertQuoteToJob links it.
- initial_visitobject
  Optionally schedule and assign the first visit in the same transaction as creating the job. With `repeat`, the job gets a visit series starting at this visit's local date and time instead, which generates this visit and those after it. A repeat for part of the year can name a second rhythm for the rest of it in `off_season`, which gives the job a second series.
  Fields(12)
  titlestring
  Assessment title. Work visits use job_title.
  Up to 255 characters.
  customer_idstring (uuid)
  Assessment customer.
  property_idstring (uuid) or null
  Assessment property owned by that customer.
  assessment_notesstring or null
  Internal notes; never automatically copied to a quote.
  Up to 10000 characters.
  job_titlestring
  Rename the related job atomically with this visit. Requires job_lock_version and, when editing, the visit lock_version. Missing or invalid versions return 422; stale versions return 409. Omit job_title and job_lock_version when the title is unchanged.
  At least 1 character.
  job_lock_versioninteger
  Current job version, required with job_title. A stale version rejects the whole save with 409.
  At least 0.
  scheduled_start_atstring (date-time)required
  scheduled_end_atstring (date-time)required
  instructionsstring or null
  lock_versioninteger
  At least 0.
  membership_idsarray of string (uuid)
  repeatobject
  Every `interval` days, weeks or months, or every weekday.
  Fields(7)
  intervalinteger
  Default: 1. 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.
  ends_onstring (date) or null
  Last date a visit may fall on.
  occurrencesinteger
  End after this many visits, counted from `starts_on`; dates outside a season are not visits and are not counted. Stored as `ends_on`; wins over `ends_on`.
  At least 1. At most 500. Write only.
  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.
  off_seasonobject
  A different rhythm for the months outside the season, such as every 4 weeks from November to February beside every 2 weeks from March to October. It becomes a second series on the job with the same first date, time, people and end date, and the months the season leaves out. Needs `season_from_month` and `season_to_month`, which must leave part of the year out; otherwise the answer is 422 `season_has_no_visits`, as it is when no visit would fall in those months.
  Fields(2)
  intervalinteger
  Default: 1. 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.

Responses

201Job 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 POST "https://app.tradesender.co.uk/api/v1/jobs" \
  -H "Authorization: Bearer $TRADESENDER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "job": {
    "customer_id": "372a8e62-6d44-552f-9c0e-c1229b6478be",
    "property_id": "20e51c3e-939a-59cd-998f-b3650207b9d5",
    "title": "Garden tidy",
    "items_attributes": [
      {
        "service_id": "b4ccc05f-b1ed-5dcd-bede-4479c3500345",
        "position": 1,
        "description": "Garden tidy",
        "quantity": "1.000",
        "unit_name": "each",
        "unit_price_cents": 5000,
        "tax_rate_basis_points": 2000,
        "tax_inclusive": false
      }
    ]
  }
}'