Manage badges - the coloured labels used to tag and categorise jobs and clients for filtering and reporting. Create, list, retrieve, update, and delete badges applied across the account.
openapi: 3.0.3
info:
title: ServiceM8 REST API
description: >-
ServiceM8 is field service and job management software for trade and
home-service businesses. The REST API is plain JSON over HTTP and closely
follows REST principles: every resource (Job, Company, JobActivity,
Attachment, and so on) has its own URL and is manipulated in isolation using
GET, POST, and DELETE. The base URL is https://api.servicem8.com/api_1.0 and
each object type is exposed as a `.json` collection - for example
GET /company.json lists companies and GET /company/{uuid}.json retrieves one.
Creating a record is a POST to the collection; updating a record is a POST to
the record URL; deleting is a DELETE to the record URL.
Private integrations authenticate with an API key sent in the `X-API-Key`
header. Public add-ons authenticate with OAuth 2.0 (authorize at
https://go.servicem8.com/oauth/authorize, exchange the code at
https://go.servicem8.com/oauth/access_token) and send a Bearer access token.
Naming note: the ServiceM8 user interface term "Client" or "Customer" maps to
the "Company" object in the API. Only a subset of ServiceM8 functionality is
modeled here; ServiceM8 documents 60+ objects. Object endpoint filenames other
than company.json, jobcontact.json, and companycontact.json (which are
confirmed in ServiceM8's own documentation) are modeled from ServiceM8's
documented resource index and its consistent lowercase object naming
convention.
version: '1.0'
contact:
name: ServiceM8 Developer
url: https://developer.servicem8.com
license:
name: ServiceM8 API Terms
url: https://www.servicem8.com/terms
servers:
- url: https://api.servicem8.com/api_1.0
description: ServiceM8 REST API (object endpoints)
- url: https://api.servicem8.com
description: ServiceM8 webhook subscription endpoints
security:
- apiKeyAuth: []
- oauth2: []
tags:
- name: Jobs
description: Jobs - the central record for a piece of work.
- name: Job Activities
description: Scheduled bookings and recorded time entries on a job.
- name: Clients
description: Companies (clients/customers) and their contacts.
- name: Job Contacts
description: People attached to a specific job (billing, site, etc.).
- name: Staff
description: Staff members - technicians and office users.
- name: Materials
description: Materials catalog and job material line items.
- name: Attachments
description: Files linked to jobs - photos, PDFs, signed documents.
- name: Queues
description: Workflow stages jobs move through.
- name: Vendors
description: ServiceM8 account records an integration operates against.
- name: Badges
description: Coloured labels used to tag jobs and clients.
- name: Webhooks
description: Object and event webhook subscriptions.
paths:
/job.json:
get:
operationId: listJobs
tags: [Jobs]
summary: List jobs
description: Lists jobs in the account. Supports OData-style $filter on fields.
parameters:
- $ref: '#/components/parameters/Filter'
responses:
'200':
description: An array of job records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Job'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/Throttled'
post:
operationId: createJob
tags: [Jobs]
summary: Create a job
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
responses:
'200':
description: Job created. The new record UUID is returned in the x-record-uuid header.
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/Throttled'
/job/{uuid}.json:
parameters:
- $ref: '#/components/parameters/Uuid'
get:
operationId: getJob
tags: [Jobs]
summary: Retrieve a job
responses:
'200':
description: A single job record.
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: updateJob
tags: [Jobs]
summary: Update a job
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
responses:
'200':
description: Job updated.
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteJob
tags: [Jobs]
summary: Delete a job
responses:
'200':
description: Job deleted.
'404':
$ref: '#/components/responses/NotFound'
/jobactivity.json:
get:
operationId: listJobActivities
tags: [Job Activities]
summary: List job activities
parameters:
- $ref: '#/components/parameters/Filter'
responses:
'200':
description: An array of job activity records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/JobActivity'
'429':
$ref: '#/components/responses/Throttled'
post:
operationId: createJobActivity
tags: [Job Activities]
summary: Create a job activity
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobActivity'
responses:
'200':
description: Job activity created.
/jobactivity/{uuid}.json:
parameters:
- $ref: '#/components/parameters/Uuid'
get:
operationId: getJobActivity
tags: [Job Activities]
summary: Retrieve a job activity
responses:
'200':
description: A single job activity record.
content:
application/json:
schema:
$ref: '#/components/schemas/JobActivity'
post:
operationId: updateJobActivity
tags: [Job Activities]
summary: Update a job activity
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobActivity'
responses:
'200':
description: Job activity updated.
delete:
operationId: deleteJobActivity
tags: [Job Activities]
summary: Delete a job activity
responses:
'200':
description: Job activity deleted.
/company.json:
get:
operationId: listCompanies
tags: [Clients]
summary: List companies (clients)
description: Lists client companies. In the ServiceM8 UI these are Clients/Customers.
parameters:
- $ref: '#/components/parameters/Filter'
responses:
'200':
description: An array of company records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Company'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createCompany
tags: [Clients]
summary: Create a company
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
responses:
'200':
description: Company created.
/company/{uuid}.json:
parameters:
- $ref: '#/components/parameters/Uuid'
get:
operationId: getCompany
tags: [Clients]
summary: Retrieve a company
responses:
'200':
description: A single company record.
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
post:
operationId: updateCompany
tags: [Clients]
summary: Update a company
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
responses:
'200':
description: Company updated.
delete:
operationId: deleteCompany
tags: [Clients]
summary: Delete a company
responses:
'200':
description: Company deleted.
/companycontact.json:
get:
operationId: listCompanyContacts
tags: [Clients]
summary: List company contacts
parameters:
- $ref: '#/components/parameters/Filter'
responses:
'200':
description: An array of company contact records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CompanyContact'
post:
operationId: createCompanyContact
tags: [Clients]
summary: Create a company contact
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyContact'
responses:
'200':
description: Company contact created.
/companycontact/{uuid}.json:
parameters:
- $ref: '#/components/parameters/Uuid'
get:
operationId: getCompanyContact
tags: [Clients]
summary: Retrieve a company contact
responses:
'200':
description: A single company contact record.
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyContact'
post:
operationId: updateCompanyContact
tags: [Clients]
summary: Update a company contact
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyContact'
responses:
'200':
description: Company contact updated.
delete:
operationId: deleteCompanyContact
tags: [Clients]
summary: Delete a company contact
responses:
'200':
description: Company contact deleted.
/jobcontact.json:
get:
operationId: listJobContacts
tags: [Job Contacts]
summary: List job contacts
parameters:
- $ref: '#/components/parameters/Filter'
responses:
'200':
description: An array of job contact records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/JobContact'
post:
operationId: createJobContact
tags: [Job Contacts]
summary: Create a job contact
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobContact'
responses:
'200':
description: Job contact created.
/jobcontact/{uuid}.json:
parameters:
- $ref: '#/components/parameters/Uuid'
get:
operationId: getJobContact
tags: [Job Contacts]
summary: Retrieve a job contact
responses:
'200':
description: A single job contact record.
content:
application/json:
schema:
$ref: '#/components/schemas/JobContact'
post:
operationId: updateJobContact
tags: [Job Contacts]
summary: Update a job contact
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobContact'
responses:
'200':
description: Job contact updated.
delete:
operationId: deleteJobContact
tags: [Job Contacts]
summary: Delete a job contact
responses:
'200':
description: Job contact deleted.
/staff.json:
get:
operationId: listStaff
tags: [Staff]
summary: List staff members
parameters:
- $ref: '#/components/parameters/Filter'
responses:
'200':
description: An array of staff records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Staff'
post:
operationId: createStaff
tags: [Staff]
summary: Create a staff member
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Staff'
responses:
'200':
description: Staff member created.
/staff/{uuid}.json:
parameters:
- $ref: '#/components/parameters/Uuid'
get:
operationId: getStaff
tags: [Staff]
summary: Retrieve a staff member
responses:
'200':
description: A single staff record.
content:
application/json:
schema:
$ref: '#/components/schemas/Staff'
post:
operationId: updateStaff
tags: [Staff]
summary: Update a staff member
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Staff'
responses:
'200':
description: Staff member updated.
delete:
operationId: deleteStaff
tags: [Staff]
summary: Delete a staff member
responses:
'200':
description: Staff member deleted.
/material.json:
get:
operationId: listMaterials
tags: [Materials]
summary: List materials
parameters:
- $ref: '#/components/parameters/Filter'
responses:
'200':
description: An array of material records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Material'
post:
operationId: createMaterial
tags: [Materials]
summary: Create a material
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Material'
responses:
'200':
description: Material created.
/material/{uuid}.json:
parameters:
- $ref: '#/components/parameters/Uuid'
get:
operationId: getMaterial
tags: [Materials]
summary: Retrieve a material
responses:
'200':
description: A single material record.
content:
application/json:
schema:
$ref: '#/components/schemas/Material'
post:
operationId: updateMaterial
tags: [Materials]
summary: Update a material
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Material'
responses:
'200':
description: Material updated.
delete:
operationId: deleteMaterial
tags: [Materials]
summary: Delete a material
responses:
'200':
description: Material deleted.
/jobmaterial.json:
get:
operationId: listJobMaterials
tags: [Materials]
summary: List job materials
description: Line items (materials/labour) added to a specific job.
parameters:
- $ref: '#/components/parameters/Filter'
responses:
'200':
description: An array of job material records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/JobMaterial'
post:
operationId: createJobMaterial
tags: [Materials]
summary: Create a job material
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobMaterial'
responses:
'200':
description: Job material created.
/jobmaterial/{uuid}.json:
parameters:
- $ref: '#/components/parameters/Uuid'
get:
operationId: getJobMaterial
tags: [Materials]
summary: Retrieve a job material
responses:
'200':
description: A single job material record.
content:
application/json:
schema:
$ref: '#/components/schemas/JobMaterial'
post:
operationId: updateJobMaterial
tags: [Materials]
summary: Update a job material
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobMaterial'
responses:
'200':
description: Job material updated.
delete:
operationId: deleteJobMaterial
tags: [Materials]
summary: Delete a job material
responses:
'200':
description: Job material deleted.
/attachment.json:
get:
operationId: listAttachments
tags: [Attachments]
summary: List attachments
description: >-
Lists attachment metadata records. The binary file itself is fetched or
uploaded at /attachment/{uuid}.file.
parameters:
- $ref: '#/components/parameters/Filter'
responses:
'200':
description: An array of attachment records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Attachment'
post:
operationId: createAttachment
tags: [Attachments]
summary: Create an attachment record
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Attachment'
responses:
'200':
description: Attachment metadata created. Upload the file bytes to /attachment/{uuid}.file.
/attachment/{uuid}.json:
parameters:
- $ref: '#/components/parameters/Uuid'
get:
operationId: getAttachment
tags: [Attachments]
summary: Retrieve an attachment record
responses:
'200':
description: A single attachment record.
content:
application/json:
schema:
$ref: '#/components/schemas/Attachment'
post:
operationId: updateAttachment
tags: [Attachments]
summary: Update an attachment record
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Attachment'
responses:
'200':
description: Attachment updated.
delete:
operationId: deleteAttachment
tags: [Attachments]
summary: Delete an attachment
responses:
'200':
description: Attachment deleted.
/attachment/{uuid}.file:
parameters:
- $ref: '#/components/parameters/Uuid'
get:
operationId: downloadAttachmentFile
tags: [Attachments]
summary: Download attachment file bytes
responses:
'200':
description: The binary contents of the attachment.
content:
application/octet-stream:
schema:
type: string
format: binary
post:
operationId: uploadAttachmentFile
tags: [Attachments]
summary: Upload attachment file bytes
requestBody:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: File uploaded for the attachment record.
/queue.json:
get:
operationId: listQueues
tags: [Queues]
summary: List queues
parameters:
- $ref: '#/components/parameters/Filter'
responses:
'200':
description: An array of queue records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Queue'
post:
operationId: createQueue
tags: [Queues]
summary: Create a queue
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Queue'
responses:
'200':
description: Queue created.
/queue/{uuid}.json:
parameters:
- $ref: '#/components/parameters/Uuid'
get:
operationId: getQueue
tags: [Queues]
summary: Retrieve a queue
responses:
'200':
description: A single queue record.
content:
application/json:
schema:
$ref: '#/components/schemas/Queue'
post:
operationId: updateQueue
tags: [Queues]
summary: Update a queue
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Queue'
responses:
'200':
description: Queue updated.
delete:
operationId: deleteQueue
tags: [Queues]
summary: Delete a queue
responses:
'200':
description: Queue deleted.
/vendor.json:
get:
operationId: listVendors
tags: [Vendors]
summary: List vendors
description: Returns the connected ServiceM8 account (vendor) record(s).
responses:
'200':
description: An array of vendor records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Vendor'
/vendor/{uuid}.json:
parameters:
- $ref: '#/components/parameters/Uuid'
get:
operationId: getVendor
tags: [Vendors]
summary: Retrieve a vendor
responses:
'200':
description: A single vendor (account) record.
content:
application/json:
schema:
$ref: '#/components/schemas/Vendor'
/badge.json:
get:
operationId: listBadges
tags: [Badges]
summary: List badges
parameters:
- $ref: '#/components/parameters/Filter'
responses:
'200':
description: An array of badge records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Badge'
post:
operationId: createBadge
tags: [Badges]
summary: Create a badge
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Badge'
responses:
'200':
description: Badge created.
/badge/{uuid}.json:
parameters:
- $ref: '#/components/parameters/Uuid'
get:
operationId: getBadge
tags: [Badges]
summary: Retrieve a badge
responses:
'200':
description: A single badge record.
content:
application/json:
schema:
$ref: '#/components/schemas/Badge'
post:
operationId: updateBadge
tags: [Badges]
summary: Update a badge
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Badge'
responses:
'200':
description: Badge updated.
delete:
operationId: deleteBadge
tags: [Badges]
summary: Delete a badge
responses:
'200':
description: Badge deleted.
/webhook_subscriptions:
servers:
- url: https://api.servicem8.com
get:
operationId: listWebhookSubscriptions
tags: [Webhooks]
summary: List webhook subscriptions
responses:
'200':
description: An array of webhook subscription records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WebhookSubscription'
post:
operationId: createWebhookSubscription
tags: [Webhooks]
summary: Create or update an object webhook subscription
description: >-
Subscribe to changes on specific fields of an object type. When a
subscribed field changes, ServiceM8 POSTs the object type, changed
fields, uuid, and a resource_url to your callback URL.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscription'
responses:
'200':
description: Webhook subscription created or updated.
/webhook_subscriptions/{uuid}:
servers:
- url: https://api.servicem8.com
parameters:
- $ref: '#/components/parameters/Uuid'
get:
operationId: getWebhookSubscription
tags: [Webhooks]
summary: Retrieve a webhook subscription
responses:
'200':
description: A single webhook subscription record.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscription'
delete:
operationId: deleteWebhookSubscription
tags: [Webhooks]
summary: Delete a webhook subscription
responses:
'200':
description: Webhook subscription deleted.
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: API key for private/single-account integrations.
oauth2:
type: oauth2
description: OAuth 2.0 for public add-ons. Access tokens expire after 3600 seconds.
flows:
authorizationCode:
authorizationUrl: https://go.servicem8.com/oauth/authorize
tokenUrl: https://go.servicem8.com/oauth/access_token
refreshUrl: https://go.servicem8.com/oauth/access_token
scopes:
manage_jobs: Read and write jobs
read_jobs: Read jobs
manage_customers: Read and write customers (companies)
read_customers: Read customers (companies)
manage_staff: Read and write staff
read_staff: Read staff
manage_inventory: Read and write materials and inventory
manage_schedule: Read and write scheduling and job activities
publish_sms: Send SMS messages
publish_email: Send email messages
vendor_logo: Read vendor account information
parameters:
Uuid:
name: uuid
in: path
required: true
description: The UUID of the record.
schema:
type: string
Filter:
name: $filter
in: query
required: false
description: >-
OData-style filter expression, e.g. `$filter=active eq 1` or
`edit gt '2026-01-01'`. Filtering is supported on indexed fields.
schema:
type: string
responses:
Unauthorized:
description: Missing or invalid API key / access token.
NotFound:
description: The requested record does not exist.
Throttled:
description: >-
Rate limit exceeded (180 requests/minute or 20,000 requests/day). Body is
the text "Number of allowed API requests per minute exceeded".
schemas:
Job:
type: object
properties:
uuid:
type: string
active:
type: integer
description: 1 for active, 0 for deleted.
created_by_staff_uuid:
type: string
date:
type: string
company_uuid:
type: string
description: UUID of the client Company this job is for.
generated_job_id:
type: string
status:
type: string
description: Quote, Work Order, Invoice, Complete, or Unsuccessful.
job_address:
type: string
job_description:
type: string
work_done_description:
type: string
queue_uuid:
type: string
total_invoice_amount:
type: string
edit:
type: string
description: Last edit timestamp.
JobActivity:
type: object
properties:
uuid:
type: string
active:
type: integer
job_uuid:
type: string
staff_uuid:
type: string
start_date:
type: string
end_date:
type: string
activity_was_scheduled:
type: integer
activity_was_recorded:
type: integer
Company:
type: object
description: A client/customer (called Company in the API).
properties:
uuid:
type: string
active:
type: integer
name:
type: string
email:
type: string
website:
type: string
billing_address:
type: string
address:
type: string
is_individual:
type: integer
badges:
type: string
description: Comma-separated list of badge UUIDs.
CompanyContact:
type: object
properties:
uuid:
type: string
active:
type: integer
company_uuid:
type: string
first:
type: string
last:
type: string
email:
type: string
phone:
type: string
mobile:
type: string
type:
type: string
JobContact:
type: object
properties:
uuid:
type: string
active:
type: integer
job_uuid:
type: string
first:
type: string
last:
type: string
email:
type: string
phone:
type: string
mobile:
type: string
type:
type: string
description: JOB, BILLING, Property Owner, or Property Manager.
Staff:
type: object
properties:
uuid:
type: string
active:
type: integer
first:
type: string
last:
type: string
email:
type: string
mobile:
type: string
job_title:
type: string
security_role_uuid:
type: string
Material:
type: object
properties:
uuid:
type: string
active:
type: integer
name:
type: string
description:
type: string
price:
type: string
cost:
type: string
tax_rate_uuid:
type: string
JobMaterial:
type: object
properties:
uuid:
type: string
active:
type: integer
job_uuid:
type: string
material_uuid:
type: string
name:
type: string
quantity:
type: string
price:
type: string
cost:
type: string
displayed_amount:
type: string
Attachment:
type: object
properties:
uuid:
type: string
active:
type: integer
related_object:
type: string
description: The object type this attaches to, e.g. job or company.
related_object_uuid:
type: string
attachment_name:
type: string
file_type:
type: string
description: File extension, e.g. .jpg or .pdf.
photo_width:
type: string
photo_height:
type: string
Queue:
type: object
properties:
uuid:
type: string
active:
type: integer
name:
type: string
email:
type: string
sort_order:
type: integer
Vendor:
type: object
properties:
uuid:
type: string
name:
type: string
email:
type: string
plan:
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/servicem8/refs/heads/main/openapi/servicem8-openapi.yml