Time Tracking API Calls


Retrieve All Time Entries across all projects

GET /time_entries.json

In ascending order by date, this retrieves time entries for all projects.

A page can contain up to 500 entries, but to select a different page of data, set the page query parameter to a value greater than zero.

The total number of time entries in the project is in the X-Records HTTP header. X-Pages will be set to the total number of pages, and X-Page will be set to the current page.

Optional Parameters

  • page : numeric - The page to start retrieving entries from ( e.g: page=1 gives records 1 - 500, page=2 gives records 501-1001 etc)
  • fromdate : string (YYYYMMDD) - The start date to retrieve from
  • fromtime : string (HH:MM) - The start time only if fromdate is passed
  • todate: string (YYYYMMDD) - The end date to retrieve to
  • totime : string (HH:MM) - The end time only if todate is passed
  • sortby : string - One of the following: date, user, task, tasklist, project, company, dateupdated (Default: date)
  • sortorder: string (ASC or DESC) - The order to sort the returned data
  • userId: numeric - Return time logs for a specific user only
  • billableType : string (billable or nonbillable) - Filter the Time Entries to those that are Billable or Not Billable.
  • invoicedType: string (invoiced or noninvoiced) - filter the time entries to those that have been Invoiced or not.
  • projectType : string (all, active, archived) - Filter the time entries to those in Active projects, Archived projects or All projects.
  • showDeleted: string (true or false) - Filter time entries to include deleted time sheet entries or not
  • tagIds: numeric - Include one or more Tag IDs here to return only the time entries with those tags attached (eg &tagIds=23,445,454)

Note

  • The date field returned in the response is in UTC date/time
  • The toDate, toTime, fromDate and fromTime are specified in your timezone.

Response

{
    "time-entries": [
        {
            "project-id": "999",
            "minutes": "15",
            "isbillable": "1",
            "person-first-name": "'Demo",
            "todo-list-name": "",
            "description": "",
            "todo-item-name": "",
            "todo-list-id": "",
            "tags": [
              {
                "name": "tag1",
                "id": "15990",
                "color": "#2f8de4"
              },
              {
                "name": "tag2",
                "id": "15991",
                "color": "#2f8de4"
            },
            "company-id": "999",
            "person-id": "999",
            "project-status": "active",
            "project-name": "Test Project",
            "company-name": "Demo 1 Company",
            "id": "999",
            "date": "2013-10-09T18:05:00Z",
            "todo-item-id": "",
            "invoiceNo": "",
            "person-last-name": "User'",
            "has-start-time": "0",
            "hours": "0"
        }
    ],
    "STATUS": "OK"
}

See Time in Data Reference


Retrieve All Time Entries for a Project

GET /projects/{project_id}/time_entries.json

In ascending order by date, this retrieves entries for the submitted project.

A page can contain up to 500 entries, but to select a different page of data, set the page query parameter to a value greater than zero.

The total number of time entries in the project is in the X-Records HTTP header. X-Pages will be set to the total number of pages, and X-Page will be set to the current page.

Optional Parameters

  • page : numeric - The page to start retrieving entries from ( e.g: page=1 gives records 1 - 500, page=2 gives records 101-201 etc)
  • fromdate : string (YYYYMMDD) - The start date to retrieve from
  • fromtime : string (HH:MM) - The start time only if fromdate is passed
  • todate: string (YYYYMMDD) - The end date to retrieve to
  • totime : string (HH:MM) - The end time only if todate is passed
  • sortby : string - One of the following: date, user, task, tasklist, project, company, dateupdated (Default: date)
  • sortorder: string (ASC or DESC) - The order to sort the returned data
  • userId: numeric - Return time logs for a specific user only
  • billableType : string (billable or nonbillable) - Filter the Time Entries to those that are Billable or Not Billable.
  • invoicedType: string (invoiced or noninvoiced) - filter the time entries to those that have been Invoiced or not.
  • showDeleted: string (true or false) - Filter time entries to include deleted time sheet entries or not
  • tagIds: numeric - Include one or more Tag IDs here to return only the time entries with those tags attached (eg &tagIds=23,445,454)

Note

  • The date field returned in the response is in UTC date/time
  • The toDate, toTime, fromDate and fromTime are specified in your timezone.

Response

{
    "time-entries": [
        {
            "project-id": "999",
            "minutes": "15",
            "isbillable": "1",
            "person-first-name": "Demo",
            "todo-list-name": "",
            "description": "",
            "todo-item-name": "",
            "todo-list-id": "",
            "tags": [
              {
                "name": "tag1",
                "id": "15990",
                "color": "#2f8de4"
              },
              {
                "name": "tag2",
                "id": "15991",
                "color": "#2f8de4"
            },
            "company-id": "999",
            "person-id": "999",
            "project-status": "active",
            "project-name": "demo",
            "company-name": "Demo 1 Company",
            "id": "999",
            "date": "2014-04-01T09:00:00Z",
            "todo-item-id": "",
            "invoiceNo": "",
            "person-last-name": "User",
            "has-start-time": "1",
            "hours": "2"
        }
    ],
    "STATUS": "OK"
}

See Time in Data Reference


Retrieve all To-do Item Times

GET /todo_items/{todo_item_id}/time_entries.json

Retrieves all of the time entries from a submitted todo item.

Response

{
    "time-entries": [
        {
            "project-id": "999",
            "minutes": "15",
            "isbillable": "0",
            "person-first-name": "Demo",
            "todo-list-name": "Inbox",
            "description": "",
            "todo-item-name": "Test Task",
            "todo-list-id": "999",
            "tags": [
              {
                "name": "tag1",
                "id": "15990",
                "color": "#2f8de4"
              },
              {
                "name": "tag2",
                "id": "15991",
                "color": "#2f8de4"
            },
            "company-id": "999",
            "person-id": "999",
            "project-name": "demo",
            "company-name": "Demo 1 Company",
            "id": "999",
            "date": "2014-04-01T16:15:00Z",
            "todo-item-id": "999",
            "invoiceNo": "",
            "person-last-name": "User",
            "has-start-time": "1",
            "hours": "0"
        }
    ],
    "STATUS": "OK"
}

See Time in Data Reference


Create a Time-Entry

POST /projects/{project_id}/time_entries.json

For the submitted project, will let you create a new time entry

Request

{
  "time-entry": {
    "description": "",
    "person-id": "999",
    "date": "20140330",
    "time": "10:10",
    "hours": "1",
    "minutes": "15",
    "isbillable": "1",
    "tags": "tag1,tag2,tag3"
  }
}

See Time in Data Reference

Response

Returns HTTP status code 201 (Created) on success, with the Location header set to the URL of the new time entry. From the new URL, you can extract the interger ID of the entry.


Create a Time-Entry (for a task/todo item)

POST /tasks/{taskid}/time_entries.json

or using the deprecated call POST /todo_items/{todo-item-id}/time_entries.json

For the given task/todo item, creates a new time entry. A taskId is the same as a todo-item-id and are used interchangeably in the docs.

Request

{
  "time-entry": {
    "description": "",
    "person-id": "999",
    "date": "20140330",
    "time": "10:10",
    "hours": "1",
    "minutes": "15",
    "isbillable": "1",
    "tags": "tag1,tag2,tag3"
  }
}

See Time in Data Reference

Response

Returns HTTP status code 201 (Created) on success, with the Location header set to the URL of the new time entry. From the new URL, you can extract the interger ID of the entry.


Retrieve Single Time-Entry

GET /time_entries/{id}.json

Retrieves a single time-entry...

Response

{
    "STATUS": "OK",
    "time-entry": {
        "project-id": "999",
        "minutes": "15",
        "isbillable": "1",
        "person-first-name": "Demo",
        "todo-list-name": "Inbox",
        "description": "",
        "todo-item-name": "Write documentation",
        "todo-list-id": "999",
        "company-id": "999",
        "person-id": "999",
        "project-name": "demo",
        "company-name": "Demo 1 Company",
        "id": "999",
        "date": "2014-03-30T10:10:00Z",
        "todo-item-id": "999",
        "invoiceNo": "",
        "person-last-name": "User",
        "has-start-time": true,
        "hours": "1"
    }
}

See Time in Data Reference


Update an Entry

PUT /time_entries/{id}.json

Updates the given time-entry record with the data given.

Optional Parameters

  • You can also include 'project-id' in the json/xml to move this timelog to another project

Request

{
  "time-entry": {
    "description": "A Short Description for the update",
    "person-id": "28726",
    "date": "20140330",
    "time": "10:10",
    "hours": "2",
    "minutes": "15",
    "isbillable": "0",
    "tags": "tag1,tag2,tag3"
  }
}

See Time in Data Reference
Response

Returns HTTP status code 200 on success.


Delete Time-Entry

DELETE /time_entries/{id}.json

Deletes the referenced Time-Entry

Response

Returns HTTP status code 200 on success.


Time Totals

You can request aggregated time totals at numerous levels

  • Total time across account: GET /time/total.json
  • Total time on a project : GET /projects/{id}/time/total.json
  • Total time on a tasklist : GET /tasklists/{id}/time/total.json
  • Total time on a task : GET /tasks/{id}/time/total.json

Optional Parameters

  • userId (numeric - default:0 (All Users) ) - Only show totals for userId passed
  • fromDate (string - YYYYMMDD format ) - Only show totals from a specific date
  • toDate (string - YYYYMMDD format ) - Only show totals up to a specific date
  • fromTime (string - HH:MM format ) - Only show totals from a specific time in conjunction with fromDate
  • toTime (string - HH:MM format ) - Only show totals up to a specific time in conjunction with toDate
  • projectType : string (all, active, archived) - Filter the time totals to those in Active projects, Archived projects or All projects.

Response

GET /time/total.json

{
  "STATUS": "OK",
  "time-totals": {
    "total-mins-sum": "25",
    "non-billed-mins-sum": "25",
    "non-billable-hours-sum": "0.42",
    "total-hours-sum": "0.42",
    "billed-mins-sum": "0",
    "billed-hours-sum": "0.00",
    "billable-hours-sum": "0.42",
    "non-billable-mins-sum": "25",
    "non-billed-hours-sum": "0.42",
    "billable-mins-sum": "25"
  }
}

GET /projects/{id}/time/total.json

{
  "STATUS": "OK",
  "projects": [
    {
      "company": {
        "name": "Digital Crew",
        "id": "47"
      },
      "time-estimates": {
        "total-hours-estimated": "2.17",
        "active-mins-estimated": "105",
        "total-mins-estimated": "130",
        "active-hours-estimated": "1.75",
        "completed-hours-estimated": "0.42",
        "completed-mins-estimated": "25"
      },
      "name": "Time Logging Project",
      "id": "1049",
      "time-totals": {
        "total-mins-sum": "754",
        "non-billed-mins-sum": "752",
        "non-billable-hours-sum": "3.42",
        "total-hours-sum": "12.57",
        "billed-mins-sum": "2",
        "billed-hours-sum": "0.03",
        "billable-hours-sum": "9.15",
        "non-billable-mins-sum": "205",
        "non-billed-hours-sum": "12.53",
        "billable-mins-sum": "549"
      }
    }
  ]
}

GET /tasklists/{id}/time/total.json

{
  "STATUS": "OK",
  "projects": [
    {
      "company": {
        "name": "Digital Crew",
        "id": "47"
      },
      "name": "Time Logging Project",
      "tasklist": {
        "time-estimates": {
          "total-hours-estimated": "1.75",
          "active-mins-estimated": "105",
          "total-mins-estimated": "105",
          "active-hours-estimated": "1.75",
          "completed-hours-estimated": "0.00",
          "completed-mins-estimated": "0"
        },
        "name": "Time Rollup",
        "id": "1027",
        "time-totals": {
          "total-mins-sum": "140",
          "non-billed-mins-sum": "140",
          "non-billable-hours-sum": "0.67",
          "total-hours-sum": "2.33",
          "billed-mins-sum": "0",
          "billed-hours-sum": "0.00",
          "billable-hours-sum": "1.67",
          "non-billable-mins-sum": "40",
          "non-billed-hours-sum": "2.33",
          "billable-mins-sum": "100"
        }
      },
      "id": "1049"
    }
  ]
}

GET /tasks/{id}/time/total.json

{
  "STATUS": "OK",
  "projects": [
    {
      "company": {
        "name": "Digital Crew",
        "id": "47"
      },
      "name": "Time Logging Project",
      "tasklist": {
        "name": "Time Rollup",
        "task": {
          "time-estimates": {
            "total-hours-estimated": "0.00",
            "active-mins-estimated": "0",
            "total-mins-estimated": "0",
            "active-hours-estimated": "0.00",
            "completed-hours-estimated": "0.00",
            "completed-mins-estimated": "0"
          },
          "name": "Some specific task",
          "id": "7641",
          "time-totals": {
            "total-mins-sum": "25",
            "non-billed-mins-sum": "25",
            "non-billable-hours-sum": "0.42",
            "total-hours-sum": "0.42",
            "billed-mins-sum": "0",
            "billed-hours-sum": "0.00",
            "billable-hours-sum": "0.42",
            "non-billable-mins-sum": "25",
            "non-billed-hours-sum": "0.42",
            "billable-mins-sum": "25"
          }
        },
        "id": "1027"
      },
      "id": "1049"
    }
  ]
}

Returns HTTP status code 200 on success.


Time Totals per Project

You can request time totals - per project

GET /projects/time/total.json

Optional Parameters

  • fromDate (string - YYYYMMDD format ) - Only show totals from a specific date
  • toDate (string - YYYYMMDD format ) - Only show totals up to a specific date
  • fromTime (string - HH:MM format ) - Only show totals from a specific time in conjunction with fromDate
  • toTime (string - HH:MM format ) - Only show totals up to a specific time in conjunction with toDate
  • projectType : string (all, active, archived) - Filter the time totals to those in Active projects, Archived projects or All projects.
  • page (numeric - defaults to 1) - The page number to show
  • pageSize (numeric - defaults to 100) - The number of results per page.

{
  "STATUS": "OK",
  "projects": [
    {
      "company": {
        "name": "Company 1",
        "id": "12345"
      },
      "name": "project name",
      "totalNonBillableMins": "0",
      "totalBillableMins": "30",
      "id": "315410",
      "totalMins": "30"
    },
    {
      "company": {
        "name": "Company 2",
        "id": "23456"
      },
      "name": "another project name",
      "totalNonBillableMins": "5",
      "totalBillableMins": "445",
      "id": "41686",
      "totalMins": "450"
    },
    {
      "company": {
        "name": "Company 3",
        "id": "41299"
      },
      "name": "a third project name",
      "totalNonBillableMins": "0",
      "totalBillableMins": "7291",
      "id": "85072",
      "totalMins": "7291"
    }
  ]
}