GithubHelp home page GithubHelp logo

toggl_api_docs's Introduction

Toggl API Documentation

⚠️ Important ⚠️

We have migrated our documentation to https://developers.track.toggl.com/docs/. There, you will find up-to date API docs for the Toggl Track, Reports and Webhooks services.

If you're running into issues or require help with anything, please contact our dedicated 24/5 support staff over on our support pages. You can chat with them using the icon on the right bottom.


Toggl API is divided into three:

For changing data, including tracking time, you'll need to use the Toggl API.

If you want to get time entries of all the workspace users and aggregated data for reporting, you need to use the read-only Reports API, which gives you many options for filtering, grouping and sorting.

For monitoring data changes in a workspace, you'll need the Webhooks API.

The API Format

The API accepts only JSON requests. Please make sure you're setting Content-Type: application/jsonin your request header. Each request returns a JSON-encoded body.

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

Times and dates use the ISO 8601 standard, more specifically a subset described in RFC 3339.

Please do note that the times and dates are stored in UTC (GMT), on return the data is set into the appropriate timezone according to the setting in user profile. 3rd party applications should make sure that they are using correct timezones and also consider daylight saving (where applicable).

For rate limiting we have implemented a Leaky bucket. When a limit has been hit the request will get a HTTP 429 response and it's the task of the client to sleep/wait until bucket is empty. Limits will and can change during time, but a safe window will be 1 request per second. Limiting is applied per api token per IP, meaning two users from the same IP will get their rate allocated separately.

Example requests

The example requests here are done using a command line tool called cURL. If you want to try the requests out yourself, you can download cURL from here. It is available for all possible operating systems.

Under Ubuntu installing cURL is very easy:

sudo apt-get install curl

API token

Each user in Toggl.com has an API token. They can find it under "My Profile" in their Toggl account.

Help us towards a better API

The Toggl API has moved to Github so you could actively participate in helping us making the API better. If you have any requests or you found a bug, you can use Github issues to let us know. You can also fork the docs and send a pull request with improvements

Code examples

Java

Python

Ruby

Node.js

C++

.NET

  • The Toggl mobile apps have shared C# libraries which provide access to the API and also common clientside business logic we use. Feel free to use as little or much of it as you want.

Scala

PHP

Go

Elixir

3rd party apps

Perl

R

Swift

toggl_api_docs's People

Contributors

apocalypticfish avatar bencooper222 avatar charlesfsl avatar clijsters avatar darrillaga avatar dasilvacontin avatar dougefresh avatar fonorobert avatar gilberthdez avatar indrekv avatar jkruczynski avatar kanet77 avatar kirstein avatar kovin avatar majatrepsic avatar matthewdowney avatar matthieuauger avatar melistik avatar michaeldanilov avatar nghiatranuit avatar nicktoggl avatar refiito avatar shedokan avatar supermalf avatar supremebeing7 avatar tanel avatar tdmalone avatar thecatontheflat avatar webervin avatar ynop avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

toggl_api_docs's Issues

Stop a time entry

Hello,
Is there a simple way to stop a time entry without starting a new one.

Currently the only solution I have found was to start a new "fake" time entry and to delete it immediately...

Thanks, Bertrand

Time Entry Changes Push Notification

I don't see anything in the api that would allow receiving push notification whenever a user updates a time entry. I do see, however, that you web app does refresh/updates when a time entry is updated from another computer/device etc... What is your recommendation for keeping records in sync using provided API?

Getting Project Users

According to https://github.com/toggl/toggl_api_docs/blob/master/chapters/project_users.md, project users can be created, updated and deleted. For the latter operations, the project user id is necessary.

Although you can get the projects a user can see (according to https://github.com/toggl/toggl_api_docs/blob/master/chapters/users.md), the project user id is not included in the response and hence, modification of project users is not possible, espescially if the project user has been created through UI.

Please provide a method to retrieve all project users of a project (including the user's role, whether he is manager or not).

Inactive Tasks via API

I can't seem to find any way to retrieve Inactive (Done) tasks via the API. Previously we could retrieve all tasks, each one flagged as active=true or active=false.

But the new API only seems to allow selecting "not done tasks":
https://github.com/toggl/toggl_api_docs/blob/master/chapters/workspaces.md#get-workspace-tasks

A flag to select inactive tasks (like in the previous API, and in the Get Projects request) would be very useful, but this functionality doesn't appear to be implemented:
https://www.toggl.com/api/v8/workspaces/777/tasks?active=false

We have a custom script we've written internally to synchronise our Clients, Projects, Tasks and Time Entries between Toggl, ActiveCollab and WHMCS.

Google sign in question

This is not an issue, rather it is more of a question. Is it possible to use google credentials to sign in to toggl using toggl API. If so, is it possible to get some documentation on how this is accomplished? Thank you in advance.

basic auth with api token doesn't work on the reports api and the documention is wrong and incomplete

I created the header as explained in the reports documentation:
Authentication

You can authenticate in the reports API only with your API token. For HTTP Basic Auth you have to add the Authorization header with the request. The Authorization header is constructed as follows:

String with api token xxxx:api_token (xxx indicating user's personal token)
The resulting string literal is then encoded using Base64
The authorization method and a space i.e. "Basic " is then put before the encoded string.
For example, if the user agent uses 'Aladdin' as the username and 'open sesame' as the password then the header is formed as follows: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

It works fine with api V8 but when I try to get a weekly report I recieve an error: message":"api token missing"

curl -v -H 'Content-Type: application/json' -H 'Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==' -X GET "https://www.toggl.com/reports/api/v2/[email protected]&workspace_id=333148"  
* About to connect() to www.toggl.com port 443 (#0)
*   Trying 50.57.224.86...
* Adding handle: conn: 0x1e866c0
* Adding handle: send: 0
* Adding handle: recv: 0
* Curl_addHandleToPipeline: length: 1
* - Conn 0 (0x1e866c0) send_pipe: 1, recv_pipe: 0
* Connected to www.toggl.com (50.57.224.86) port 443 (#0)
* successfully set certificate verify locations:
*   CAfile: /usr/share/curl/ca-bundle.crt CApath: none
* SSLv3, TLS handshake, Client hello (1):
* SSLv3, TLS handshake, Server hello (2):
* SSLv3, TLS handshake, CERT (11):
* SSLv3, TLS handshake, Server key exchange (12):
* SSLv3, TLS handshake, Server finished (14):
* SSLv3, TLS handshake, Client key exchange (16):
* SSLv3, TLS change cipher, Client hello (1):
* SSLv3, TLS handshake, Finished (20):
* SSLv3, TLS change cipher, Client hello (1):
* SSLv3, TLS handshake, Finished (20):
* SSL connection using DHE-RSA-AES256-GCM-SHA384
* Server certificate:
*    subject: O=*.toggl.com; OU=Domain Control Validated; CN=*.toggl.com
*    start date: 2012-07-19 07:59:09 GMT
*    expire date: 2013-08-18 12:49:05 GMT
*    subjectAltName: www.toggl.com matched
*    issuer: C=US; ST=Arizona; L=Scottsdale; O=GoDaddy.com, Inc.; OU=http://certificates.godaddy.com/repository; CN=Go Daddy Secure Certification Authority; serialNumber=07969287
*    SSL certificate verify ok.
> GET /reports/api/v2/[email protected]&workspace_id=333148 HTTP/1.1
> User-Agent: curl/7.30.0
> Host: www.toggl.com
> Accept: */*
> Content-Type: application/json
> Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==
> 
< HTTP/1.1 401 Unauthorized
* Server nginx/1.2.8 is not blacklisted
< Server: nginx/1.2.8
< Date: Tue, 04 Jun 2013 14:18:14 GMT
< Content-Type: application/json
< Content-Length: 129
< Connection: keep-alive
< 
* Connection #0 to host www.toggl.com left intact
{"error":{"message":"api token missing","tip":"You can find your API Token in your profile at https://www.toggl.com","code":401}}

In the documentation for weekly reports there is an example

curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET "https://toggl.com/reports/api/v2/weekly?workspace_id=123&since=2013-05-19&until=2013-05-20"

Here you seem to use another way of authentication (that isn't documented in the reports documentation) but it works if you add &user_agent=xxx to the request as it is missing in the example.

client, product, and description should include external ids to other systems

Many CRMs already have unique ids for client, product, and descriptions. It would be great if those systems sent Toggl external IDs for those fields if Toggl would return them inside API responses so they may be unambiguously linked to host data.

For instance, if I'm working on a new client opportunity in Salesforce, as a CRM it already has unique numbers for the account (client), opportunity (project) and maybe even a task (description).

If all the users on my account (or workspace--I really don't understand what those are) are using the same Salesforce system (and why not--they're my staff), then it would be easier to link the two systems.

Round off times

Is there a way to 'round off' the duration, similar to the UI?

Can the time entry API be used to START a timer?

If the start time is either omitted or set to the current time, and the duration and stop times are omitted, will Toggl start tracking time on that entry?

Basically, it's not clear from the API, but I'm curious if I can start a timer through the API, and if the user can see the timer start if they're in one of the apps (desktop, page, iPhone, or Android)?

Tag docs once an API has been finalized

It's awesome that the docs are on Github now, yay! Right now all changes are committed to master. It would be good to know what changes or updates are actually available in the production database. In order to know that, it would be great if the docs could be tagged with the API version that they match somehow? Doing this would allow us to also easily diff the changes in docs between API versions.

Maybe this isn't possible, but at least it would be nice to see if it is.

User current time entry

Hi guys,

Is it possible to get a users current time entry, so I can know what someone is working on at any given moment?

Thanks.

Filter reports by task

I need to enter daily totals on my timesheet for each task performed. When I filter the detailed report by project, the time entries for tasks are mixed up because they are sorted by date. It would be great if we had another level of filter granularity on tasks within a project.

API limits?

I can't find any mention of API limits in the documentation, as in requests per hour per user agent. I imagine there must be a limit. Is that something you can share?

Time Entry Project Attribute

In V6 of the API (public API) all time entries had which project they were a part of returned as part of the data received. In V8 that is no longer included.

Can this be amended?

Need to start the clock via API

There needs to be a start and/or stop that allows the remote to specify the user, client, project, and description.

If another task is already being time, it should be automatically stopped for this current one.

Alternatively, I would be OK if there were a way to pop-up the track page for the user, with parameters specifying the client, project, and description.

Include summary information when retrieving project data

All related information should be returned when retrieving data for a project (such as through a call to https://www.toggl.com/api/v8/projects/{project_id}, or to https://www.toggl.com/api/v8/workspaces/{workspace_id}/projects). This includes summary information that is currently provided through the reports summary api, such as total time, currency, amount and rate.

For consistency, this information should probably be returned for users and clients as well.

Reports

I'd like to see the same reports I can generate with the GUI available through the API.
I'm mostly referring to the CSVs of the detailed reports.

Thanks,
Gabi.

Reporting API sometimes returns "We are sorry, this PG::Error should never happen to you"

Our application makes fairly consistent, and fairly simple, calls to https://toggl.com/reports/api/v2/details. Most of the time these calls work perfectly, but every now and then we get the following error back:

"We are sorry, this PG::Error should never happen to you"

We're providing the following query string arguments:

  • user_agent
  • since
  • until
  • workspace_id
  • project_ids
  • page

One other detail I've noticed —our application sometimes includes multiple copies of each of those query string arguments. I'm going to see what I can do to fix that, but presumably that shouldn't be the problem here, since most standard URL parsing libraries would be able to ignore that (using the value of the last instance of the argument, I assume).

Stopping created time entries does not stop them

Hello

I hope this is the correct place to report issues. Otherwise please redirect me to the right place.

  1. Create a running time entry (as described in https://www.toggl.com/public/api)

curl -v -u YOUR_API_TOKEN:api_token -H "Content-type: application/json" -d "{"time_entry":{"tag_names":["API"],"billable":true,"description":"A new time entry","start":"2013-04-16T17:30:45+02:00","stop":null,"duration":-1366124361.927,"created_with":"Curl","project":{"id":524472}}}" -X POST https://www.toggl.com/api/v6/time_entries.json

  1. Go to Toggl web interface (https://www.toggl.com/track): A new time entry is shown as running
  2. Press the Stop button: The time entry stops running
  3. Press the refresh button in the browser

Is: time entry is running again (still)

Should: Stop it.

I really have no clue what I'm doing wrong here. It looks a lot like a bug to me. But when I start a new entry in the toggl web ui and then stop it, it is stopped for real.

Regards and thanks
Benno

Bad response - NULL

Simple request to your api:

GET /api/v8/time_entries?start_date=2013-05-26T00%3A00%3A00%2B00%3A00&end_date=2013-09-03T00%3A00%3A00%2B00%3A00 HTTP/1.1
Host: www.toggl.com
Content-Type: application/json
Authorization: Basic XXXXXXXXXXXX
Cache-Control: no-cache

will return only null in body response

This will throw error in most common uses (for example Tom Kane's ruby wrapper will break down on this error)

Problem is that there are no Time Entries. For me valid response should be [] empty array not null.

What do you think?

Ondrej Bartas

Retrieve users api_key in v8

Hello

I'm trying to switch from toggl API v6 to toggl API v8 but I am stuck. I use the API for the JIRA plugin Joggler. This plugin creates and edits time entries for various users. In v6 I was able to retrieve all api_token from all workspace users (https://www.toggl.com/api/v6/workspaces/{wid}/users.json) in v8 this call (https://www.toggl.com/api/v8/workspaces/{workspace_id}/users) does no longer include the api_token of the users. Is this a bug or a missing feature? Or is there another way to retrieve the api_token of users?

Regards
Benno

Inexplicable code of 500 from the api

We're getting an inexplicable code of 500 from the api when we post to it to get our auth.

Trying a try/catch gives me this (nothing helpful in the response):

undefined
undefined
failed [500]

This was working fine Thursday, and now nothing - even though we've not changed the code and I'm certain that the api token is correct. At the very least, the failure should return back something, right?

Here's the code:

try{

  //example modified from https://gist.github.com/2922814
  var auth_url = "https://www.toggl.com/api/v8/sessions";
  var result = Meteor.http.call("POST", auth_url, {
    params: {
      timeout: 30000
    },
      headers: {
        "content-type": "application/json"
      },
      auth: apiToken+":api_token"
  });

  }
  catch(err){
    console.log(err.tip);
    console.log(err.code);
    console.log(err.message);
  }

Any ideas??

Tasks :: Getting done_seconds

I am trying to get task details with the done_seconds included in the
returned json, I am programming my calls in php using curl.

From methods here:
https://github.com/toggl/toggl_api_docs/blob/master/chapters/tasks.md

and here:
https://github.com/toggl/toggl_api_docs/blob/master/chapters/workspaces.md

Thanks for your help,

Mike

Change Project Estimated Hours

On the Toggl website it's possible to choose if a Project's Estimated Workhours are based on the Tasks, or set the hours manually.

It doesn't seem to be possible to do this via the API, so we need to do this manually every time we add/update a Project in our system (which pushes to Toggl).

This was possible on the old API:
https://www.toggl.com/public/api#post_projects

Is this functionality going to be added to the API?
Or is the Project Time estimate going to be phased out entirely?

Tags

I'm trying to get the total amount of time spent on one or more time entries that will have been generated by one or more staff members over a unspecified period of time.

There may be another way to do this but we have put unique identifier set in both the tag for those time entries and also forms part of the description for the time item.

I'm trying to do something like:

curl -v -u {token}:api_token -X GET "https://toggl.com/reports/api/v2/details?user_agent={UA}&workspace_id={WID}&tag_ids={TID}"

return is:

{
"total_grand": null,
"total_billable": null,
"total_currencies": [],
"data": []
}

Obviously with correct id's to try and get a report that lists items by that tag id, although this appears to work via the reports page I cannot get it to work via the API?

Additionally though we can add, edit and remove tags the appears to be no method to list current tags?

We have also attempted to use description as a filter but due to the identifier only forming part of the description this seems to produce unreliable results unless there is a wildcard i'm not aware of?

Thanks

Barry

Filter detailed report by project id

I've experimented with retrieving reporting information by project id, but just seem to get all data back for a workspace - got that working fine - add workspace_id to the querystring.

Is it possible to reduce the amount of data returned by simply retrieving the time entries for the project I want rather than getting everything for the workspace back?

Managing workspace users

The API provides a way to retrieve all workspace users (https://github.com/toggl/toggl_api_docs/blob/master/chapters/workspaces.md#get-workspace-users), however management of them is not possible through the API.

Please add a way to add/invite users to a workspace, especially if users are created through the API (https://github.com/toggl/toggl_api_docs/blob/master/chapters/users.md#sign-up-new-user). Maybe, the user creation endpoint could be extended to already provide a workspace.

Furthermore, please also add a way to remove users from a workspace.


With this functionality we can fully automate user right management in Toggl (backed up by an HR system and Active Directory).

Btw, congratulations for the new Report API. This is exactly what we have been looking for!

[Feature request] Get time entries of the users on the project

Hello,

I would like to implement different messages and alerts for project managers and for this I would like to get time entries not only of the current user but for all the users for specific project or for all the users (more or less the capability that already exists in report area on the site).

Thanks,
Yan.

IDs of subgrouping items in Summary report

I would love to see subrouping items IDs when using Summary report. For example when using grouping=users and subgrouping=tasks, I get {task: "Task name"} items, but I need the ID of the task too.

Best regards,
Martin Stachon
MORAVIO.com

Missing method for admin user to get time entries for other users in workspace

In the web interface, an admin of a workspace can read/update/delete time entries entered by other users (either via summary or reports). It seems that this is not currently available in the API.

I'd really like to just be able to do:
GET https://www.toggl.com/api/v8/time_entries/{user_id}
with the optional parameters start_date and end_date, and get time entries for a specific user, thus preserving the convenience of admin permissions in the API.

Perhaps already in the roadmap? ETA?

Cheers,
A.

Aggregated time entries for the same task on the same day

I need to enter daily totals on my timesheet for each task performed. Currently the detailed report shows separate time entries when I work on the same task multiple times in a day. That's too granular for me.

I would love to see a reporting option to display aggregated time entries when they share date, client, project and task.

Reporting API Parameter &until= seems to be two days off

When fetching detailed reports the &until parameter needs to be set to the day after tomorrow in order to include entries from the current day. I haven't checked whether that's the case for the &since= parameter as well.

Example: I have to use the following URL to get today's (2013-08-16) entries: https://toggl.com/reports/api/v2/details?user_agent=nikolauspohleatgmailcom&workspace_id=315814&since=2013-07-19&until=2013-08-18&page=1

Please note that the application that consumes the API as well as most of our users are located in the time zone CET (GMT+1).

Could Time Entry include the uid as well?

When pulling the time entry, the user who created the time entry is not included. Is there any way the uid could be included when I pull a time entry?

I'm trying to move time entries between Toggl and an accounting tool. The user who created the time entry is quite important for billing purposes.

Note the added "uid" field below... that's what I have in mind.

{
"data":
{
"id":436694100,
"uid":XXXXXX,
"pid":123,
"wid":777,
"billable":false,
"start":"2013-03-05T07:58:58.000Z",
"duration":1200,
"description":"Meeting with possible clients",
"tags":["billed"]
}
}

Get task returning null data

I'm trying to GET https://www.toggl.com/api/v8/tasks/1905744 as 1905744 is the task id that is specified for 78808206. The user in question has id = 473662

I could have sworn that this works before, but now all I receive in response is {"data":null}.

Tasks are for pro workspaces only - would this occur if a user was once paying but stopped subscribing? What else would cause this behavior? This is for a client of mine and I can only access his account through the API.

Bulk add tags to time entries?

I'm going to be transferring time entries into another system for invoicing, and I'd like to tag each time entry once it's been successfully transferred.

Do I have to perform a separate POST update for each time entry that I want to tag?

Three of our teammates share the same API!

Three of our teammates share the same API, and for that reason we can't get the details of each one. Only details for one of those teammates are shown.
How is it possible to get a unique api token for each one?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.