ServiceM8 API Essential Guide

What type of API does ServiceM8 provide?

REST API

• ServiceM8 offers a REST API that allows developers to connect ServiceM8 to third-party applications.

• The API is implemented as plain JSON over HTTP using REST commands - GET, POST and DELETE.

• Every resource, like Job, Company or JobActivity, has its own URL and is manipulated in isolation.

• The API closely follows REST principles and is described as easy to use.

Key Features

• The API can be explored through any browser for GET requests.

• It uses JSON for data formatting.

• It follows REST architectural principles like resource-based URLs and standard HTTP methods.

• Documentation is provided for getting started, authentication, HTTP response codes, etc.

Comparison to Other API Types

While ServiceM8 uses REST, it's worth noting how this compares to other common API types:

• SOAP APIs use XML and are more complex, often used for enterprise applications requiring high security.

• GraphQL APIs allow clients to request specific data in a single query, which can be more efficient for some use cases.

• gRPC APIs are designed for high performance and use protocol buffers.

REST APIs like ServiceM8's are widely used for web and mobile applications due to their simplicity and flexibility compared to these other types.

Does the ServiceM8 API have webhooks?

Yes, the official ServiceM8 API does have webhooks. Here are the key points about ServiceM8's webhook functionality:

Webhook Availability

• Webhooks are available through the ServiceM8 Webhooks API.
• They are only available for Public Applications that implement OAuth 2.0 authentication.

Subscribing to Webhooks

• You can create, update, and delete webhook subscriptions using the Webhooks API endpoint: https://api.servicem8.com/webhook_subscriptions.
• When subscribing, you need to specify:
  • A callback URL that will receive the webhook events
  • The object type the subscription applies to

Supported Object Types

While the documentation doesn't provide an exhaustive list of supported object types, some examples include:

• job
• client
• material
• task
• form
• attachment

The exact list of supported object types may vary, so it's best to check the latest API documentation or contact ServiceM8 support for a complete list.

Webhook Events

Webhooks are triggered when fields on the subscribed object change. The webhook payload includes:

• The object type
• The UUID of the changed object
• A list of fields that changed
• A timestamp of the change (in UTC)
• A resource URL to fetch the full object data

Handling Webhooks

• Your callback URL needs to handle both verification requests and actual webhook events.
• For verification, you need to echo back a challenge parameter.
• For webhook events, you'll receive a JSON payload with the changed object details.

Best Practices

• Use HTTPS for your callback URL for security.
• Implement proper error handling and respect the response codes from ServiceM8.
• Remember that webhook payloads don't include the new field values - you need to fetch those using the REST API.

In summary, ServiceM8's webhook system allows you to subscribe to changes on various object types, providing real-time updates for your integrated applications.

Rate Limits and other limitations

Based on the search results provided, here are the key points regarding the API Rate Limits of the ServiceM8 API:

Rate Limits

1. The ServiceM8 API has two main rate limits:

   • 180 requests per minute
   • 20,000 requests per day

2. If either of these limits is reached, the API will return a HTTP 429 response code with the message "Number of allowed API requests per minute exceeded".

Key Points to Consider

• Throttling is applied on a per-application and per-account basis. This means that if you have a single application connected to two different clients' ServiceM8 accounts, throttling is applied separately to each account.

• API developers are encouraged to anticipate these rate limits and take appropriate measures such as:

  • Using cached values from previous calls
  • Passing on messages to end users
  • Retrying requests at a later time

• The daily limit of 20,000 requests is a fixed limit and does not change based on the size of the account or number of jobs.

• The rate limits apply to all types of requests, including those triggered by webhooks and regular data synchronization.

Best Practices

1. Implement proper error handling for 429 responses in your application.

2. Use caching strategies to reduce the number of API calls when possible.

3. Spread out non-urgent API calls over time to avoid hitting the rate limits.

4. For large-scale operations, consider batching requests or using bulk endpoints if available.

5. Monitor your API usage to stay within the limits and optimize your integration.

Additional Information

• There is a separate Message Sending Quota for email and SMS messages, which has its own limits and is calculated on a rolling 24-hour basis.

• If you consistently need higher limits, you may be able to request a quota increase by opening a Sending Quota Increase ticket with ServiceM8 support.

It's important to note that these rate limits can significantly impact large-scale operations or integrations with high-volume data synchronization needs. If you're experiencing issues with these limits, you may need to optimize your integration strategy or discuss potential solutions with ServiceM8 support.

Latest API Version

Based on the search results provided, there is no specific mention of the most recent version of the ServiceM8 API. However, I can provide some relevant information about the ServiceM8 API:

API Overview

The ServiceM8 API is a REST API that allows developers to integrate with ServiceM8 and connect it to third-party applications. Here are some key points:

• It is implemented as plain JSON over HTTP using REST commands – GET, POST, and DELETE.
• Each resource (e.g., Job, Company, JobActivity) has its own URL and is manipulated in isolation.
• The API closely follows REST principles and is designed to be easy to use.
• You can explore the GET part of the API through any browser.

API Endpoints

While the search results don't mention a specific version number, they do provide information about some API endpoints:

• Job Contacts: https://api.servicem8.com/api_1.0/jobcontact.json
• Company Contacts: https://api.servicem8.com/api_1.0/companycontact.json

The presence of api_1.0 in these URLs suggests that the current version might be 1.0, but this is not explicitly stated.

Key Considerations

1. Authentication: The API requires authentication, but the specific method is not mentioned in the search results.

2. Naming Conventions: The API uses different terminology compared to the ServiceM8 user interface. For example, "Client/Customer" in the UI is referred to as "Company" in the API.

3. Filtering: The API supports filtering, which can be useful for retrieving specific data.

4. Add-on SDK: ServiceM8 provides an Add-on SDK for developers who want to create add-ons for the platform.

Best Practices

1. Use appropriate HTTP methods (GET, POST, DELETE) for different operations.

2. Familiarize yourself with the naming conventions used in the API to avoid confusion.

3. Utilize filtering when querying data to improve efficiency and retrieve only the necessary information.

4. Consult the official ServiceM8 developer documentation for the most up-to-date and accurate information about the API.

In conclusion, while the most recent version of the ServiceM8 API is not explicitly stated in the search results, the available information suggests that it might be version 1.0. For the most accurate and up-to-date information about the API version, it's recommended to consult the official ServiceM8 developer documentation or contact their support directly.

How to get a ServiceM8 developer account and API Keys?

To get a developer account for ServiceM8 and create an API integration, you'll need to follow these steps:

1. Sign up as a Development Partner

1. Log in to your ServiceM8 account.
2. Click on the "Developer" link in the main menu.

2. Create a Public Application

1. After logging in as a Development Partner, you'll be able to create a new application.
2. Once you save your add-on, you'll be issued an App Id and App Secret.

3. Implement OAuth 2.0 Authentication

To allow your add-on to access customer's ServiceM8 accounts, you'll need to implement OAuth 2.0 authentication. This involves:

1. Initiating authentication by redirecting users to the ServiceM8 OAuth authorization URL.
2. Exchanging the temporary token for a permanent access token.
3. Using the access token to make API requests.

Key Points to Consider:

• You can create a Public Application without making it publicly available on the ServiceM8 Add-on Store.
• Ensure you keep your App Secret secure, as it allows access to connected ServiceM8 accounts.
• Consider which scopes your application needs access to and request only the necessary permissions.

Best Practices:

1. Use incremental authorization to request permissions as needed, improving user experience.
2. Keep your App Secret confidential to maintain security.
3. Implement user impersonation when necessary to respect user-specific permissions.
4. Familiarize yourself with the naming conventions used in the REST API, as they may differ from the ServiceM8 UI.

By following these steps and best practices, you'll be able to set up a developer account and create an API integration with ServiceM8.

What can you do with the ServiceM8 API?

Based on the search results, here are the key data models you can interact with using the ServiceM8 API, along with what is possible for each:

Jobs

• Create, retrieve, update and delete jobs
• Filter jobs based on criteria like status, date, company UUID
• Attach files to job diary
• Post updates to job activity feed

Companies (Clients/Customers)

• Create, retrieve, update and delete company records
• Sync client data with accounting packages

Materials

• Manage materials/line items on quotes and invoices

Job Activities

• Schedule bookings
• Record time (check-ins to jobs)

Attachments

• Add quotes, invoices, work orders to job diary
• Add photos to job diary

Custom Fields

• Add custom fields to extend data models

Vendors (ServiceM8 Accounts)

• Manage vendor/account data

Email Messages

• Send emails on behalf of ServiceM8 accounts

Text Messages

• Send SMS/text messages on behalf of ServiceM8 accounts

Activity Feed

• Post status updates and messages to the activity feed

PDF Documents

• Generate PDF documents like quotes and invoices

Key points:

• Uses REST API with JSON over HTTP
• Supports GET, POST, DELETE methods
• Each resource has its own URL
• Can filter and query data
• Integrates with accounting packages like MYOB, Xero, QuickBooks
• Allows extending functionality through custom add-ons and integrations

The API provides comprehensive access to core ServiceM8 data and functionality, allowing developers to build integrations and custom solutions on top of the platform.