Add-On for Travel In Schedule

Developer API & SDK
1

Hi guys,

We’re looking at building a private add-on for our pest control business and just wanted to check whether something is possible before we get too far into it.

Basically, when we schedule jobs for our technicians, we’d like the add-on to automatically insert a 30-minute travel block between appointments on the Staff Schedule.

Ideally, the travel blocks would:

  • Show as a separate grey unavailable block on the calendar, without needing a customer job card.

  • Be assigned to the individual technician.

  • Allow us to manually change the duration or remove the block.

  • Automatically adjust when appointments are moved or cancelled.

We’ve been looking at the Availability API, but can’t determine whether it supports this.

Could you confirm whether this is possible through the API and, if so, which endpoint and field values we’d need to use?

We’re planning to build this using the new ServiceM8 Addon Kit.

Thanks for your help.

2

Hi Lee,

The Availability API provides create, read, update and delete operations. Here’s the API surface available for your add-on.

Availability endpoints

All paths below are relative to https://api.servicem8.com/api_1.0:

  • Create: POST /availability.json, requiring manage_schedule.
  • Read: GET /availability/{uuid}.json, requiring read_schedule.
  • Change the time range: POST /availability/{uuid}.json, requiring manage_schedule, using start_timestamp and end_timestamp.
  • Remove: DELETE /availability/{uuid}.json, requiring manage_schedule. Deletion sets active to 0 and hides the record in the UI.

The create/update fields include regarding_object, regarding_object_uuid, name, availability_type, start_timestamp and end_timestamp. The timestamp examples use YYYY-MM-DD HH:MM:SS. When creating a record without supplying a UUID, the new UUID is returned in the x-record-uuid response header.

See the Create Availability reference and Update Availability reference.

Responding to booking changes

Job Activity supports webhooks, and your add-on can declare subscriptions in its manifest’s webhooks section. Notifications identify the changed record and fields; your function then retrieves the record to obtain its current values.

For booking data, GET /jobactivity/{uuid}.json requires read_schedule and exposes job_uuid, staff_uuid, start_date and end_date. This gives your add-on the job, technician and timing information for an appointment.

Using Addon Kit

For these read/write operations, include read_schedule manage_schedule in oauth.scope in your addon.jsonc, and request those scopes when logging in:

npx addon-kit login --scopes "read_schedule manage_schedule"

Addon Kit requires the function’s API scopes in both the manifest and the deploying credential; its default manage_addons scope alone is for managing add-ons, not reading or writing schedule data.

We’ll confirm with the team whether Availability supports your complete travel-block workflow, including the exact technician/unavailability field values, a separate grey block without a job card, manual duration changes/removal in Staff Schedule, and how those blocks should be maintained when appointments move or are cancelled.

Thanks,
Cody