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

Authentication

Private Applications

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.

Public Applications

Public applications will need to register their app from within their ServiceM8 Developer account to receive a client id and secret key. Using OAuth 2, applications can then connect to each user’s account through various endpoints.

The developer portal API examples demonstrate how to authenticate against the API as a private application, public applications authenticate by providing the same API endpoints with their access_token as authentication – meaning that user's email addresses and account passwords are not required.

For more information on how to authenticate with ServiceM8 as a public application, see Platform Services::Authentication.

Data Formats

Supported data formats for the request payload are XML and JSON. The following table lists the content type and encoding fields of the request sent to data services:

Request Header Description Example
Accept The desired format of the content body in the response. application/json
Accept-Encoding The desired content-coding in the response. To improve performance, you can set the Accept-Encoding request header to “gzip, deflate”. gzip, deflate

REST API Reading

The REST API has two modes of action 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 https://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 “https://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 https://api.servicem8.com/api_1.0/staff.json

 

Get details for a specific staff member

curl -u email:password https://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 
-H "Content-Type: application/json"
-H "Accept: application/json" 
-d '{"status": "Quote", "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 https://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 -H "Content-Type: application/json" -H "Accept: application/json" -d "{"status":"Work Order"}" -X POST https://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 https://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.

Date of Last Revision: June 4, 2015