Summary

The API accepts only JSON requests. Please make sure you're setting Content-Type: application/json in your request header. Each request returns a JSON-encoded body. If the time entry is currently running, the duration attribute contains a negative value, denoting the start of the time entry in seconds since epoch (Jan 1 1970). The correct duration can be calculated as current_time + duration, where current_time is the current time in seconds since epoch.

The result of each action is communicated via standard HTTP response codes.

CORS

If you wish to use the API using CORS, we'll need to whitelist you first. Please refer to the CORS documentation

Successful requests

When request is successful (2xx), a nested response object is returned. Fields which value is NULL are not in the response.

Example request:

curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \
  -H "Content-Type: application/json" \
  -d '{"created_with":"API example code","pid":null,"tid":null,"description":"New time entry","tags":[],"billable":false,"duration":-1654686174,"wid":31366,"at":"1984-06-08T11:02:53.836Z","start":"1984-06-08T11:02:53.000Z","stop":null}' \
  -X POST https://api.track.toggl.com/api/v9/time_entries

Response

{
  "data": {
    "description": "New time entry",
    "start": "1984-02-12T15:35:47+02:00",
    "billable": false,
    "wid": 31366,
    "pid": 9012,
    "duration": 1200,
    "stop": "1984-02-12T15:35:57+02:00",
    "tags": [],
    "id": 4269795
  }
}

Failed requests

If a create or update action failed, HTTP status code 404 and an array of localized error messages will be returned.

curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \
  -H 'Content-Type: application/json' \
  -d '{"time_entry":{"description":"New time entry","created_with":"API example code"}}' \
  -X POST https://api.track.toggl.com/api/v9/time_entries

Response

["Start can't be blank"]

Authentication

To use the API, you need to authenticate yourself. This can be done via HTTP POST or HTTP Basic Auth. After successful authentication a session is created using a cookie.

If authentication fails, HTTP status code 403 is returned. You can read more about authentication and see sample requests here.