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

| Field | Description | |-------|-------------| | First Name | Required for individuals. Can be omitted if Business Name is provided. | | Email, Phone, or Mobile | At least one contact method is required for deduplication. |

Contact Information

| Field | Description | |-------|-------------| | First Name | Contact's first name | | Last Name | Contact's last name (optional) | | Email | Primary lookup identifier for deduplication | | Phone | Landline number (Australian format supported) | | Mobile | Mobile number (Australian format supported) |

Business Information

| Field | Description | |-------|-------------| | Business Name | If provided, client is created as a business; otherwise as individual |

Address Fields

Client Address (fixedCollection): | Field | Description | |-------|-------------| | Street | Street address including unit/suite | | City | City or suburb | | State/Province | State, province, or region | | Postcode | Postal or ZIP code | | Country | Country name |

Job Address: | Field | Description | |-------|-------------| | Job Address Same as Client | Toggle to use client address for job site | | Job Address | Separate address fields (only shown when toggle is off) |

Job Information

| Field | Description | |-------|-------------| | Job Details | Multiline job description/notes | | Job Status | Quote, Work Order, In Progress, or Completed |

Optional Features

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

Category Assignment: | Field | Description | |-------|-------------| | Enable Category | Toggle to enable | | Use Dynamic Category | Toggle between dropdown or expression input | | Category | Dropdown selection (loads from ServiceM8) | | Category Name | Text/expression input for dynamic mode |

Badges Assignment: | Field | Description | |-------|-------------| | Enable Badges | Toggle to enable | | Use Dynamic Badges | Toggle between multi-select or expression input | | Badges | Multi-select dropdown (loads from ServiceM8) | | Badge Names | Comma-separated names for dynamic mode |

Queue Assignment: | Field | Description | |-------|-------------| | Enable Queue | Toggle to enable | | Use Dynamic Queue | Toggle between dropdown or expression input | | Queue | Dropdown selection (loads from ServiceM8) | | Queue Name | Text/expression input for dynamic mode |

Notifications: | Field | Description | |-------|-------------| | Enable Notifications | Toggle to enable | | Notification Recipients | Collection of recipients (see below) |

Each notification recipient has the following options:

| Field | Description | |-------|-------------| | Notification Type | Email or SMS | | Email Address | Recipient email (for Email type) | | Phone Number | Recipient phone (for SMS type) | | Recipient Name | Name used in greeting | | Email Format | HTML or Plain Text (for Email type) | | Custom Subject | Toggle to use custom email subject | | Subject | Custom subject line (supports placeholders) | | Custom Message | Toggle to use custom message content | | Message (HTML) | Custom HTML email body (when format is HTML) | | Message (Text) | Custom plain text email body (when format is Text) | | SMS Message | Custom SMS message (max 160 chars recommended) | | Include Attachments | Toggle to attach files to email | | Attachment Source | All Binary Data or Specific Property | | Binary Property | Property name when using specific property |

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

Attachments: | Field | Description | |-------|-------------| | Enable Attachments | Toggle to enable | | Attachment Mode | "All Binary Data" (auto-upload from previous node) or "URL List" | | URL List | Comma-separated URLs to download and attach |

Notes: | Field | Description | |-------|-------------| | Enable Custom Note | Toggle to add a custom note | | Custom Note Content | Note text to add to the job |

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

Additional Options

| Field | Description | |-------|-------------| | Individual Name Format | "First Last" or "Last, First" - must match your ServiceM8 settings | | Return Headers | Include all created record UUIDs in output |

Update Job

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

Job Selection

| Field | Description | |-------|-------------| | Job Selection Mode | "Select from Dropdown" or "Enter Job Number" | | Job | Dropdown selection of recent jobs | | Job Number | Manual entry (e.g., "J00123") |

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

| Field | Description | |-------|-------------| | Return Headers | Include created record UUIDs (note, attachments) in output |

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": "created_client_and_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:

| Field | Meaning | |-------|---------| | categoryMissing | Category name not found in ServiceM8 | | badgesMissing | One or more badge names not found | | queueMissing | Queue name not found in ServiceM8 | | attachmentsFailed | Files that failed to upload |

Decision Matrix

Business Client Matching

| Name Match | Address Match | Action | |------------|---------------|--------| | Exact | Any | Use existing client | | Partial | Exact/Near | Use existing client | | Partial | None | Create new client | | None | Any | Create new client |

Individual Client Matching

| Name Match | Address Match | Action | |------------|---------------|--------| | Exact | Exact | Use existing client | | Exact | Different | Create new (different person, same name) | | Partial | Exact/Near | Use existing client | | None | Any | Create new client |

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:

| Format | Example | When to Use | |--------|---------|-------------| | First Last | John Smith | If your ServiceM8 is configured for standard format | | Last, First | Smith, John | If your ServiceM8 uses inverted format (default) |

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 | | /platform_service_sms | POST | Send SMS notification | | /platform_service_email | 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.