> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/servicem8.md).

# ServiceM8

Manage jobs, clients, and scheduling for field-service businesses.

## Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector | Authentication |
| --------- | -------------- |
| ServiceM8 | API key        |

### ServiceM8

Connect ServiceM8 to manage jobs, clients, and scheduling.

#### Set up in ServiceM8

1. Prepare the ServiceM8 account or service that the workflow will access. Grant access to the required resources and operations.
2. **API key:** Create an API key in ServiceM8 under Settings > API Keys.

#### Set up in StackAI

1. Open **Settings → Connections**, add a connection, and select **ServiceM8**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required | What to enter                                                                                                                           |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| API key       | Yes      | Create an API key in ServiceM8 under Settings > API Keys. [Provider instructions](https://developer.servicem8.com/docs/authentication). |

### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

## Use an action

1. Add the required **ServiceM8** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

## Actions

### List Jobs

Find ServiceM8 jobs, optionally filtered by status, client, or last-modified time. Deleted (inactive) jobs are left out unless you include them. Returns at most Maximum jobs (blank means 50); if more jobs matched, truncated is set and next\_cursor is left blank, so narrow the filters (for example Modified after) or set Maximum jobs to 1000 and page through with next\_cursor.

#### Inputs

| Field                 | Type            | Required | Description                                                                                                                                                                          |
| --------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Status                | select (string) | No       | Only show jobs in this stage. Leave blank for every status. Available values: Quote, Work Order, Unsuccessful, Completed.                                                            |
| Client                | select (string) | No       | Only show jobs for this client. Leave blank for every client. Options load from the selected connection.                                                                             |
| Show advanced options | boolean         | No       | Reveal the last-modified filter, deleted-job toggle, result cap, and page cursor. Default: false.                                                                                    |
| Modified after        | datetime        | No       | Only show jobs changed after this date and time. A time with a UTC offset is converted to the ServiceM8 account's time zone; a time without one is read as the account's local time. |
| Include deleted jobs  | boolean         | No       | Also show jobs that were deleted in ServiceM8. Default: false.                                                                                                                       |
| Maximum jobs          | integer         | No       | The most jobs to return in one run. Leave blank for 50. Minimum: 1. Maximum: 1000. Default: 50.                                                                                      |
| Page cursor           | string          | No       | Continue from an earlier run's next cursor.                                                                                                                                          |

#### Outputs

| Field       | Type          | Description                                                      |
| ----------- | ------------- | ---------------------------------------------------------------- |
| Jobs        | object\_array | The jobs found.                                                  |
| Next cursor | string        | Pass this back to get more jobs.                                 |
| Truncated   | boolean       | True when more jobs matched than Maximum jobs allowed to return. |

### Create Client

Add a new client (customer) record to ServiceM8, with an optional address, billing address, and website (blank fields are left empty in ServiceM8). ServiceM8 does not deduplicate clients: running this twice with the same name creates two separate client records. Because a rerun cannot resume a create, if this action fails, check ServiceM8 for a duplicate before running it again.

#### Inputs

| Field                 | Type     | Required | Description                                                                                 |
| --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------- |
| Client name           | string   | Yes      | The client's business or person name.                                                       |
| Address               | textarea | No       | The client's street address. Leave blank to store no address.                               |
| Show advanced options | boolean  | No       | Reveal the billing address and website fields. Default: false.                              |
| Billing address       | textarea | No       | Where invoices go, if different from the address. Leave blank to bill to the address above. |
| Website               | string   | No       | The client's website. Leave blank to store none.                                            |

#### Outputs

| Field             | Type   | Description                      |
| ----------------- | ------ | -------------------------------- |
| Client UUID       | string | The new client's ID.             |
| Open in ServiceM8 | string | Link to the client in ServiceM8. |

### Create Job

Create a new job in ServiceM8, optionally for an existing client, with a site address, description, and purchase order number (blank fields are left empty in ServiceM8). A blank Status creates a Quote. ServiceM8 does not deduplicate jobs: running this twice creates two separate job records. Because a rerun cannot resume a create, if this action fails, check ServiceM8 for a duplicate before running it again.

#### Inputs

| Field                 | Type            | Required | Description                                                                                                                |
| --------------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| Status                | select (string) | No       | The job's starting stage. Blank means Quote. Available values: Quote, Work Order, Unsuccessful, Completed. Default: Quote. |
| Client                | select (string) | No       | The client this job is for. Leave blank for no client. Options load from the selected connection.                          |
| Job address           | textarea        | No       | Where the work happens. Leave blank to store no address.                                                                   |
| Description           | textarea        | No       | What work the job needs. Leave blank to store no description.                                                              |
| Show advanced options | boolean         | No       | Reveal the purchase order number field. Default: false.                                                                    |
| Purchase order number | string          | No       | The client's PO reference. Leave blank to store none.                                                                      |

#### Outputs

| Field             | Type   | Description                   |
| ----------------- | ------ | ----------------------------- |
| Job UUID          | string | The new job's ID.             |
| Open in ServiceM8 | string | Link to the job in ServiceM8. |

### Create Job Activity

Book a staff member onto a job for a time window, putting them on the ServiceM8 schedule (a side effect visible to the whole team). Blank Activity type means Scheduled; set it to Recorded to log time already worked instead. Start and end with a UTC offset are converted to the ServiceM8 account's time zone; without one they are read as the account's local time. ServiceM8 does not deduplicate activities: running this twice books the same staff member twice. Because a rerun cannot resume a create, if this action fails, check the ServiceM8 schedule before running it again.

#### Inputs

| Field         | Type            | Required | Description                                                                                                                                                                                                                                           |
| ------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Job           | select (string) | Yes      | The job to book. Options load from the selected connection.                                                                                                                                                                                           |
| Staff member  | select (string) | Yes      | Who does the work. Options load from the selected connection.                                                                                                                                                                                         |
| Start         | datetime        | Yes      | When the work starts, on a 15-minute step (:00, :15, :30, or :45; seconds are dropped). A time with a UTC offset is converted to the ServiceM8 account's time zone; a time without one is read as the account's local time.                           |
| End           | datetime        | Yes      | When the work ends. Must be after the start and on a 15-minute step (:00, :15, :30, or :45; seconds are dropped). A time with a UTC offset is converted to the ServiceM8 account's time zone; a time without one is read as the account's local time. |
| Activity type | select (string) | No       | Booking ahead (Scheduled) or logging past work (Recorded). Blank means Scheduled. Available values: Scheduled, Recorded. Default: scheduled.                                                                                                          |

#### Outputs

| Field         | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Activity UUID | string | The new activity's ID. |

### Add Job Note

Add a text note to a ServiceM8 job's diary, visible to the whole team. ServiceM8 does not deduplicate notes: running this action twice adds two separate notes. Because a rerun cannot resume a create, if this action fails, check the job's diary in ServiceM8 before running it again.

#### Inputs

| Field | Type            | Required | Description                                                            |
| ----- | --------------- | -------- | ---------------------------------------------------------------------- |
| Job   | select (string) | Yes      | The job to add the note to. Options load from the selected connection. |
| Note  | textarea        | Yes      | The note text.                                                         |

#### Outputs

| Field     | Type   | Description        |
| --------- | ------ | ------------------ |
| Note UUID | string | The new note's ID. |

## Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/servicem8.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
