iOS Deep Links

Use deep links to take a user directly to a ServiceM8 screen, such as a job's billing tab, a client record or a staff conversation. Links open the installed ServiceM8 iOS app in the user's signed-in account. The user completes any editing, sending or payment steps in the app.

URL format

Use the externally registered com.servicem8 scheme:

com.servicem8://<area>[/<record-reference>][/<screen>...]

For example, open the billing tab of job number 123:

com.servicem8://job/123/billing

Or link to a job by its UUID:

com.servicem8://job/5b8329c8-25a6-4c68-b03a-5b5ec319df2a

Replace every placeholder in the tables below, including its angle brackets, with an actual value. Use record UUIDs from the ServiceM8 API. Only job references also accept a generated job number; other record references use UUIDs. Child references must identify records belonging to the specified parent job or client.

Route keywords are case-insensitive; identifiers retain their original case. Use the spelling shown for query parameter names. Unknown screens and extra path components are not supported. Do not append a path or query parameter to perform an undocumented action.

The servicem8:// scheme is used internally by the app but is not registered for opening from another app or website. External integrations should use com.servicem8:// or one of the HTTPS universal links documented below.

Opening a link

From a website, use a normal link activated by the user:

<a href="com.servicem8://job/123/billing">Open job billing in ServiceM8</a>

Custom-scheme links require ServiceM8 to be installed on the iPhone or iPad. They do not provide a browser or App Store fallback. Tell users to install ServiceM8 if the app cannot be opened.

Deep links use the current app account and staff permissions; they do not authenticate API requests or grant access to a record. The app waits for its authenticated main screen to be ready before handling a screen link. Records must be accessible in that account, and some screens require the record to have synced to the device. A missing record, disabled feature or restricted screen can prevent the destination from opening.

Available screens depend on the installed app version, account features and device. Opening the app successfully does not confirm that the requested screen opened or that an action completed.

App screens

On iPad, schedule selects the Schedule tab when it is available. Otherwise, including on iPhone, it opens the Jobs My Schedule filter. On iPads using the sidebar layout, there is no More tab; use a link to the specific destination instead of more.

Jobs

<job-ref> is a job UUID or generated job number. Job links open the Jobs tab and then the requested job screen. Each screen respects the same access restrictions and feature availability as opening it manually.

com.servicem8://jobdiary/<job-ref> is also supported as an alias for the job Diary. The task/new route is for legacy Tasks; accounts using the newer Checklist system should use checklist/new.

Use a form definition UUID for form/<form-uuid> and a form response UUID for form-response/<form-response-uuid>. An incomplete form response opens for editing; a completed response opens for viewing. For an existing billing item, use the job material UUID, not the material catalogue UUID.

Prefilling a new job

The existing new-job link also accepts ?data=<base64-json> to prefill the wizard. Encode a JSON object as UTF-8, Base64-encode it, then percent-encode the result as a query parameter value. For example, the JSON can specify an existing client and a job address:

{
  "companyUUID": "5b8329c8-25a6-4c68-b03a-5b5ec319df2a",
  "jobAddress": "123 Example Street"
}

com.servicem8://job/new?data=<base64-json>

The user still reviews and completes the New Job wizard. Base64 is an encoding, not encryption; do not include credentials in a URL.

Clients

<client-uuid> is the UUID of the client (Company) record. Client screens require an active client available on the device and access to Clients.

Every client route also accepts clients or company in place of client. The contact UUID identifies a contact belonging to that client.

Inbox and staff messages

messages is an alias for message, including messages/new. Inbox links require access to Inbox. Messaging links require access to staff messaging; channels additionally require the staff-channel feature to be enabled. Direct-message and new-message links use the messaging interface available to the account.

To target a message within a channel, append the optional message query parameter with a valid message UUID:

com.servicem8://staffchannel/<channel-uuid>?message=<message-uuid>

The same modifier is accepted on the channel details route. Without a valid target message UUID, the channel opens without targeting a particular message.

Invoicing and tasks

Invoicing requires the user's invoicing permission. The Tasks list opens the legacy Tasks or newer Checklist screen available to the account. Task detail links apply only to legacy Tasks; there is no corresponding Checklist item detail link.

Knowledge and assets

Knowledge requires access to Knowledge. Article and asset detail links require an active record available on the device. The app chooses the appropriate viewer for the account's enabled features.

Settings and other screens

These destinations respect the user's menu access and account features. Profile requires the Profile feature. Business Dashboard uses the native dashboard when available or the app's authenticated web dashboard otherwise.

Job lists, filters and queues

These established shortcuts remain supported:

Use the UUID of an existing saved filter or job queue accessible in the account.

HTTPS universal links

Use these HTTPS links for Job and Client detail destinations:

Both require a UUID; generated job numbers are not accepted. The OpenJob and OpenClient route names are case-insensitive. When iOS hands the link to ServiceM8, the app opens the corresponding record. Browser handling depends on the user's context; see the Add-on SDK FAQ for returning to the app and opening a job in the browser.

These are not general HTTPS equivalents of every custom-scheme route. For job subviews such as Billing, use com.servicem8://job/<job-ref>/billing rather than appending /billing to an OpenJob link.

Unsupported destinations

There are no screen links for notification detail, individual invoice/payment detail, Checklist item detail, Settings subpages, or arbitrary nested screens. A /new route is an entry point to that specific workflow; it does not imply support for a corresponding /<uuid> route unless listed above.

Use only the documented routes. In particular, opening a screen is not a server API call and does not provide a completion callback for saving, sending or charging.