Servicem8 | Composio Docs

Overview

SLUG: SERVICEM8

Description

ServiceM8 helps field service businesses schedule jobs, send quotes, and manage invoices, offering staff mobile apps and real-time job status tracking

Authentication Details

OAuth2

client_id

stringRequired

client_secret

stringRequired

full

stringDefaults to https://api.servicem8.comRequired

oauth_redirect_uri

stringDefaults to https://backend.composio.dev/api/v1/auth-apps/add

scopes

stringDefaults to staff_locations,staff_activity,publish_sms,publish_email,vendor,vendor_logo,vendor_email,read_locations,manage_locations,read_staff,manage_staff,read_customers,manage_customers,read_customer_contacts,manage_customer_contacts,read_jobs,manage_jobs,create_jobs,read_job_contacts,manage_job_contacts,read_job_materials,manage_job_materials,read_job_categories,manage_job_categories,read_job_queues,manage_job_queues,read_tasks,manage_tasks,read_schedule,manage_schedule,read_inventory,manage_inventory,read_job_notes,publish_job_notes,read_job_photos,publish_job_photos,read_job_attachments,publish_job_attachments,read_inbox,read_messages,manage_notifications,manage_templates,manage_badges,read_assets,manage_assets

bearer_token

string

Connecting to Servicem8

Create an auth config

Use the dashboard to create an auth config for the Servicem8 toolkit. This allows you to connect multiple Servicem8 accounts to Composio for agents to use.

Select App

Navigate to Servicem8.

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

Create and Get auth config ID

Click “Create Servicem8 Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using OAuth2

1 from composio import Composio
2 
3 # Replace these with your actual values
4 servicem8_auth_config_id = "ac_YOUR_SERVICEM8_CONFIG_ID" # Auth config ID created above
5 user_id = "0000-0000-0000"  # UUID from database/application
6 
7 composio = Composio()
8 
9 
10 def authenticate_toolkit(user_id: str, auth_config_id: str):
11     connection_request = composio.connected_accounts.initiate(
12         user_id=user_id,
13         auth_config_id=auth_config_id,
14     )
15 
16     print(
17         f"Visit this URL to authenticate Servicem8: {connection_request.redirect_url}"
18     )
19 
20     # This will wait for the auth flow to be completed
21     connection_request.wait_for_connection(timeout=15)
22     return connection_request.id
23 
24 
25 connection_id = authenticate_toolkit(user_id, servicem8_auth_config_id)
26 
27 # You can also verify the connection status using:
28 connected_account = composio.connected_accounts.get(connection_id)
29 print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Servicem8 toolkit’s playground

OpenAI (Python)

Anthropic (TypeScript)

Google (Python)

Vercel (TypeScript)

Python

1 from composio import Composio
2 from openai import OpenAI
3 import json
4 
5 openai = OpenAI()
6 composio = Composio()
7 
8 # User ID must be a valid UUID format
9 user_id = "0000-0000-0000"  # Replace with actual user UUID from your database
10 
11 tools = composio.tools.get(user_id=user_id, toolkits=["SERVICEM8"])
12 
13 print("[!] Tools:")
14 print(json.dumps(tools))
15 
16 def invoke_llm(task = "What can you do?"):
17     completion = openai.chat.completions.create(
18         model="gpt-4o",
19         messages=[
20             {
21                 "role": "user",
22                 "content": task,  # Your task here!
23             },
24         ],
25         tools=tools,
26     )
27 
28     # Handle Result from tool call
29     result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30     print(f"[!] Completion: {completion}")
31     print(f"[!] Tool call result: {result}")
32 
33 invoke_llm()

Tool List

SERVICEM8_CREATE_JOBS

Tool Name: Create a new Job

Description

Tool to create a new job in servicem8. use when you have gathered all job details and need to push a record. example: "create a quote job for 123 main st with po #1234."

Action Parameters

active

integerDefaults to 1

badges

array

category_uuid

string

company_uuid

string

created_by_staff_uuid

string

date

string

job_address

stringRequired

job_description

string

purchase_order_number

string

queue_uuid

string

status

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_CREATE_JOB_NOTE

Tool Name: ServiceM8 Create Job Note

Description

Tool to create a new job note in servicem8. use when you need to attach additional information to a specific job after obtaining its uuid.

Action Parameters

action_completed_by_staff_uuid

string

action_required

string

active

integerDefaults to 1

create_date

string

note

stringRequired

related_object

stringRequired

related_object_uuid

stringRequired

uuid

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_CREATE_JOB_PAYMENT

Tool Name: ServiceM8 Create Job Payment

Description

Tool to create a new job payment in servicem8. use when you have collected payment details and need to record payment against a job. example: "create a 100.00 cash payment for job 123e4567-e89b-12d3-a456-426614174000 at 2023-01-01 13:00:00."

Action Parameters

actioned_by_uuid

stringRequired

active

integerRequired

amount

stringRequired

attachment_uuid

string

edit_date

stringRequired

is_deposit

integer

job_uuid

stringRequired

method

stringRequired

note

string

timestamp

stringRequired

uuid

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_DELETE_JOB_NOTE

Tool Name: Delete Job Note

Description

Tool to delete a specific job note. use when you need to archive a note by its uuid.

Action Parameters

uuid

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_DELETE_JOB_PAYMENT

Tool Name: ServiceM8 Delete Job Payment

Description

Tool to delete (archive) a specific job payment by its uuid. use when you need to archive a payment record.

Action Parameters

uuid

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_LIST_ALL_ASSETS

Tool Name: List All Assets

Description

Tool to list all servicem8 assets. use when you need a comprehensive asset registry, including custom fields, for inventory or reporting.

Action Parameters

filter

string

Action Response

data

arrayRequired

error

string

successful

booleanRequired

SERVICEM8_LIST_ALL_CLIENTS

Tool Name: List All Clients

Description

Tool to list all servicem8 clients. use when you need a complete set of customer records for integrations or reporting.

Action Parameters

filter

string

Action Response

data

arrayRequired

error

string

successful

booleanRequired

SERVICEM8_LIST_ALL_DOCUMENT_TEMPLATES

Tool Name: List All Document Templates

Description

Tool to list document templates. use when you need to retrieve available template uuids and names before generating job documents.

Action Parameters

filter

string

limit

integer

offset

integer

Action Response

data

arrayRequired

error

string

successful

booleanRequired

SERVICEM8_LIST_ALL_FORMS

Tool Name: List All Forms

Description

Tool to list all servicem8 forms. use when you need to fetch available form templates with optional filters.

Action Parameters

filter

string

Action Response

data

arrayRequired

error

string

successful

booleanRequired

SERVICEM8_LIST_ALL_JOBS

Tool Name: List All Jobs

Description

Tool to list all jobs. use when you need to fetch all job records from your servicem8 account.

Action Parameters

filter

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_LIST_ALL_JOB_NOTES

Tool Name: List All Job Notes

Description

Tool to list all job notes in servicem8. use when you need to fetch notes, optionally filtered or paginated.

Action Parameters

filter

string

limit

integer

offset

integer

Action Response

data

arrayRequired

error

string

successful

booleanRequired

SERVICEM8_LIST_ALL_JOB_QUEUES

Tool Name: List All Job Queues

Description

Tool to list all job queues in servicem8. use when you need to fetch configured queues before dispatching jobs.

Action Parameters

Action Response

data

arrayRequired

error

string

successful

booleanRequired

SERVICEM8_LIST_ALL_LOCATIONS

Tool Name: List All Locations

Description

Tool to list all servicem8 locations. use when you need to fetch every configured location for assignments or mapping.

Action Parameters

Action Response

data

arrayRequired

error

string

successful

booleanRequired

SERVICEM8_LIST_ALL_MATERIALS

Tool Name: List All Materials

Description

Tool to list all materials. use when you need a full inventory dump after authenticating with read inventory scope.

Action Parameters

Action Response

data

arrayRequired

error

string

successful

booleanRequired

SERVICEM8_LIST_ALL_TASKS

Tool Name: List All Tasks

Description

Tool to list all tasks in a servicem8 account. use when you need to fetch task records, optionally filtered. requires 'read tasks' oauth scope.

Action Parameters

filter

string

limit

integer

offset

integer

Action Response

data

arrayRequired

error

string

successful

booleanRequired

SERVICEM8_RETRIEVE_CLIENT

Tool Name: Retrieve ServiceM8 Client

Description

Tool to retrieve details of a specific client by its uuid. use after confirming the client's uuid is valid.

Action Parameters

uuid

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_RETRIEVE_FORM

Tool Name: Retrieve Form

Description

Tool to retrieve details of a specific form by its uuid. use when you need up-to-date form metadata given a known form uuid.

Action Parameters

uuid

Required

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_RETRIEVE_JOB

Tool Name: Retrieve Job

Description

Tool to retrieve details of a specific job by its uuid. use when you have the job uuid and need its full record.

Action Parameters

uuid

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_RETRIEVE_JOB_ACTIVITY

Tool Name: Retrieve Job Activity

Description

Tool to retrieve details of a specific job activity by its uuid. use when you have the job activity uuid and need its full details.

Action Parameters

uuid

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_RETRIEVE_JOB_NOTE

Tool Name: Retrieve Job Note

Description

Tool to retrieve details of a specific job note by its uuid. use when you have the note uuid (e.g., after listing notes) and need its full record before processing or display.

Action Parameters

uuid

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_RETRIEVE_JOB_PAYMENT

Tool Name: Retrieve Job Payment

Description

Tool to retrieve details of a specific job payment by its uuid. use when you have the payment uuid and need its full record and metadata.

Action Parameters

uuid

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_RETRIEVE_JOB_QUEUE

Tool Name: Retrieve Job Queue

Description

Tool to retrieve details of a specific job queue by its uuid. use when you need full queue metadata before dispatching work.

Action Parameters

uuid

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_RETRIEVE_LOCATION

Tool Name: Retrieve Location

Description

Tool to retrieve details of a specific location by its uuid. use when you already have the location's uuid and need full location details.

Action Parameters

uuid

Required

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_RETRIEVE_MATERIAL

Tool Name: Retrieve ServiceM8 Material

Description

Tool to retrieve details of a specific material by its uuid. use when you have a material uuid and need current inventory or pricing details.

Action Parameters

uuid

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_RETRIEVE_STAFF_MEMBER

Tool Name: Retrieve Staff Member

Description

Tool to retrieve details of a specific staff member by their uuid. use when you need up-to-date staff information given a known staff uuid.

Action Parameters

uuid

Required

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_SERVICE_M8_CREATE_JOB

Tool Name: ServiceM8 Create Job

Description

Tool to create a new job in servicem8. use when you have all job details and need to push a record into servicem8. example: "create a quote job for 123 main st with po #1234."

Action Parameters

active

integerDefaults to 1

badges

array

category_uuid

string

company_uuid

string

created_by_staff_uuid

string

date

string

job_address

stringRequired

job_description

string

purchase_order_number

string

queue_uuid

string

status

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_UPDATE_JOB_NOTE

Tool Name: Update a ServiceM8 Job Note

Description

Tool to update details of an existing job note. use when modifying a note after its creation.

Action Parameters

active

integer

edit_date

string

note

string

uuid

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SERVICEM8_UPDATE_JOB_PAYMENT

Tool Name: ServiceM8 Update Job Payment

Description

Tool to update details of an existing job payment. use after confirming the payment uuid and desired changes.

Action Parameters

actioned_by_uuid

string

active

integer

amount

stringRequired

attachment_uuid

string

edit_date

string

is_deposit

integer

job_uuid

stringRequired

method

string

note

string

timestamp

string

uuid

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired