Toggle Sidebar

Tasks

This section describes how to retrieve and edit tasks. Tasks are central to our data model and will be described in detail.


Task Assignees

Tasks can have one or multiple assignees.


  • If task.user is not null: The task is assigned to a single user (backwards compatible with /tasks/add)
  • If task.user is null and task.users is null: The task isn't assigned to anyone yet.
  • If task.user is null and task.users is not null: The task is assigned to one or multiple users (tasks/share)

Rules and Constraints

  • Every user assigned to the task can close / re-open the task
  • Every user has his own estimated and accumulated times within the task
  • Every user assigned to the task can edit or delete it, provided they have advanced user permissions that allow them to edit projects and tasks
  • The parameter "tracking" indicates whether the task is currently on a timer. Tracking is true if any of the tasks assignees is currently tracking time on this task.

Available Endpoints

Parameters

Type Parameter Description Required
Integer id Read only
String name The task name YES
Date due_date The date when this task should be completed NO
Double estimated_time Estimated hours to complete this task NO
Integer priority The priority of this task, e.g. from 1 to 10 NO
Integer project_id The id of the Project object, that this task belongs to NO
String project The name of the task's project NO
Long project_accumulated_time The project accumulated time in seconds. NO
Long project_loc_worked_hours The project localized total worked hours NO
Integer user_id The id of the user assigned to this task NO
Integer list_id The id of the task list containing this task. NO
Integer list_position The position of this task within its task list NO
Double is_billable Indicates whether this task is billable NO
Double hourly_rate The default hourly rate for this task NO
Double hourly_cost The default hourly cost for this task NO
Double fixed_rate The default fixed rate for this task NO
Boolean is_archived Indicates whether this task is closed or not. Default: false NO
Date start_date The date when this task was created Read only
Date end_date The date when this task was closed Read only
Long accumulated_time The total time worked on this task by the assignee Read only
Double worked_hours The total amount of hours worked on this task Read only
String accumulated_time_display Displays the accumulated time in HH:mm:SS format Read only
Boolean now_tracking Indicates whether the user is tracking this task at the moment or not Read only
JSON tracking_event If now_tracking is true, a JSON representation of the currently active time entry is included in the task object Read only
String color The project's color Read only
JSON json Store user preferences in JSON format No

Sharing Parameters

These parameters represent the relation between a shared task an one of its assignees.


Type Parameter Description Required
JSON[] users A JSON array containing all users who are currently assigned to this task. Yes
String status The current task status of a single assignee. No
Long accumulated_time The total number of seconds a user has spent working on a shared task. Read only
Double estimated_time The number of hours a user is supposed to spend working on a shared task. No
Date shared_on The date when the task has been shared with the user. Read only
JSON event If tracking is true, a JSON representation of the currently active time entry is included in the task object Read only

JSON Object

{
    "name": "Shared Task",
    "project_id": null,
    "project": null,
    "project_accumulated_time": null,
    "project_loc_worked_hours": null,
    "customer": null,
    "customer_id": null,
    "service": null,
    "service_id": null,
    "estimated_time": 0,
    "loc_estimated_time": "00:00",
    "accumulated_time": 0,
    "is_archived": false,
    "start_date": "2017-03-23 13:42:54",
    "loc_start_date": "03/23/2017 01:42:54 PM",
    "end_date": null,
    "loc_end_date": null,
    "due_date": null,
    "loc_due_date": null,
    "list_position": 0,
    "list_id": null,
    "worked_hours": 0,
    "loc_worked_hours": "00:00",
    "accumulated_time_display": "00:00:00",
    "now_tracking": false,
    "account_id": 2,
    "color": null,
    "day_index": 0,
    "index": 0,
    "skill": null,
    "user": null,
    "billing": {
      "is_billable": true,
      "hourly_rate": null,
      "loc_hourly_rate": null,
      "hourly_cost": null,
      "loc_hourly_cost": null,
      "fixed_rate": null,
      "loc_fixed_rate": null,
      "billable_hours": null,
      "non_billable_hours": null,
      "loc_billable_hours": null,
      "loc_non_billable_hours": null
    },
    "project_billing": null,
    "service_item": null,
    "tracking_event": null,
    "subtasks": [],
    "comments": [],
    "users": [
      {
        "name": "Diego M.",
        "surname": "Wyllie",
        "avatar_url": "http://static.trackingtime.mobi/image.jpg",
        "status": "INVITED",
        "shared_on": "2017-03-23 13:42:54",
        "event": null,
        "estimated_time": null,
        "accumulated_time": null
      },
      {
        "name": "John",
        "surname": "Appleseed",
        "avatar_url": "http://www.gravatar.com/avatar/25289e28437d20ea5aea01850ff57ab5.jpg?d=...",
        "status": "INVITED",
        "shared_on": "2017-03-23 13:42:54",
        "event": null,
        "estimated_time": null,
        "accumulated_time": null
      }
    ],
    "id": 2354320,
    "created_at": "2017-03-23 13:42:54",
    "updated_at": null,
    "json": null
  }
}
                                    

Endpoints

List Tasks

List all account tasks.


Endpoint

https://app.trackingtime.co/api/v4/tasks

Parameters

Type Parameter Description Required
String filter [ALL | ACTIVE | ARCHIVED | TRACKING]. Use the TRACKING filter to retrieve all account tasks currently tracking. Default = ACTIVE NO
String include_billing Set to 'true' to include billing data in the server response. Default = false NO

Permissions

  • Admins and project managers can view all account tasks
  • Co-workers can be given permission (can_view_others) to view account tasks

Get Task

Retrieve the task with the given id.


Endpoint

https://app.trackingtime.co/api/v4/tasks/:id

Parameters

Type Parameter Description Required
String include_billing Set to 'true' to include billing data in the server response. Default = true NO

Permissions

  • Admins and project managers can view all account tasks
  • Co-workers can be given permission (can_view_others) to view account tasks

Add Task [DEPRECATED]

Add a new task. Please note that this endpoint is deprecated. Use task/share instead.


Endpoint

https://app.trackingtime.co/api/v4/tasks/add

Parameters

Type Parameter Description Required
String project_name Instead of providing a project ID you can create a new project on the fly by passing a name in this parameter. DEPRECATED! NO
Boolean notify_by_email Set to true if you want the task assignee to be notified via email. NO

Permissions

  • Admins and project managers can add any tasks
  • Co-workers can be given permission (can_edit_projects_and_tasks) to add new tasks

Share Task

Add a new shared task with one or multiple assignees.


Endpoint

https://app.trackingtime.co/api/v4/tasks/share

Parameters

Type Parameter Description Required
Boolean notify_by_email Set to true if you want the task assignee to be notified via email. NO
JSON[] users A JSON array containing user ID's:
[{"id":1},{"id":2},{"id":3}]
NO

Permissions

  • Admins and project managers can add any tasks
  • Co-workers can be given permission (can_edit_projects_and_tasks) to add new tasks

Update Task

Update an existing task.


Endpoint

https://app.trackingtime.co/api/v4/tasks/update/:id

Parameters

Type Parameter Description Required
JSON[] users A JSON array containing user ID's:
[{"id":1},{"id":2},{"id":3}]
NO

Permissions

  • Admins and project managers can update any tasks
  • Co-workers can be given permission (can_edit_projects_and_tasks) to update existing tasks

Delete Task

When you delete a task all associated time entries will also be deleted.


Endpoint

https://app.trackingtime.co/api/v4/tasks/delete/:id

Permissions

  • Admins and project managers can delete any tasks
  • Co-workers can be given permission (can_edit_projects_and_tasks) to delete tasks

Open / Close Task

Open / close an existing task.


Endpoint

https://app.trackingtime.co/api/v4/tasks/open/:id

https://app.trackingtime.co/api/v4/tasks/close/:id

Permissions

  • Admins, project managers can open / close any tasks
  • Co-workers can can be given permission (can_edit_projects_and_tasks) to open / close any tasks they have access to

Search Tasks

Search active user tasks by task name and project name.


Endpoint

https://app.trackingtime.co/api/v4https://app.trackingtime.co/v3/:account_id/tasks/search

Parameters

Type Parameter Description Required
JSON[] data A json array containing project / task name pairs to search for.
[{"project_name":"API-v2","task_name":"Add a new account"},
{"project_name":"Inbox","task_name":"Work smarter"}]
YES

Permissions

  • Available to all users

Sort Tasks

Allows you to sort tasks in a user-specific way using the parameters index and day_index.


Endpoint

https://app.trackingtime.co/api/v4/tasks/sort

Parameters

Type Parameter Description Required
JSON data A json array containing tuples of the form (id,index) of the tasks to be sorted, e.g.:
[{"id":13391,"index":8},{"id":13384,"index":9}]
YES
Boolean by_day Set to true in case you want to sort using the day_index parameter rather then the standard index. Default: false NO

Response

{"response":{"status":200,"message":"ok"},"data":null}