Schedule a job visit

POST/api/v1/jobs/{job_id}/visits

A visit added to a completed job makes the job active again, so there is no need to reopen it first. A cancelled job refuses new visits until it is reopened.

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 createJobVisit.

Parameters

In the address

job_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.

visitobjectrequired
Fields(11)
- 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)

Responses

201Visit details.

dataobjectrequired
Fields(33)
- lock_versionintegerrequired
  At least 0.
- created_atstring (date-time)required
- updated_atstring (date-time)required
- idstring (uuid)required
- account_idstring (uuid)required
- job_idstring (uuid) or nullrequired
- job_titlestring or null
- job_lock_versioninteger or null
  At least 0.
- purposestring
  One of: work, quote_assessment.
- customer_idstring (uuid)
- property_idstring (uuid) or null
- titlestring or null
- assessment_notesstring or null
- quote_idstring (uuid) or null
  Current unarchived assessment quote.
- has_quotesboolean
  Includes archived quotes; customer and property are fixed when true.
- jobobject
  Full updated job returned when a visit save includes job_title, or when completing this visit also completed its job. Replace the cached job using this record, never by advancing its version from the title metadata alone.
  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.
- statusstringrequired
  One of: scheduled, in_progress, completed, cancelled.
- scheduled_start_atstring (date-time)required
- scheduled_end_atstring (date-time)required
- actual_start_atstring (date-time) or null
- actual_end_atstring (date-time) or null
- instructionsstring or null
- completion_notesstring or null
- cancelled_atstring (date-time) or null
- reminder_sent_atstring (date-time) or null
  When the customer was emailed a reminder of this visit, or was told by moveCalendarDay that it had moved to today, tomorrow or the day after. Null when they have not been, and null again once moveCalendarDay moves the visit without telling them so.
  Read only.
- membership_idsarray of string (uuid)required
- visit_series_idstring (uuid) or null
- invoice_idstring (uuid) or null
  Set when this completed visit of a job billed `per_visit` or `monthly` is on a live invoice; cleared when that invoice is voided or archived.
- seriesobject or null
  The repeating visit this visit belongs to, if any.
  Fields(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.
- photosarray of objectrequired
  Oldest first.
  Each item(7)
  idstring (uuid)required
  filenamestringrequired
  content_typestringrequired
  byte_sizeintegerrequired
  At least 1.
  membership_idstring (uuid) or nullrequired
  Team member who added the photo. They and managers can remove it.
  urlstring (uri)required
  Signed link that expires after 24 hours. Refetch the visit for a fresh one; cache images by photo id, not by URL.
  created_atstring (date-time)required
- running_time_entriesarray of object
  Everyone clocked in to this visit right now.
  Each item(3)
  idstring (uuid)required
  membership_idstring (uuid)required
  started_atstring (date-time)required
- time_entryobject or null
  Only from startVisit with `track_time`; the caller's running entry on this visit.
  Fields(19)
  lock_versionintegerrequired
  At least 0.
  created_atstring (date-time)required
  updated_atstring (date-time)required
  idstring (uuid)required
  account_idstring (uuid)required
  job_idstring (uuid) or nullrequired
  job_titlestring or nullrequired
  job_numberstring or nullrequired
  visit_idstring (uuid) or null
  visit_titlestring or null
  purposestring
  `work` for job and work-visit time, `quote_assessment` for quote visit time.
  One of: work, quote_assessment.
  membership_idstring (uuid)required
  membership_namestringrequired
  recorded_by_idstring (uuid)required
  updated_by_idstring (uuid)required
  started_atstring (date-time)required
  ended_atstring (date-time) or nullrequired
  duration_secondsintegerrequired
  At least 0.
  notesstring or null
- stopped_time_entryobject or null
  Only from startVisit with `track_time`; the timer stopped elsewhere, or null.
  Fields(19)
  lock_versionintegerrequired
  At least 0.
  created_atstring (date-time)required
  updated_atstring (date-time)required
  idstring (uuid)required
  account_idstring (uuid)required
  job_idstring (uuid) or nullrequired
  job_titlestring or nullrequired
  job_numberstring or nullrequired
  visit_idstring (uuid) or null
  visit_titlestring or null
  purposestring
  `work` for job and work-visit time, `quote_assessment` for quote visit time.
  One of: work, quote_assessment.
  membership_idstring (uuid)required
  membership_namestringrequired
  recorded_by_idstring (uuid)required
  updated_by_idstring (uuid)required
  started_atstring (date-time)required
  ended_atstring (date-time) or nullrequired
  duration_secondsintegerrequired
  At least 0.
  notesstring or null

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/4088bebb-3a71-586f-922c-1612b3fa6557/visits" \
  -H "Authorization: Bearer $TRADESENDER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "visit": {
    "scheduled_start_at": "2026-10-13T09:00:00+01:00",
    "scheduled_end_at": "2026-10-13T11:00:00+01:00",
    "instructions": "The side gate is unlocked.",
    "membership_ids": [
      "379274bb-b710-5b2f-a775-bf99cae8e0ea"
    ]
  }
}'