Introduction

The ServiceM8 REST API allows developers to hook into ServiceM8 and connect it to third-party applications. Whether you're writing a plugin for an application or planning on hooking some internal application into ServiceM8, the API can do it for you.

The REST API is implemented as plain JSON over HTTP using the REST commands - GET, POST and DELETE. Every resource, like Job, Company or JobActivity, has their own URL and are manipulated in isolation. The API closely follows the REST principles and it's easy to use.

You can explore the GET part of the API through any browser.

API Throttle

To ensure continuous quality of service, API usage can be subject to throttling. The throttle will be applied once an API consumer reaches a certain threshold in terms of a maximum number of requests per minute. Most clients will never hit this threshold, but those that do, will get met by a HTTP 503 response code and a text body of "Number of allowed API requests per minute exceeded"

We encourage all API developers to anticipate this error, and take appropriate measures like e.g. using a cached value from a previous call, or passing on a message to the end user that gets subjected to this behaviour (if any).

Authentication

Use of the API is always through an existing user in ServiceM8. There's no special API user. You get to see and work with what the user you are logging in to the API is allowed to. You're required to add user credentials via HTTP Basic Authentication. Security is provided via SSL.

REST API Reading

The REST API has two modes of actions for reading - show and list. Show returns a single record and list returns a collection. Usually, there's just a single show action for each resource, but several lists. You can easily explore REST API reading through a browser, as all these actions are done through GET.

Examples

GET a list of jobs

curl -u email:password http://api.servicem8.com/api_1.0/job.json

This command issues a HTTP GET request to /job.json. It will return HTTP status code 200, and a JSON document listing the jobs in your account. If nothing is found, a HTTP 404 "not found" response will be returned. This is equivalent to typing in the URL "http://api.servicem8.com/api_1.0/job.json" in your browser, when logged on as the authenticated user.

GET a list of staff

curl -u email:password http://api.servicem8.com/api_1.0/staff.json

This is equivalent to the previous example, but returns a listing of staff in your account. Furthermore, you can specify a callback by appending “?callback=your_call_back_function” to the GET URL. See the Widgets section for JSON examples.

Get details for a specific staff member

curl -u email:password http://api.servicem8.com/api_1.0/staff/68da81d7-b260-4a02-8fa6-1f9bcd123994.json

If a staff member with the supplied UUID exists, a JSON response is generated along with the status code "200". The JSON response contains the staff data registered for the particular user. If nothing is found, the response HTTP 404 "not found" is returned.

REST API writing

When you're creating and updating REST resources, you'll be sending JSON into ServiceM8. Just include the JSON of the resource in the body of your request, and you're done.

A successful creation responds with the status code "201".

Updating resources is done through the POST command and against the URL of the resource you want to update. The response to a successful update is "200". When updating records, submit only the fields you wish to change.

Examples

POST (create) example - create new job

curl -u email:password \
    -d "{"job_address":"1 Infinite Loop, Cupertino, California 95014, United States","company_id":"Apple","description":"Client has requested quote for service delivery","contact_first":"John","contact_last":"Smith"}" \
    -X POST http://api.servicem8.com/api_1.0/job.json

This creates a new job, with a description, contact and job address. Note how company id can be a record id, or a lookup value to automatically match an existing record (or create a new company object record if no match is found).

POST (update) example - change job status

curl -u email:password \
    -d "{"status":"Work Order"}" \
    -X POST http://api.servicem8.com/api_1.0/job/d4345f09-d87a-4d54-89e2-dad4253ffc85.json

Sets the status of the job to (Work Order).

Deleting through the REST API

Finally, you can delete resources (if you're allowed to) using the DELETE command.

DELETE example - removing a staff member

curl -u email:password -X DELETE http://api.servicem8.com/api_1.0/staff/68da81d7-b260-4a02-8fa6-1f9bcd123994.json

This example deletes the staff member object with the UUID 68da81d7-b260-4a02-8fa6-1f9bcd123994.