ServiceM8 Smart Job Creation

CRM Project Management

v1.3.2

Last updated Apr 14, 2026

n8n node for creating ServiceM8 jobs with intelligent client/contact deduplication

28 Weekly Downloads

234 Monthly Downloads

View on NPM GitHub Repository

Included Nodes

ServiceM8 Smart Job Creation

Description

n8n-nodes-servicem8-jobcreation

A custom n8n community node for creating and updating ServiceM8 jobs with intelligent client/contact deduplication.

This node consolidates what would typically be a 50+ node workflow into a single, configurable node that handles:

Client lookup and matching
Contact deduplication
Business vs individual classification
Job creation with all optional features
Job updates with badges, attachments, and notes

Installation

Community Node (Recommended)

1. Go to Settings > Community Nodes
2. Select Install
3. Enter n8n-nodes-servicem8-jobcreation
4. Click Install

Manual Installation

npm install n8n-nodes-servicem8-jobcreation

Credentials

This node requires ServiceM8 API credentials. Create a new credential of type ServiceM8 API with your API key.

To get your API key:
1. Log into ServiceM8
2. Go to Settings > API & Webhooks
3. Generate or copy your API key

—

Operations

Create Job

Creates a new ServiceM8 job with intelligent client/contact deduplication.

#### How Deduplication Works

1. Contact Lookup: Searches for existing contacts by email > mobile > phone (in priority order)
2. Client Matching: If a contact is found, checks if it belongs to a matching client
3. Decision Matrix: Determines whether to use an existing client or create a new one based on:
– Name match quality (exact, partial, none)
– Address match quality (exact, near, none)
– Business vs individual classification

#### Required Fields

#### Contact Information

#### Business Information

#### Address Fields

#### Job Information

#### Optional Features

All optional features have an enable toggle. When enabled, additional configuration fields appear.

Each notification recipient has the following options:

Message Placeholders: Custom messages support these placeholders:

{{name}} – Recipient name
{{jobNumber}} – Job number (e.g., “J00123”)
{{clientName}} – Client/customer name
{{jobAddress}} – Job site address
{{jobDetails}} – Job description

Note: A system report note is always created with job creation details.

#### Additional Options

—

Update Job

Updates an existing ServiceM8 job with optional badges, attachments, and notes.

#### Job Selection

#### Update Fields

Collection of job fields that can be updated:

Status
Job Description
Job Address
And more (based on ServiceM8 API)

#### Optional Features

Add Badges: Same as Create operation
Upload Attachments: Same as Create operation
Add Note: Add a note to the job

#### Additional Options

—

Output Schema

Both operations return a fixed schema – all fields are always present (empty strings, false, or empty arrays when not applicable). This ensures predictable downstream processing.

Create Job Output

{
  "success": true,
  "error": "",
  "jobUuid": "abc-123-def-456",
  "jobNumber": "J00789",
  "clientUuid": "xyz-789-uvw-012",
  "action": "createdclientand_contact",
  "summary": {
    "clientCreated": true,
    "contactCreated": true,
    "categoryAssigned": true,
    "categoryName": "Plumbing",
    "categoryMissing": "",
    "badgesAssigned": ["Urgent", "VIP"],
    "badgesMissing": ["NonexistentBadge"],
    "queueAssigned": true,
    "queueName": "Today",
    "queueMissing": "",
    "notificationsSent": {
      "email": 2,
      "sms": 1
    },
    "attachmentsUploaded": ["invoice.pdf", "photo.jpg"],
    "attachmentsFailed": [],
    "noteAdded": true,
    "customNoteAdded": false
  },
  "debug": {
    "classification": "business",
    "contactLookupField": "email",
    "matchType": {
      "name": "exact",
      "address": "near"
    },
    "reason": "Exact name match with existing client",
    "clientsChecked": 45,
    "executionTimeMs": 1234
  },
  "createdRecords": {
    "clientUuid": "xyz-789-uvw-012",
    "companyContactUuid": "contact-456",
    "jobUuid": "abc-123-def-456",
    "jobContactUuid": "jc-789",
    "systemNoteUuid": "note-111",
    "customNoteUuid": "",
    "attachmentUuids": ["att-001", "att-002"]
  }
}

Update Job Output

{
  "success": true,
  "error": "",
  "jobUuid": "abc-123-def-456",
  "jobNumber": "J00789",
  "fieldsUpdated": ["status", "job_description"],
  "badgesAssigned": ["Priority"],
  "badgesMissing": [],
  "attachmentsUploaded": ["document.pdf"],
  "attachmentsFailed": [],
  "noteAdded": true,
  "createdRecords": {
    "noteUuid": "note-333",
    "attachmentUuids": ["att-003"]
  }
}

Error Output (Continue On Fail)

When “Continue On Fail” is enabled and an error occurs:

{
  "success": false,
  "error": "Job with number J99999 not found",
  "jobUuid": "",
  "jobNumber": "",
  "fieldsUpdated": [],
  "badgesAssigned": [],
  "badgesMissing": [],
  "attachmentsUploaded": [],
  "attachmentsFailed": [],
  "noteAdded": false,
  "createdRecords": {
    "noteUuid": "",
    "attachmentUuids": []
  }
}

—

Error Handling

Hard Failures (Node Stops)

| Error | Cause |
|——-|——-|
| First Name is required (or provide a Business Name) | No first name or business name provided |
| At least one contact method is required | No email, phone, or mobile provided |
| No job selected | Update operation with no job selected |
| Job with UUID/number not found | Job was deleted or doesn’t exist |
| ServiceM8 API error on {endpoint} | API authentication, network, or server error |

Soft Failures (Reported in Output)

These don’t stop execution but are reported in the output:

—

Decision Matrix

Business Client Matching

Individual Client Matching

—

Australian Phone Number Support

The node automatically normalizes Australian phone numbers:

| Input | Normalized |
|——-|————|
| 0412345678 | 0412 345 678 |
| +61412345678 | 0412 345 678 |
| 0298765432 | 02 9876 5432 |
| 98765432 | 02 9876 5432 (if looks like landline) |

—

Name Format Configuration

ServiceM8 can store individual client names in two formats:

Important: The name format setting must match your ServiceM8 configuration for deduplication to work correctly. Check your ServiceM8 settings under Settings > Account Settings > Name Format.

—

ServiceM8 API Endpoints Used

| Endpoint | Method | Purpose |
|———-|——–|———|
| /api_1.0/companycontact.json | GET, POST | Contact lookup/create |
| /api_1.0/company.json | GET, POST | Client lookup/create |
| /api_1.0/job.json | GET, POST | Job create/update |
| /api_1.0/jobcontact.json | GET, POST, DELETE | Job contact management |
| /api_1.0/category.json | GET | Category lookup |
| /api_1.0/badge.json | GET | Badge lookup |
| /api_1.0/jobbadge.json | POST | Apply badge to job |
| /api_1.0/queue.json | GET | Queue lookup |
| /api_1.0/jobqueue.json | POST | Assign job to queue |
| /api_1.0/jobnote.json | POST | Create job note |
| /api_1.0/note.json | POST | Create note |
| /api_1.0/Attachment.json | POST | Create attachment metadata |
| /api_1.0/Attachment/{uuid}.file | POST | Upload attachment binary |
| /platformservicesms | POST | Send SMS notification |
| /platformserviceemail | POST | Send email notification |

—

Development

Build

npm run build

Local Testing

npm run build
npm link
Then in your n8n custom nodes directory:
npm link n8n-nodes-servicem8-jobcreation

Project Structure

n8n-nodes-servicem8-jobcreation/
├── credentials/
│   └── ServiceM8Api.credentials.ts
├── nodes/
│   └── ServiceM8JobCreation/
│       ├── ServiceM8JobCreation.node.ts
│       ├── servicem8.svg
│       ├── execute.ts
│       ├── types/
│       │   ├── api.ts
│       │   ├── input.ts
│       │   ├── result.ts
│       │   └── index.ts
│       ├── helpers/
│       │   ├── api.ts
│       │   ├── phoneUtils.ts
│       │   ├── addressUtils.ts
│       │   └── clientMatcher.ts
│       ├── methods/
│       │   ├── loadOptions.ts
│       │   └── index.ts
│       ├── properties/
│       │   ├── operation.ts
│       │   ├── create/
│       │   │   ├── contact.ts
│       │   │   ├── business.ts
│       │   │   ├── address.ts
│       │   │   ├── job.ts
│       │   │   ├── options/
│       │   │   │   ├── category.ts
│       │   │   │   ├── badges.ts
│       │   │   │   ├── queue.ts
│       │   │   │   ├── notifications.ts
│       │   │   │   ├── attachments.ts
│       │   │   │   ├── notes.ts
│       │   │   │   └── additionalOptions.ts
│       │   │   └── index.ts
│       │   └── update/
│       │       ├── jobSelection.ts
│       │       ├── fields.ts
│       │       ├── options.ts
│       │       └── index.ts
│       └── operations/
│           ├── create/
│           │   ├── orchestrator.ts
│           │   ├── inputProcessor.ts
│           │   ├── contactLookup.ts
│           │   ├── clientLookup.ts
│           │   ├── clientCreate.ts
│           │   ├── jobCreate.ts
│           │   ├── categoryAssign.ts
│           │   ├── queueAssign.ts
│           │   ├── notifications.ts
│           │   └── index.ts
│           ├── update/
│           │   ├── jobUpdate.ts
│           │   └── index.ts
│           └── shared/
│               ├── attachmentsUpload.ts
│               ├── badgesAssign.ts
│               ├── notesCreate.ts
│               └── index.ts
├── package.json
├── tsconfig.json
└── README.md

—

License

MIT

—

Author

Trade Magnet – www.trademagnet.com.au

—

Support

For issues and feature requests, please open an issue on GitHub.