Task Management Tasks

Overview

This resource represents Tasks - units of work to be completed, such as cleaning, maintenance, or inspections. Tasks can be created manually or automatically from Templates, and can be assigned to team members.

Parameters

OAuth Scopes:

task_management_read

Name	Type	Read/Write	Description
account	Integer	Read	Account's ID related to Task
assignee	Integer	Read	Assignee's ID (User) responsible for the Task
event_source	Object	Read	Polymorphic reference to the event source (Booking or Rental)
created_by	Object	Read	Polymorphic reference to creator (User or Application)
template	UUID	Read	Template's ID from which Task was created
id	UUID	Read	Task's ID
name	String	Read	Task's name
description	String	Read	Task's description
category	String	Read	Task's category, list of Categories described in enums section
priority	String	Read	Task's priority, list of Priorities described in enums section
status	String	Read	Task's status, list of Statuses described in enums section
due_at	Time	Read	Task's due date and time
expected_duration_in_minutes	Integer	Read	Expected duration to complete the Task in minutes
actual_duration_in_minutes	Integer	Read	Actual duration spent on the Task in minutes
has_issues	Boolean	Read	Whether the Task has issues reported
due_at_automation	Object	Read	Automation rules for due date calculation
created_at	Time	Read	Task's create time
updated_at	Time	Read	Task's update time
canceled_at	Time	Read	Task's cancellation time (null if not canceled)

task_management_write

Name	Type	Read/Write	Description	Constraints
account	Integer	Read	Account's ID related to Task
assignee	Integer	Read	Assignee's ID (User) responsible for the Task
event_source	Object	Read	Polymorphic reference to the event source (Booking or Rental)
created_by	Object	Read	Polymorphic reference to creator (User or Application)
template	UUID	Read	Template's ID from which Task was created
id	UUID	Read	Task's ID
name	String	Read/Write	Task's name	Required on create
description	String	Read/Write	Task's description	Required on create
category	String	Read/Write	Task's category, list of Categories described in enums section	Required on create, must be one of Categories
priority	String	Read/Write	Task's priority, list of Priorities described in enums section	Required on create, must be one of Priorities
status	String	Read/Write	Task's status, list of Statuses described in enums section	Required on create, must be one of Statuses
due_at	Time	Read/Write	Task's due date and time	Required on create
expected_duration_in_minutes	Integer	Read/Write	Expected duration to complete the Task in minutes	Required on create, must be greater than 0
actual_duration_in_minutes	Integer	Write	Actual duration spent on the Task in minutes	Available on handle action
has_issues	Boolean	Read/Write	Whether the Task has issues reported	Required on create
notes	String	Write	Notes about the Task execution	Available on handle action
assignee_id	Integer	Write	Assignee's ID to assign the Task to
event_source_id	Integer/UUID	Write	Event source ID (Booking or Rental ID)
event_source_type	String	Write	Event source type ("Booking" or "Rental")	Required if event_source_id is provided
template_id	UUID	Write	Template's ID to create Task from
checklist	Array	Write	Array of checklist item names to create	Available on create
checked_task_item_ids	Array	Write	Array of Task Item IDs to mark as checked	Available on handle action
task_items	Array	Write	Array of task item objects to update	Available on manage action
append_task_items	Array	Write	Array of task item objects to append	Available on manage action
attachments	Array	Write	Array of attachment objects with file data	Available on create
due_at_automation	Object	Read	Automation rules for due date calculation
created_at	Time	Read	Task's create time
updated_at	Time	Read	Task's update time
canceled_at	Time	Read	Task's cancellation time (null if not canceled)

List Tasks

GET /task_management/tasks

OAuth Scopes:

task_management_read / task_management_write

response.json

{
  "links": {
    "tasks.account": "https://www.bookingsync.com/api/v3/accounts/{tasks.account}",
    "tasks.assignee": "https://www.bookingsync.com/api/v3/users/{tasks.assignee}",
    "tasks.booking": "https://www.bookingsync.com/api/v3/bookings/{tasks.event_source.id}",
    "tasks.rental": "https://www.bookingsync.com/api/v3/rentals/{tasks.event_source.id}",
    "tasks.template": "https://www.bookingsync.com/api/v3/task_management/templates/{tasks.template}",
    "tasks.user": "https://www.bookingsync.com/api/v3/users/{tasks.created_by.id}",
    "tasks.application": "https://www.bookingsync.com/api/v3/applications/{tasks.created_by.id}"
  },
  "tasks": [
    {
      "links": {
        "account": 1,
        "assignee": 10,
        "created_by": {
          "id": 5,
          "type": "User"
        },
        "event_source": {
          "id": 100,
          "type": "Booking"
        },
        "template": null
      },
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Clean apartment after checkout",
      "description": "Full cleaning including bathroom, kitchen, and bedroom",
      "category": "cleaning",
      "priority": "high",
      "status": "todo",
      "due_at": "2024-01-15T14:00:00Z",
      "expected_duration_in_minutes": 120,
      "actual_duration_in_minutes": null,
      "has_issues": false,
      "due_at_automation": {
        "delay_in_minutes": 60,
        "event": "check_out",
        "event_source_type": "Booking"
      },
      "created_at": "2024-01-10T10:00:00Z",
      "updated_at": "2024-01-10T10:00:00Z",
      "canceled_at": null
    }
  ],
  "meta": {}
}

Get a single Task

Returns a single task identified by ID.

GET /task_management/tasks/:task_id

OAuth Scopes:

task_management_read / task_management_write

response.json

{
  "links": {
    "tasks.account": "https://www.bookingsync.com/api/v3/accounts/{tasks.account}",
    "tasks.assignee": "https://www.bookingsync.com/api/v3/users/{tasks.assignee}",
    "tasks.booking": "https://www.bookingsync.com/api/v3/bookings/{tasks.event_source.id}",
    "tasks.rental": "https://www.bookingsync.com/api/v3/rentals/{tasks.event_source.id}",
    "tasks.template": "https://www.bookingsync.com/api/v3/task_management/templates/{tasks.template}",
    "tasks.user": "https://www.bookingsync.com/api/v3/users/{tasks.created_by.id}",
    "tasks.application": "https://www.bookingsync.com/api/v3/applications/{tasks.created_by.id}"
  },
  "tasks": [
    {
      "links": {
        "account": 1,
        "assignee": 10,
        "created_by": {
          "id": 5,
          "type": "User"
        },
        "event_source": {
          "id": 100,
          "type": "Booking"
        },
        "template": null
      },
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Clean apartment after checkout",
      "description": "Full cleaning including bathroom, kitchen, and bedroom",
      "category": "cleaning",
      "priority": "high",
      "status": "todo",
      "due_at": "2024-01-15T14:00:00Z",
      "expected_duration_in_minutes": 120,
      "actual_duration_in_minutes": null,
      "has_issues": false,
      "due_at_automation": {
        "delay_in_minutes": 60,
        "event": "check_out",
        "event_source_type": "Booking"
      },
      "created_at": "2024-01-10T10:00:00Z",
      "updated_at": "2024-01-10T10:00:00Z",
      "canceled_at": null
    }
  ],
  "meta": {}
}

Create a new Task

Creates a Task.

POST /task_management/tasks

OAuth Scopes:

task_management_write

request.json

{
  "tasks": [
    {
      "name": "Clean apartment after checkout",
      "description": "Full cleaning including bathroom, kitchen, and bedroom",
      "category": "cleaning",
      "priority": "high",
      "status": "todo",
      "due_at": "2024-01-15T14:00:00Z",
      "expected_duration_in_minutes": 120,
      "has_issues": false,
      "assignee_id": 10,
      "event_source_id": 100,
      "event_source_type": "Booking",
      "checklist": [
        "Clean bathroom",
        "Clean kitchen",
        "Change bedding"
      ]
    }
  ]
}

response.json

{
  "links": {
    "tasks.account": "https://www.bookingsync.com/api/v3/accounts/{tasks.account}",
    "tasks.assignee": "https://www.bookingsync.com/api/v3/users/{tasks.assignee}",
    "tasks.booking": "https://www.bookingsync.com/api/v3/bookings/{tasks.event_source.id}",
    "tasks.rental": "https://www.bookingsync.com/api/v3/rentals/{tasks.event_source.id}",
    "tasks.template": "https://www.bookingsync.com/api/v3/task_management/templates/{tasks.template}",
    "tasks.user": "https://www.bookingsync.com/api/v3/users/{tasks.created_by.id}",
    "tasks.application": "https://www.bookingsync.com/api/v3/applications/{tasks.created_by.id}"
  },
  "tasks": [
    {
      "links": {
        "account": 1,
        "assignee": 10,
        "created_by": {
          "id": 5,
          "type": "User"
        },
        "event_source": {
          "id": 100,
          "type": "Booking"
        },
        "template": null
      },
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Clean apartment after checkout",
      "description": "Full cleaning including bathroom, kitchen, and bedroom",
      "category": "cleaning",
      "priority": "high",
      "status": "todo",
      "due_at": "2024-01-15T14:00:00Z",
      "expected_duration_in_minutes": 120,
      "actual_duration_in_minutes": null,
      "has_issues": false,
      "due_at_automation": null,
      "created_at": "2024-01-10T10:00:00Z",
      "updated_at": "2024-01-10T10:00:00Z",
      "canceled_at": null
    }
  ],
  "meta": {}
}

Handle a Task

Updates a Task's execution-related fields. This endpoint is used by task assignees to update status, report issues, track time, and check off checklist items.

PATCH /task_management/tasks/:task_id/handle

OAuth Scopes:

task_management_write

request.json

{
  "tasks": [
    {
      "status": "in_progress",
      "has_issues": false,
      "checked_task_item_ids": [
        "b2c3d4e5-f6a7-8901-bcde-f23456789012"
      ]
    }
  ]
}

response.json

{
  "links": {
    "tasks.account": "https://www.bookingsync.com/api/v3/accounts/{tasks.account}",
    "tasks.assignee": "https://www.bookingsync.com/api/v3/users/{tasks.assignee}",
    "tasks.booking": "https://www.bookingsync.com/api/v3/bookings/{tasks.event_source.id}",
    "tasks.rental": "https://www.bookingsync.com/api/v3/rentals/{tasks.event_source.id}",
    "tasks.template": "https://www.bookingsync.com/api/v3/task_management/templates/{tasks.template}",
    "tasks.user": "https://www.bookingsync.com/api/v3/users/{tasks.created_by.id}",
    "tasks.application": "https://www.bookingsync.com/api/v3/applications/{tasks.created_by.id}"
  },
  "tasks": [
    {
      "links": {
        "account": 1,
        "assignee": 10,
        "created_by": {
          "id": 5,
          "type": "User"
        },
        "event_source": {
          "id": 100,
          "type": "Booking"
        },
        "template": null
      },
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Clean apartment after checkout",
      "description": "Full cleaning including bathroom, kitchen, and bedroom",
      "category": "cleaning",
      "priority": "high",
      "status": "todo",
      "due_at": "2024-01-15T14:00:00Z",
      "expected_duration_in_minutes": 120,
      "actual_duration_in_minutes": null,
      "has_issues": false,
      "due_at_automation": null,
      "created_at": "2024-01-10T10:00:00Z",
      "updated_at": "2024-01-10T10:00:00Z",
      "canceled_at": null
    }
  ],
  "meta": {}
}

Allowed parameters for handle

Only :status, :has_issues, :actual_duration_in_minutes, :notes, and :checked_task_item_ids attributes are allowed.

Manage a Task

Updates a Task's management-related fields. This endpoint is used by task managers to update task details, assignee, and checklist items.

PATCH /task_management/tasks/:task_id/manage

OAuth Scopes:

task_management_write

request.json

{
  "tasks": [
    {
      "name": "Updated task name",
      "assignee_id": 15,
      "priority": "medium",
      "task_items": [
        {
          "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
          "name": "Updated item name",
          "position": 1
        }
      ],
      "append_task_items": [
        {
          "name": "New checklist item"
        }
      ]
    }
  ]
}

response.json

{
  "links": {
    "tasks.account": "https://www.bookingsync.com/api/v3/accounts/{tasks.account}",
    "tasks.assignee": "https://www.bookingsync.com/api/v3/users/{tasks.assignee}",
    "tasks.booking": "https://www.bookingsync.com/api/v3/bookings/{tasks.event_source.id}",
    "tasks.rental": "https://www.bookingsync.com/api/v3/rentals/{tasks.event_source.id}",
    "tasks.template": "https://www.bookingsync.com/api/v3/task_management/templates/{tasks.template}",
    "tasks.user": "https://www.bookingsync.com/api/v3/users/{tasks.created_by.id}",
    "tasks.application": "https://www.bookingsync.com/api/v3/applications/{tasks.created_by.id}"
  },
  "tasks": [
    {
      "links": {
        "account": 1,
        "assignee": 10,
        "created_by": {
          "id": 5,
          "type": "User"
        },
        "event_source": {
          "id": 100,
          "type": "Booking"
        },
        "template": null
      },
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Clean apartment after checkout",
      "description": "Full cleaning including bathroom, kitchen, and bedroom",
      "category": "cleaning",
      "priority": "high",
      "status": "todo",
      "due_at": "2024-01-15T14:00:00Z",
      "expected_duration_in_minutes": 120,
      "actual_duration_in_minutes": null,
      "has_issues": false,
      "due_at_automation": null,
      "created_at": "2024-01-10T10:00:00Z",
      "updated_at": "2024-01-10T10:00:00Z",
      "canceled_at": null
    }
  ],
  "meta": {}
}

Allowed parameters for manage

Only :name, :description, :category, :priority, :status, :due_at, :expected_duration_in_minutes, :assignee_id, :task_items, and :append_task_items attributes are allowed.

Delete a Task

Cancels a Task (soft delete).

DELETE /task_management/tasks/:task_id

OAuth Scopes:

task_management_write

Returns an empty body with status 204 No Content.