Manifest Reference

Sample Add-on Manifest

{
  "$schema": "https://api.servicem8.com/api_1.0/addonsdk/manifest-schema/v1.json",
  "name": "Hello World Addon",
  "version": "1.0",
  "iconURL": "https:\/\/go.servicem8.com\/images\/addon-sdk-sample-icon.png",
  "supportURL": "https:\/\/support.exampleaddon.com",
  "supportEmail": "support@exampleaddon.com",
  "addonTargetAudience": "Plumbing and electrical businesses in New South Wales, Australia (Australia/NSW), with 1 to 20 staff.",
  "oauth": {
    "scope": "create_jobs manage_customers"
  },
  "actions": [{
    "name": "Hello Action",
    "type": "online",
    "entity": "job",
    "iconURL": "https:\/\/go.servicem8.com\/images\/addon-sdk-sample-icon.png",
    "event": "hello_world_event",
    "location": "modal"
  }],
  "menuItems": [{
    "name": "Hello Menu",
    "type": "addon",
    "iconURL": "https:\/\/go.servicem8.com\/images\/addon-sdk-sample-icon.png",
    "event": "hello_world_event"
  }],
  "webhooks": [{
    "object": "job",
    "fields": [
      "job_address",
      "billing_address"
    ]
  }]
}

Manifest validation

The sample declares the v1 manifest JSON Schema using $schema. JSON editors that support JSON Schema can use this declaration to validate fields while you edit. The schema's stable identifier is urn:servicem8:addon-manifest:v1; the URL stays pinned to v1, and a future breaking v2 will have a separate URL.

GET https://api.servicem8.com/api_1.0/addonsdk/manifest-schema/v1.json returns the schema directly as application/schema+json, without an envelope. No API key, OAuth token or account feature flag is required. Other methods return 405 Method Not Allowed with Allow: GET.

The endpoint serves the same v1 schema used by ServiceM8's server-side manifest validation. Editor validation does not replace server-side checks, including plain-text FAQ requirements, callback configuration, OAuth scopes and the 64 KB total encoded manifest limit. Server-side validation also applies when $schema is omitted.

JSON Parameters

name

The name of your Add-on

version

The version of your add-on, you should increase your version number with each release of your add-on to the store.

This add-on release version is independent of the manifest schema version. For example, an add-on release "2.0" can still use the v1 manifest schema.

iconURL

A publicly accessible image url where your add-on icon is available. This icon will be used for your add-on within the ServiceM8 Add-on Store. Icon will automatically be resized down to required size so we recommend an icon size of at least 512x512px.

supportURL

A URL where ServiceM8 customers can visit if they need support using your add-on.

supportEmail

An email address where ServiceM8 customers can get in contact if they need support using your add-on.

addonTargetAudience

An optional string describing your add-on's geographic coverage (global, country-specific or region-specific), industries and business size. For example, Australia/NSW means New South Wales, Australia.

When supplied, the value must be nonblank plain text without HTML or Markdown, with a maximum of 2,000 Unicode characters. Omit it when unavailable. addonTargetAudience and supportFAQ are independent: you can supply either, both or neither. The 64 KB total encoded manifest limit still applies.

supportFAQ

An optional, ordered array of 1–10 objects containing question and answer, used to improve Add-on Store recommendations and helpdesk guidance. Omit the field when no FAQs are supplied. You choose all questions and their order. See Support FAQs for plain-text and size limits, and a copyable manifest example.

oauth[scope]

If you are using Serverless OAuth, ServiceM8 will complete the OAuth flow between clients and your add-on during activation. Specify your OAuth scope here as a space-separated list of scope requirements. This setting will determine what API scope your STS access token is issued with.

actions

Actions are an Add-on capability to add new buttons to the Job Card or Client Card. Actions are not mandatory, and a single add-on can include many actions if required.

actions[name] `Mandatory`

Name is the name that will be displayed to the user for the new action in either the web platform or app.

actions[type] `Mandatory`

Type is the type of action you wish to create. If you wish to support multiple types, add several action records to your manifest. Valid values are:

online: Your add-on action will appear in the online web platform job/client cards
app: Your add-on action will appear in the app job/client cards

actions[entity] `Mandatory`

Entity is which card you wish to extend with your action. If you wish to support multiple entities, add several actions to your manifest. Valid values are:

job: Your add-on action will appear in the Job card
company: Your add-on action will appear in the Client card

actions[iconURL] `Mandatory`

A publicly accessible image URL for the action icon. This will appear inside the job/client card for users. Icon should relate to the action that will be undertaken to give users context of what action they are taking. Icon will automatically be resized down to required size so we recommend an icon size of 256x256px.

actions[event] `Mandatory`

The event name to be invoked on your add-on backend (Simple Function or web service). Event context is provided automatically (job, company, account, etc) as part of the invoked request.

📘
Event names are case-insensitive. It's good practice to always use lower case event names, as your function will receive the event name in lower case. Using lower case in the original event name will prevent confusion.

actions[location]

Location is only supported on web platform, app always uses window. Defaults to modal for online actions, and window for app actions.

Location is where your action should be presented to the user. Valid values are:

modal: Your action will be presented in a popup window, inside the ServiceM8 UI
window: Your action will be presented in a new tab/window, outside the ServiceM8 UI
Use only when linking the user to a second app/UI, otherwise modal is recommended.

menuItems

Menu Items are an Add-on capability to add new ServiceM8 menu items to the web platform (under the Addons menu), or to the ServiceM8 app (under the More menu). Menu Items are not mandatory, and a single add-on can include many menu items if required.

menuItems[name] `Mandatory`

Name is the name that will be displayed to the user for the new menu item in either the web platform or app.

menuItems[type] `Mandatory`

Type is the type of menu item you wish to create. If you wish to support multiple menu items, add several menuItem records to your manifest. Valid values are:

addon: Your menu item will appear in the online Addons menu
app: Your menu item will appear in the app more tab menu

menuItems[iconURL] `Mandatory`

A publicly accessible image URL for the menu icon. Icon should relate to the action that will be undertaken to give users context of what action they are taking. Icon will automatically be resized down to required size so we recommend an icon size of 256x256px.

menuItems[event] `Mandatory`

Each action must provide either an event or an actionURL

📘
Event names are case-insensitive. It's good practice to always use lower case event names, as your function will receive the event name in lower case. Using lower case in the original event name will prevent confusion.

The event name to be invoked on your add-on backend (Simple Function or web service) when users clicks on the menu item.

webhooks

Webhooks enable your add-on to subscribe to changes in account data, by specifying an object and which object fields are relevant you will receive webhook_subscription to allow you to take event-based actions. Webhooks are optional within a manifest. You should always subscribe to the minimal object/field combination that meets your requirements, as each change will invoke your addon for processing.

webhooks[object] `Mandatory`

The object you wish to subscribe to for change notifications. Objects are the same as API Endpoints - so review API documentation for available endpoints for subscription.

webhooks[fields] `Mandatory`

An array of fields you wish to be notified if any changes occur. Fields that can be subscribed to match the API endpoints - so review API documentation for available objects/fields for subscription.

preferences

An optional array of static settings for your Add-on. ServiceM8 generates the controls under Settings → Preferences → Add-ons in the online web platform, grouped under your Add-on's name and ordered as they appear in the array. Staff with Settings and Preferences access can edit the values. Settings belong to the account and are shared by its staff; they are not per-staff preferences.

📘
Supported hosting
Preferences are supported only for ServiceM8-hosted Simple Function Add-ons. Externally hosted web services and AWS Lambda functions hosted in your own AWS account are not supported.

Declare up to 10 preferences. Omit preferences, or set it to an empty array, if your Add-on has no settings. Add the following fragment to your manifest:

{
  "preferences": [
    {
      "key": "quote_title",
      "name": "Quote title",
      "type": "text",
      "default": "Your quote",
      "maxLength": 100,
      "description": "The heading used for new quotes."
    },
    {
      "key": "quote_notes",
      "name": "Default notes",
      "type": "textarea",
      "default": "Please confirm access before installation.",
      "maxLength": 500,
      "description": "Additional instructions included with each quote."
    },
    {
      "key": "include_installation",
      "name": "Include installation",
      "type": "boolean",
      "default": true,
      "description": "Include installation in the quote by default."
    },
    {
      "key": "default_enclosure",
      "name": "Default enclosure",
      "type": "select",
      "default": "side_alley",
      "options": [
        { "value": "side_alley", "name": "Side Alley" },
        { "value": "balcony", "name": "Balcony" }
      ],
      "description": "The enclosure style selected for new quotes."
    }
  ]
}

Preference properties

Property	Required	Description
`key`	Yes	A unique, stable identifier within your Add-on, matching `^[a-z][a-z0-9_]*$`: a lowercase letter followed by lowercase letters, digits or underscores.
`name`	Yes	A non-blank string used as the field label.
`type`	Yes	One of `text`, `textarea`, `boolean` or `select`. See the controls below.
`default`	Yes	A value matching the declared type and its constraints. Use a JSON boolean for `boolean`, and a string for the other types. `null` is not supported.
`description`	No	Plain-text help of at most 250 Unicode code points, including whitespace.
`maxLength`	No	A non-negative integer limiting the number of Unicode code points in a `text` or `textarea` value. Not supported for other types.
`options`	For `select`	A non-empty array of objects containing only `value` and `name`. Each `value` must be a unique string, each `name` a non-blank string, and `default` must match one of the values.

Type	Preferences control	Value received by your function
`text`	Single-line text field	String
`textarea`	Multiline text field	String
`boolean`	Yes/No dropdown	`true` or `false`
`select`	Dropdown using the supplied options	Selected option's string `value`, not its display name

Names, descriptions and option labels are plain text. ServiceM8 controls their typography and spacing. HTML, Markdown and CSS in these strings are displayed literally, not rendered as formatting. Character limits apply to the decoded strings before escaping.

Unsupported preference properties or types, including number, are rejected. Options are static: dynamic choices, conditional fields, nested settings and executable validators are not supported. Defaults must satisfy maxLength or select membership where applicable. The complete manifest remains subject to its 64 KB size limit.

Saved values and manifest changes

ServiceM8 stores all saved preferences for one Add-on in one account-specific JSON record. The complete serialized record, including keys, values and JSON syntax, must fit within 65,536 bytes (64 KB). This is a byte limit, not a character limit; JSON escaping can increase the stored size. A save exceeding the limit is rejected without changing the stored record.

This storage is separate from the Add-on SDK key/value API. It is not intended for passwords or secrets, and Add-ons cannot write these preferences through an API. Users edit them on the Preferences page. Saving different fields is independent; a page save is not a single transaction across every field.

ServiceM8 uses the manifest default only when a key has no saved value. Saved false, "0" and empty strings are preserved. Reading defaults does not save them.
Changing a label preserves the value. Changing a default affects only keys without saved values.
Keep keys stable. Use a new key when changing a preference's type; there is no automatic type migration.
Removing a definition hides its control and removes the key from event data. Its stored value is retained for rollback and still counts toward the storage limit.
If a saved value no longer matches an updated constraint or option list, it remains visible and is delivered unchanged. Preferences shows a correction message, and the next save must satisfy the updated definition.
Deactivating an Add-on hides its preferences and retains the saved values. Ineligible Add-ons cannot display, save or receive preferences.

Your hosted function receives current values through the top-level event.preferences object, with no additional OAuth scope or API request.

Sample Add-on Manifest

Manifest validation

JSON Parameters

name

version

iconURL

supportURL

supportEmail

addonTargetAudience

supportFAQ

oauth[scope]

actions

actions[name] Mandatory

actions[type] Mandatory

actions[entity] Mandatory

actions[iconURL] Mandatory

actions[event] Mandatory

Event names are case-insensitive. It's good practice to always use lower case event names, as your function will receive the event name in lower case. Using lower case in the original event name will prevent confusion.

actions[location]

menuItems

menuItems[name] Mandatory

menuItems[type] Mandatory

menuItems[iconURL] Mandatory

menuItems[event] Mandatory

Event names are case-insensitive. It's good practice to always use lower case event names, as your function will receive the event name in lower case. Using lower case in the original event name will prevent confusion.

webhooks

webhooks[object] Mandatory

webhooks[fields] Mandatory

preferences

Supported hosting

Preference properties

Saved values and manifest changes

actions[name] `Mandatory`

actions[type] `Mandatory`

actions[entity] `Mandatory`

actions[iconURL] `Mandatory`

actions[event] `Mandatory`

menuItems[name] `Mandatory`

menuItems[type] `Mandatory`

menuItems[iconURL] `Mandatory`

menuItems[event] `Mandatory`

webhooks[object] `Mandatory`

webhooks[fields] `Mandatory`