Tasks

Create a new Task

Changed on

OAuth Scope

This endpoint requires the following OAuth scope manage_tasks.

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/task.json

Request

  • Base URL
    https://api.servicem8.com/api_1.0
  • URL
    https://api.servicem8.com/api_1.0/task.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: manage_tasks

Request body

due_datestring

The date by which the task should be completed. Format is YYYY-MM-DD. For mobile app compatibility, may be returned with time component (HHMMSS) in some contexts.

task_detailsstring

Detailed description of the task. Contains more comprehensive information about what needs to be done, how to complete the task, or any other relevant notes.

namestring required

The name or title of the task. This field is mandatory and used to identify the task in listings and the user interface.

related_objectstring

The name of the object class this task is related to. Must be a valid object class name in the system (e.g., 'job', 'client', etc.). The value is always stored as lowercase regardless of input case.

related_object_uuidstring uuid

UUID of the specific object instance this task is related to. Must be a valid UUID corresponding to an existing object of the type specified in related_object.

task_completestring

Boolean flag indicating whether the task has been completed (1) or is still pending (0). When set to 1, the completed_timestamp and completed_by_staff_uuid fields are automatically populated.

completed_timestampstring

The date and time when the task was marked as complete. Format is YYYY-MM-DD HH:MM:SS. Automatically set when task_complete is changed to 1.

completed_by_staff_uuidstring uuid

UUID of the staff member who marked the task as complete. Automatically set to the current staff member's UUID when task_complete is changed to 1.

assigned_to_staff_uuidstring uuid

UUID of the staff member assigned to complete this task. Must be a valid staff UUID in the system.

lngunknown
latunknown
uuidstring uuid

Unique identifier for this record

created_by_staff_uuidstring uuid
create_datestring

Timestamp at which record was last modified

Example request

{
  "due_date": "YYYY-MM-DD",
  "related_object_uuid": "123e4567-3b3a-4674-84a1-23f94ede2f5b",
  "completed_timestamp": "2026-03-01 12:00:00",
  "completed_by_staff_uuid": "123e4567-336e-4418-87d5-23f94cf2cf7b",
  "assigned_to_staff_uuid": "123e4567-e2ed-47fc-87b3-23f94dda813b",
  "uuid": "123e4567-d970-4552-8da0-23f948fc411b",
  "created_by_staff_uuid": "123e4567-8efe-42ae-85e6-23f94b87ec5b",
  "create_date": "2026-03-01 12:00:00"
}

Response

Success

errorCodenumber
messagestring

Example response

{
  "message": "OK"
}

Changes

  • 638a8df09bf4Revision changes
    • 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