TrackingTime API

Tasks, Comments and Subtasks

This section describes how to retrieve and edit tasks, task comments and subtasks.

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

JSON Object

{"response":{"status":200,"message":"Request completed successfully."},"data":{
  "name": "Recent Task",
  "project_id": null,
  "project": "TrackingTime v2",
  "project_accumulated_time": 9709198,
  "project_loc_worked_hours": "2696:59",
  "priority": 0,
  "estimated_time": 0.0,
  "loc_estimated_time": "00:00",
  "accumulated_time": 19420,
  "is_archived": false,
  "start_date": "2015-11-14 22:12:51",
  "loc_start_date": "14.11.2015 22:12:51",
  "end_date": null,
  "loc_end_date": null,
  "due_date": null,
  "loc_due_date": null,
  "skill": null,
  "user": {
    "name": "Diego",
    "surname": "Wyllie",
    "avatar_url": "http://static.trackingtime.mobi/189.jpg",
    "id": 1
  },
  "list_position": 0,
  "list_id": null,
  "subtasks": [],
  "comments": [],
  "worked_hours": 5.39,
  "loc_worked_hours": "05:23",
  "accumulated_time_display": "05:23:40",
  "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
  },
  "now_tracking": false,
  "tracking_event": null,
  "account_id": 2,
  "id": 21522,
  "created_at": "2015-11-14 22:12:51",
  "updated_at": "2015-11-20 14:30:43"
}}
                

Available Endpoints

List Tasks

List all account tasks.

Action URL

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

Action URL

/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

Add a new task.

Action URL

/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

Update Task

Update an existing task.

Action URL

/tasks/update/:id

Parameters

Type Parameter Description Required
String skill_name Instead of providing a skill ID you can create a new skill on the fly by passing a name in this parameter. 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.

Action URL

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

Action URL

/tasks/open/:id

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

Action URL

https://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.

Action URL

/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}

Task Comments

Add Task Comment

Add a new task comment.

Action URL

/tasks/:id/comments/add

Parameters

Type Parameter Description Required
String text The content of the comment is limited to 500 chars YES
Date created_at The date of the comment as yyyy-MM-dd HH:mm:SS YES
Integer user_id The user that sends the comment YES
JSON notify_users Include a json array of user IDs to notify them about this new comment, e.g.:
[{"id":1},{"id":2}]
YES

Response

{"response":{"status":200,"message":"Anfrage erfolgreich bearbeitet"},"data":[
  {
    "text": "Some nice comment...",
    "loc_created_at": "30.01.2014 01:14:30",
    "user": {
      "name": "Diego",
      "surname": "Wyllie",
      "avatar_url": "http://static.trackingtime.mobi/142.png",
      "id": 1
    },
    "id": 228,
    "created_at": "2014-01-30 01:14:30",
    "updated_at": null
  }
]}
                        

List Task Comments

Retrieve the comments for the given task.

Action URL

/tasks/:id/comments

Delete Task Comment

Delete an existing task comment.

Action URL

/tasks/:id/comments/delete/:id

Subtasks

Add Subtask

Add a new subtask.

Action URL

/tasks/:id/subtasks/add

Parameters

Type Parameter Description Required
String name Cannot be blank. Max. 5,000 chars YES
Boolean is_done Default: false NO
Integer index The position in the list NO

Response

{"response":{"status":200,"message":"Request completed successfully."},"data":[
  {
    "index": 0,
    "name": "second",
    "is_done": false,
    "id": 6,
    "created_at": null,
    "updated_at": null
  }
]}
                        

List Subtasks

Retrieve all subtasks for the given task.

Action URL

/tasks/:id/subtasks

Update Subtask

Updates an existing subtask with the given id.

Action URL

/tasks/:id/subtasks/update/:id

Parameters

Type Parameter Description Required
String name YES
Boolean is_done YES
Integer index The position in the list YES

Delete Subtask

Deletes an existing to-do with the given id.

Action URL

/tasks/:id/subtasks/delete/:id

Sort Subtasks

Sort subtasks by list position.

Action URL

/tasks/:id/subtasks/sort

Parameters

Type Parameter Description Required
JSON data A json array containing tuples of the form (id,list_position) to be updated, e.g.:
[{"id":13391,"list_position":8},{"id":13384,"list_position":9}]
YES

Open / Close Subtask

Open / close an existing subtask with the given id.

Action URL

/tasks/:task_id/subtasks/open/:id

/tasks/:task_id/subtasks/close/:id