Email the customer that someone is on the way

POST/api/v1/visits/{id}/on_my_way

Sends the visit's customer an email saying the caller is on the way and roughly when they will arrive. It goes to the email address on the customer, with the subject "[Your name] from [Business] is on the way", and replies go to the business. minutes is the wait the note gives. Without message the note is the account's "On my way" note; either way its placeholders are filled in: [First name], [Customer], [Business], [Your name], [Property] (the first line of the address) and [Arrival] ("30 minutes", or "an hour" for 60). It is listed among the customer's messages as on_my_way, and the answer is that message. For a visit that is scheduled or in_progress. Managers, and a technician assigned to the visit. It counts towards the 100 emails a day that sendQuote and sendInvoice share. Errors: 422 customer_has_no_email when the customer has no email address; 409 invalid_transition when the visit is completed or cancelled; 409 on_my_way_already_sent when anybody sent one for this visit in the last 5 minutes, so that two taps, or two people in one van, send the customer one email; 422 invalid_minutes; 422 message_too_long.

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

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.

minutesintegerrequired
Roughly how long until they arrive. It fills [Arrival] in the note.
One of: 15, 30, 45, 60.
messagestring or null
The note, in place of the account's "On my way" note. Placeholders in square brackets are filled in.
Up to 2000 characters.

Responses

200The email as it is listed among the customer's messages.

dataobjectrequired
Fields(14)
- idstring (uuid)required
- account_idstring (uuid)required
- customer_idstring (uuid)required
- kindstringrequired
  What the email was. `quote`: Quote emailed. `invoice`: Invoice emailed. `portal_link`: Portal link emailed. `invoice_reminder`: Payment reminder. `quote_follow_up`: Quote follow-up. `visit_reminder`: Visit reminder. `on_my_way`: On my way. `rescheduled`: Visit moved. `direct_debit_failed`: Direct Debit failed. `refund`: Refund.
  One of: quote, invoice, portal_link, invoice_reminder, quote_follow_up, visit_reminder, on_my_way, rescheduled, direct_debit_failed, refund.
- to_emailstring (email)required
  The address it was sent to, which may not be the one on the customer.
- subjectstringrequired
  The email's subject line.
- bodystringrequired
  The note the customer read, as plain text: the words above the link, not the whole email. It never holds a link that signs the customer in. Where a quote or invoice note had the customer's link it reads `[Link]`, and a sign-in link somebody typed into a note reads `portal=[removed]`.
- quote_idstring (uuid) or null
  The quote the email was about.
- invoice_idstring (uuid) or null
  The invoice the email was about.
- visit_idstring (uuid) or null
  The visit the email was about. The first of them, when one email covered several.
- membership_idstring (uuid) or null
  The member who sent it. Null when it was sent automatically.
- sent_atstring (date-time)required
  When the email was handed over for delivery. A message is written once and never changes.
- created_atstring (date-time)required
- updated_atstring (date-time)required

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/visits/d256e41f-3501-5cb6-9c63-1514f6995d01/on_my_way" \
  -H "Authorization: Bearer $TRADESENDER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "minutes": 30
}'