Jobs

Create a new Job

Changed on

OAuth Scope

This endpoint requires the following OAuth scope create_jobs.

Record UUID

UUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the x-record-uuid response header.

post/job.json

Request

  • Base URL
    https://api.servicem8.com/api_1.0
  • URL
    https://api.servicem8.com/api_1.0/job.json
  • Auth
    • API key in header X-Api-Key
    • or OAuth 2
      Authorization code: https://api.servicem8.com/oauth/authorize
      Token URL: https://api.servicem8.com/oauth/access_token scopes: create_jobs

Request body

created_by_staff_uuidstring uuid

UUID of the staff member who created this job. Records which staff member initially added the job to the system.

datestring

The date the job was created or scheduled. Used for organizing jobs chronologically and for reference in reports.

company_uuidstring 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_addressstring

The address where invoices and billing information should be sent. If not specified, defaults to the job address.

status'Quote' | 'Work Order' | 'Unsuccessful' | 'Completed' required

Current status of the job. Controls where the Job appears in the Dispatch Board.. Valid values are [Quote,Work Order,Unsuccessful,Completed]

lngunknown
latunknown
payment_datestring

Not used. Refer to JobPayment endpoint.

payment_actioned_by_uuidstring uuid

Not used. Refer to JobPayment endpoint.

payment_methodstring

Not used. Refer to JobPayment endpoint.

payment_amountstring

Not used. Refer to JobPayment endpoint.

category_uuidstring uuid

UUID reference to the job category this job belongs to. Categories help organize jobs by type of work or department.

payment_notestring

Not used. Refer to JobPayment endpoint.

geo_is_validunknown
purchase_order_numberstring

Client purchase order reference number for this job. Used for cross-referencing with external accounting or order management systems.

invoice_sent0 | 1

Indicates whether an invoice has been sent for this job.. Valid values are [0,1]

invoice_sent_stampunknown
ready_to_invoiceunknown
ready_to_invoice_stampunknown
geo_countryunknown
geo_postcodeunknown
geo_stateunknown
geo_cityunknown
geo_streetunknown
geo_numberunknown
queue_uuidstring uuid

The UUID of the queue this job belongs to.

queue_expiry_datestring

The date and time when the job expires from the queue.

queue_assigned_staff_uuidstring uuid

The UUID of the staff member assigned to this job in the queue.

badgesstring

JSON Array of Badge UUIDs

quote_datestring

The date and time that the job status was changed to Quote.

quote_sent0 | 1

Boolean flag indicating whether a quote has been sent to the client for this job.. Valid values are [0,1]

quote_sent_stampunknown
work_order_datestring

The date and time that the job status was changed to Work Order.

active_network_request_uuidunknown
related_knowledge_articlesunknown
uuidstring uuid

Unique identifier for this record

job_addressstring

Physical address where the job is to be performed. This address is used for geocoding to place the job on the map.

job_descriptionstring
work_done_descriptionstring

Email Address

payment_processed0 | 1

Indicates whether the job has been exported to the connected Accounting Package.. Valid values are [0,1]

payment_received0 | 1

Indicates whether full payment has been received for this job.. Valid values are [0,1]

completion_datestring

The date and time that the job status was changed to Completed.

unsuccessful_datestring

The date and time that the job status was changed to Unsuccessful.

Example request

{
  "created_by_staff_uuid": "123e4567-f7ec-44f1-8f82-23f94fdc6cab",
  "date": "YYYY-MM-DD",
  "company_uuid": "123e4567-9fc3-4f4c-ae8c-23f94a2a432b",
  "payment_date": "2026-03-01 12:00:00",
  "payment_actioned_by_uuid": "123e4567-e130-4744-bf68-23f94937a7eb",
  "category_uuid": "123e4567-5651-43fe-a6f2-23f94a6f9c7b",
  "queue_uuid": "123e4567-e5cb-43ec-8a27-23f948619a1b",
  "queue_expiry_date": "2026-03-01 12:00:00",
  "queue_assigned_staff_uuid": "123e4567-3588-4466-8265-23f9431c9d3b",
  "quote_date": "2026-03-01 12:00:00",
  "work_order_date": "2026-03-01 12:00:00",
  "uuid": "123e4567-8032-4212-ae45-23f94e9e212b",
  "completion_date": "2026-03-01 12:00:00",
  "unsuccessful_date": "2026-03-01 12:00:00"
}

Response

Success

errorCodenumber
messagestring

Example response

{
  "message": "OK"
}

Changes

  • 638a8df09bf4Revision changes
    • breaking

      removed the enum value 0.00 of the request property

    • breaking

      removed the enum value 1.00 of the request property

    • breaking

      the request property type changed from string to no type

    • breaking

      the request property type changed from string to no type

    • breaking

      the request property type changed from integer to no type

    • breaking

      the request property type changed from string to no type

    • breaking

      the request property type changed from string to no type

    • breaking

      the request property type changed from string to no type

    • breaking

      the request property type changed from string to no type

    • breaking

      the request property type changed from string to no type

    • breaking

      the request property type changed from number to no type, and format from float to no format

    • breaking

      the request property type changed from number to no type, and format from float to no format

    • breaking

      the request property type changed from string to no type

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

  • ca9b053c4373Revision changes
    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status