ServiceM8 icon

ServiceM8

ServiceM8 Node
Join our community

Actions14

Overview

This node integrates with the ServiceM8 platform to manage jobs within a business workflow. Specifically, the Job - Create operation allows users to create new job records in ServiceM8 by specifying detailed job information such as client association, scheduling dates, status, location, billing details, and other metadata.

Typical use cases include automating job creation from external systems or workflows, syncing job data between platforms, or programmatically adding jobs based on triggers or events. For example, when a new customer request is received via a form, this node can automatically create a corresponding job in ServiceM8 with all relevant details filled in.

Properties

Name Meaning
created_by_staff_uuid UUID of the staff member who created this job. Records which staff member initially added the job to the system.
date The date the job was created or scheduled. Used for organizing jobs chronologically and for reference in reports.
company_uuid UUID reference to the client/company record associated with this job. Links the job to a client in the system, establishing the client-job relationship for billing and contact purposes.
billing_address The address where invoices and billing information should be sent. If not specified, defaults to the job address.
status Current status of the job. Controls where the Job appears in the Dispatch Board. Valid values are: Quote, Work Order, Unsuccessful, Completed.
lng The longitude coordinate of the job location.
lat The latitude coordinate of the job location.
category_uuid UUID reference to the job category this job belongs to. Categories help organize jobs by type of work or department.
geo_is_valid Indicates whether the geocoding for the job address is valid. If false, the lat, lng, and other geo_ fields should not be used. Valid values: 0 (false), 1 (true).
purchase_order_number Client purchase order reference number for this job. Used for cross-referencing with external accounting or order management systems.
invoice_sent Indicates whether an invoice has been sent for this job. Valid values: 0 (no), 1 (yes).
invoice_sent_stamp The date and time when the invoice was sent.
geo_country The country field of the job address.
geo_postcode The postcode/ZIP code field of the job address.
geo_state The state/province field of the job address.
geo_city The city/suburb field of the job address.
geo_street The street name field of the job address.
geo_number The street number field of the job address.
queue_uuid The UUID of the queue this job belongs to.
queue_expiry_date The date and time when the job expires from the queue.
queue_assigned_staff_uuid The UUID of the staff member assigned to this job in the queue.
badges JSON Array of Badge UUIDs associated with the job.
quote_date The date and time that the job status was changed to Quote.
work_order_date The date and time that the job status was changed to Work Order.
uuid Unique identifier for this job record.
active Record active/deleted flag. Valid values: 0 (deleted/inactive), 1 (active).
edit_date Timestamp at which record was last modified.
job_address Physical address where the job is to be performed. This address is used for geocoding to place the job on the map.
job_description Description of the job.
work_done_description Description of the work done (used in emails).
total_invoice_amount The total amount to be invoiced for this job.
payment_processed Indicates whether the job has been exported to the connected Accounting Package. Valid values: 0 (no), 1 (yes).
payment_processed_stamp The date and time the job has been exported to the connected Accounting Package.
payment_received Indicates whether full payment has been received for this job. Valid values: 0 (no), 1 (yes).
payment_received_stamp The date and time when full payment was received.
completion_date The date and time that the job status was changed to Completed.
completion_actioned_by_uuid UUID of the staff member who marked this job as completed. References a staff record in the system.
unsuccessful_date The date and time that the job status was changed to Unsuccessful.
job_is_scheduled_until_stamp The end date/time of the last scheduled activity for this job. After this date, the job is considered Unscheduled.

Output

The node outputs an array of JSON objects representing the created job(s) as returned by the ServiceM8 API. Each object contains the properties of the newly created job record, including identifiers, timestamps, status, location data, billing info, and other metadata as specified in the input.

No binary data output is produced by this operation.

Dependencies

  • Requires an API key credential for authenticating with the ServiceM8 API.
  • The node uses the ServiceM8 REST API endpoints to perform job creation.
  • Proper configuration of the API credentials in n8n is necessary.
  • Network access to the ServiceM8 API endpoint must be available.

Troubleshooting

  • Missing Required Fields: If required fields for creating a job are omitted, the API may reject the request. Ensure mandatory fields like company_uuid and date are provided if applicable.
  • Invalid UUIDs: Providing malformed or non-existent UUIDs (e.g., for staff, company, category) will cause errors. Verify UUID correctness.
  • Status Field Validation: The status property only accepts specific values (Quote, Work Order, Unsuccessful, Completed). Using invalid values will result in errors.
  • Geocoding Issues: If geo_is_valid is set incorrectly, location-based features may malfunction.
  • API Authentication Errors: Ensure the API key credential is valid and has sufficient permissions.
  • Network Errors: Connectivity issues to the ServiceM8 API endpoint will cause failures.
  • Error Handling: The node supports "Continue On Fail" mode to allow processing multiple items even if some fail.

Links and References

Discussion