ServiceM8 Clients API

openapi: 3.0.3
info:
  title: ServiceM8 REST Attachments Clients 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: Clients
  description: Companies (clients/customers) and their contacts.
paths:
  /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.
components:
  schemas:
    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
    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.
  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.
  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