The ServiceM8 Developer Portal

Welcome to the ServiceM8 developer portal. You'll find comprehensive guides and documentation to help you start working with ServiceM8 as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Add-on Store Requirements

Before you begin

Here are some things to consider before developing an add-on for the ServiceM8 Add-on Store, to give it the best chance of approval and success.

  • Value: would your add-on “add value” to ServiceM8 and what customers’ can achieve? Review the existing core functionality and add-ons. Please don’t replicate existing functionality, or solve a problem that’s already been solved in a slightly different way.

  • Usefulness: does your idea for an add-on solve a problem, and have a clear use case? Would your add-on save time, or reward the business for time invested? Please don’t make an add-on in search of a problem, or that doesn’t provide real benefits.

  • Relevance: would your add-on be relevant, and solve for “good fit” ServiceM8 customers? This will ensure you maximise your add-on’s reach and impact.

  • Safety: would your add-on be safe to use? Please don’t make an add-on which could expose customers to legal or regulatory risk.

  • Support: can you support your add-on? Once released, you will be required to provide prompt customer support and maintain best-practice infrastructure behind your add-on for it to succeed and remain in the Add-on Store.

Also ensure you’ve read and understood ServiceM8’s Terms of Service, Privacy Policy & Partner Agreement.

Uniqueness

  • Third-party add-ons submitted for listing on the Add-on Store must be unique. If a submitted add-on has similar functionality to an existing add-on or area of ServiceM8 functionality, it should be clearly differentiated by providing different benefits and/or use cases. This should be apparent in all aspects of the add-on, including its name, listing, interface/s and functionality.

Branding

  • Your listing can’t portray your add-on as being developed or supported by ServiceM8 itself.
  • You can’t promote your company through any aspect of your add-on’s actual user interfaces or outputs.
  • Ensure “ServiceM8” is correctly spelled and capitalised wherever referenced in text throughout your add-on’s listing, help documentation and user interfaces.
  • Ensure “ServiceM8” is correctly pronounced in any audio (e.g. a voiceover to a help video). ServiceM8 is pronounced as one word i.e. “ServiceMate”.

Name

  • Add-on names must be unique.
  • Add-on names can’t exceed 30 characters in length.
  • Add-on names must be definite, and present consistently across their listing, help documentation, and user interfaces.
  • Add-on names can’t include the word “ServiceM8”, or any variation, abbreviation or allusion such as “M8”, “Mate” or “SM8”.
  • Add-on names can’t include or allude to the names of existing add-ons (e.g. “Automation Plus”) or discrete ServiceM8 features or concepts (e.g. “Advanced Email Templates”).
  • Add-on names can’t be a generic descriptor name such as “Task List”. You may include your company name in the title e.g. “Task List by MyCompany” is acceptable.
  • Add-on names shouldn't include descriptions or subtitles. These should be contained in the description fields.

Short & Long Descriptions

  • The first ‘Description’ under Item Details in your add-on management interface is your add-on’s “short” description. This is what appears under your add-on’s name in the Add-on Store. It should be concise and clearly summarise the overall functionality and value of your add-on.
  • The Long Description should provide sufficient detail for someone to understand what your add-on is, and what it can do for them. It should clearly explain the add-on’s purpose, functionality & benefits.
  • Add-on descriptions should be accurate, well-written and free of spelling and grammar mistakes.
  • The add-on listing (including images, videos & help documentation) should make it clear which ServiceM8 platforms the add-on supports i.e. is it used in the Online Dashboard only, or both the Online Dashboard & App?
  • Do not use an add-on’s description to promote your company and other add-ons you’ve developed. A brief attribution to your company and/or landing page URL is acceptable.
  • Avoid any language which implies that your add-on is superior to, or addresses a deficiency in, the core ServiceM8 feature set or other available add-ons.
  • If your Add-on listing is marked as “Free”, but you charge for your add-on externally (i.e. the integration is free, but your product is not), then you must make this clear in the add-on description.

Images & Video

  • Supplied images must demonstrate the add-on’s functionality across all platforms it operates.
  • Include at least 3 screenshots of the user interface/s of your add-on.
  • App screenshots should be placed in the relevant iOS device for optimal presentation & clarity.
  • Screenshots of an add-on’s interface/s must be accurate and represent your add-on’s real operation/presentation i.e. screenshots cannot be altered. Annotations or highlighting to draw attention to certain elements is acceptable.
  • Do not separately promote your company and any other add-ons you’ve developed in an add-on’s images or video.
  • Do not include any real business or personal information in any screenshots or footage.

Support

  • Help documentation must be provided. This can be in whichever format suits e.g. help article/s, help video/s, or a combination of approaches.
  • An add-on will not be approved without help documentation which encompasses the entire add-on’s onboarding, configuration, interfaces and workflows.
  • An actively-monitored support email address must be provided, which customers can use to contact you for support.
  • You must respond within a reasonable time to enquiries and support requests regarding your add-on. Developers who do not respond to enquiries and support requests may have their add-ons delisted from the Add-on Store.

Privacy Policy

  • A link to your own ServiceM8 Developer Privacy Policy must be provided in the ‘Privacy Policy’ field of the Add-on Store Details. Your privacy policy must describe what data you use from the user’s ServiceM8 account, what other data you collect as part of add-on usage, how data it is handled, stored, disclosed and retained, and the rights and responsibilities of each party.
  • Your privacy policy must follow best-practice privacy, security, and data-handling principles, comply with applicable privacy legislation in the regions supported, and uphold ServiceM8’s Privacy Policy.

Supported Regions

  • An add-on can be made available to ServiceM8 customers in more than one global region, provided there is nothing about the add-on which might limit its relevance, usefulness or performance in different regions.
  • If an add-on is designed for use in a specific jurisdiction, country, state or province of a region, it should be clear in the add-on’s listing.

Pricing

  • You may decide to charge for your add-on through ServiceM8’s billing system or manage billing yourself
  • If your Add-on Store listing is marked as “Free”, but you charge for your add-on externally (i.e. the integration is free, but your product is not), then you must make this clear in the add-on description.

Activation & Onboarding

  • In order to be listed on the ServiceM8 Add-on Store, add-ons must authenticate using OAuth 2.0. Add-ons which use HTTP Basic Auth will not be listed.
  • The ideal new-user experience is one in which the customer clicks “Connect” to activate your add-on, consents to allowing your add-on to access their account, and can then begin using your add-on immediately without creating a separate username/password.
  • Serverless Add-ons (Lambda Functions)
    • The activation process is completely managed within ServiceM8, and your add-on receives temporary OAuth tokens for each event.
  • Web Service Hosted Add-ons
    • When the user clicks Connect, they are redirected to your Activation URL which initiates the OAuth process
    • After your add-on obtains an OAuth token, you can inspect the Vendor and Staff endpoints to obtain details about the account and its users, and create an account (if required) based on these details
    • You should redirect the user back to ServiceM8 after you have obtained an OAuth token
    • Each time ServiceM8 calls your add-on for relevant events, you can inspect the Account UUID and Staff UUID contained in the event data to determine the account on your side
    • If your add-on requires that the user creates a separate account in order to access your add-on, then follow the guidelines for External Integrations.
  • External Integrations
    • For external integrations, the user will usually need to have a separate account in order to use your add-on.
    • When the user clicks Connect from your add-on’s store page, they will be sent to your configured Activation URL.
    • Your Activation URL should direct the user to an endpoint which begins the OAuth flow so your add-on can obtain an OAuth token
    • If the user is not logged in to your add-on when they reach this page, you should display a Login/Signup page to allow them to login or create a new account. You must ensure that the OAuth flow is started immediately after the user has authenticated. Do not redirect the user to a dashboard or welcome page.
    • After your add-on has obtained an OAuth token, you may redirect the user back to ServiceM8 or continue inside your add-on.
    • If you’re listing an integration with ServiceM8 on another website it must be clear that your business developed the integration.

Reservation of Rights

  • ServiceM8 is constantly improving & enhancing its platform, and reserves the right to develop any improvement, enhancement or add-on to the core ServiceM8 platform, regardless of any actual or perceived similarities to any add-on you may have submitted to the Add-on Store.
  • ServiceM8 does not grant any exclusive rights to listing in the ServiceM8 Add-on Store for the particular feature set or benefits your add-on provides. ServiceM8 may approve similar add-ons from other developers. ServiceM8 will not enter into correspondence or mediation to resolve disputes of this nature between developers.

Pre-submission checklist

Before submitting your add-on for review by the ServiceM8 team, please ensure it meets all Add-on Store requirements, and the below checklist:

  • The add-on is feature complete and works as described in its listing.
  • The add-on has been thoroughly tested in a live environment and is free of bugs and errors.
  • The add-on has been scoped with care and does not request more data or permissions than required to function as described.
  • All listing details are complete, accurate, and provide a concise overview and description of the add-on.
  • The listing is free of spelling and grammar mistakes.
  • The add-on’s interfaces are free of spelling and grammar mistakes.
  • Help documentation is complete and covers all aspects of the add-on.
  • Contact information in your Partner account is up to date.

Add-on Store Requirements


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.