API V5

Overview

Schema

All API access is over HTTPS, and accessed from the api.plan.toggl.com/api/v5 domain. All data is received as JSON.

All dates are returned in ISO 8601 format:

YYYY-MM-DD

2014-12-31

All dates with time are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

2014-12-31T11:59:59+01:00

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SS.000Z

2014-12-31T11:59:59.999+01:00

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

$ curl "https://api.plan.toggl.com/api/v5/1/projects?filter=active" -i

In this example, the workspace identity value is provided for the :workspace parameter in the path while :filter is passed in the query string.

For POST, PUT, and DELETE requests, parameters not included in the URL:

$ curl "https://api.plan.toggl.com/api/v5/me" -i --data "name=Elmo"

Client Errors

There are four possible types of client errors on API calls that receive request bodies:

Sending invalid fields will result in a 422 Unprocessable Entity response.

HTTP/1.1 422 Unprocessable Entity

{
  "errors": {
    "email": ["format is invalid"],
    "avatar_color": ["is not included in the list"]
  }
}

Sending a request to interact with an unexistent resource will result in a 404 Resource Not Found response.

HTTP/1.1 404 Resource Not Found

Sending a request to interact with a resource that is beyond the scope of your current user will result in a 403 Forbidden response.

HTTP/1.1 403 Forbidden

Sending a request with invalid Authorization header will result in a 401 Unauthorized response.

HTTP/1.1 401 Unauthorized

HTTP Redirects

API v5 uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field which contains the URI of the resource to which the client should repeat the requests.

Status Code Description
301 Permanent redirection. The URI you used to make the request has been superseded by the one specified in the Location header field. This and all future requests to this resource should be directed to the new URI.
302, 307 Temporary redirection. The request should be repeated verbatim to the URI specified in the Location header field but clients should continue to use the original URI for future requests.

Other redirection status codes may be used in accordance with the HTTP 1.1 spec.

HTTP Verbs

Where possible, API v5 strives to use appropriate HTTP verbs for each action.

Verb Description
HEAD Can be issued against any resource to get just the HTTP header info.
GET Used for retrieving resources.
POST Used for creating resources, or performing custom actions (such as merging a pull request).
PUT Used for updating resources. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETE Used for deleting resources.

Authentication

Authentication is implemented by OAuth 2.0. Requests that require authentication will return 404 Not Found, instead of 403 Forbidden, in some places. This is to prevent the accidental leakage of private data to unauthorized users.

Basic Authentication

OAuth2 Token (sent in a header)

$ curl "https://api.plan.toggl.com/api/v5" -H "Authorization: Bearer OAUTH-TOKEN"

OAuth2 Token (sent as a parameter)

$ curl "https://api.plan.toggl.com/api/v5/?access_token=OAUTH-TOKEN"

Cross Origin Resource Sharing

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests.

Here’s a sample request sent from a browser hitting http://example.com:

$ curl -i "https://api.plan.toggl.com/api/v5" -H "Origin: http://example.com"

Here’s a sample request for a browser hitting http://example.com:

$ curl -i "https://api.plan.toggl.com/api/v5" -H "Origin: http://example.com"
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Max-Age: 1728000
Access-Control-Allow-Credentials: true

Authentication

We use the OAuth 2.0 protocol for authentication and authorization. Currently only two authorization grants (protocol flows) are supported: Authorization Code Grant and Resource Owner Password Credentials Grant. We only allow the access to our API on behalf of a Toggl Plan user.

All developers need to register their application before getting started. A registered OAuth application is assigned a unique Client ID (API Key) and Client Secret (API Secret). The Client Secret should not be shared.

For registering your application sign in on developers site with your Toggl Plan credentials and create new application.

Authorization Code Grant (Web Application Flow)

This grant type is useful when you implement your own web application that you want to be integreted with Toggl Plan. It lets the app request authorization in a user’s account without getting their password.

This is a description of the OAuth2 flow from 3rd party web sites.

  1. Redirect users to request access

    GET https://plan.toggl.com/oauth/login

    Parameters

    Name Type Description
    response_type string Required. Must be set to “code”.
    client_id string Required. The client ID (App key) you received from Toggl Plan when you registered.
    redirect_uri string The URL in your app where users will be sent after authorization. See details below about redirect urls.
    state string An unguessable random string. It is used to protect against cross-site request forgery attacks.

  2. Toggl Plan redirects back to your site

    If the user accepts your request, Toggl Plan redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don’t match, the request has been created by a third party and the process should be aborted.

    Exchange this for an access token:

    POST https://api.plan.toggl.com/api/v5/authenticate/token
 Authorization: Basic Base64(CLIENT-ID:CLIENT-SECRET)

    Example using curl:

    curl https://api.plan.toggl.com/api/v5/authenticate/token -d grant_type=authorization_code -d code=random_code_returned_previously1234 -d client_id=random_id_123 --user random_id_123:really_secret_secret

    Parameters

    Name Type Description
    grant_type string Required. Must be set to “authorization_code”.
    code string Required. The code you received as a response to Step 1.
    client_id string Required. The client ID (App key) you received from Toggl Plan when you registered.

    Response

    {
   "access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a",
   "refresh_token": "2c6912e7710c838347ae178b4ae72e16c7e42f292",
   "expires_in": 3600,
   "token_type": "bearer"
 }

  3. Use the access token to access the API

    The access token allows you to make requests to the API on a behalf of a user.

    GET https://api.plan.toggl.com/api/v5/me?access_token=...

    You can pass the token in the query params like shown above, but a cleaner approach is to include it in the Authorization header

    Authorization: Bearer OAUTH-TOKEN

    For example, in curl you can set the Authorization header like this:

    curl "https://api.plan.toggl.com/api/v5/me" -H "Authorization: Bearer OAUTH-TOKEN"

Resource Owner Password Credentials Grant

This grant type should only be used when you implement a server-to-server app. Your app MUST NOT be available to the public. The grant type is useful for scripting (import, export, gathering statistics, etc.). It lets the app request an access token directly using a user’s account credentials. It should be your own Toggl Plan user account.

  1. Make a token request with grant_type=password:

    POST https://api.plan.toggl.com/api/v5/authenticate/token
 Authorization: Basic Base64(CLIENT-ID:CLIENT-SECRET)

    Example using curl:

    curl https://api.plan.toggl.com/api/v5/authenticate/token -d grant_type=password -d username=<username> -d password=<password> --user <client-id>:<client-secret>

    Parameters

    Name Type Description
    grant_type string Required. Must be set to “password”.
    username string Required. The email of the Toggl Plan user.
    password string Required. The password of the Toggl Plan user.

    Response

    {
   "access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a",
   "refresh_token": "2c6912e7710c838347ae178b4ae72e16c7e42f292",
   "expires_in": 3600,
   "token_type": "bearer"
 }

  2. Use the access token obtained to access the API:

    GET https://api.plan.toggl.com/api/v5/me
 Authorization: Bearer ACCESS-TOKEN

Refreshing an Access Token

It’s possible to refresh an expired access token with its refresh token, which has a longer time span. The refresh token can only be used once.

  1. Exchange the refresh token for an access token:

    POST https://api.plan.toggl.com/api/v5/authenticate/token
 Authorization: Basic Base64(CLIENT-ID:CLIENT-SECRET)

    Parameters

    Name Type Description
    grant_type string Required. Must be set to “refresh_token”.
    refresh_token string Required. The refresh token issued to the client with the access token.

    Response

    {
   "access_token": "e72e16c7e42123123123adgasdas7710c838347ae178b4a",
   "refresh_token": "2c6912e7710c838347ae178b4ne72e16c7e42f292",
   "expires_in": 3600,
   "token_type": "bearer"
 }

Redirect URLs

The redirect_uri parameter is optional. If left out, Toggl Plan will redirect users to the callback URL configured in the OAuth Application settings. If provided, the redirect URL must exactly match the callback URL.

User profile

Get profile information

GET /me
GET https://api.plan.toggl.com/api/v5/me

Request

Content-Type: application/json
Authorization: Bearer <token>

Response 200

Content-Type: application/json; charset=utf-8
{
  "id": 1,
  "name": "Elmo",
  "email": "elmo@muppets.com",
  "color": "#db9a9a",
  "color_id": 1,
  "initials": "el",
  "picture_url": "/avatars/1/large/picture.png",
  "has_picture": true,
  "workspaces": [],
  "invitations": [],
  "project_ids": [],
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Update profile

PUT /me
PUT https://api.plan.toggl.com/api/v5/me

Request

Content-Type: application/json
Authorization: Bearer <token>
{
  "name": "Elmo",
  "initials": "el"
}

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "Elmo",
  "email": "elmo@muppets.com",
  "color": "#db9a9a",
  "color_id": 1,
  "initials": "el",
  "picture_url": "/avatars/1/large/picture.png",
  "has_picture": true,
  "workspaces": [],
  "invitations": [],
  "project_ids": [],
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Members

Add a new member

POST /1/dummy_users
POST https://api.plan.toggl.com/api/v5/1/dummy_users

New member can be added using name. It has no link with an existing user.

To link a new member with an existing user you have to create an invitation.

URI Parameters

workspace
integer (required) 1

Workspace identity

Request

Content-Type: application/json
Authorization: Bearer <token>
{
    "name": "Elmo",
    "role": "regular
}

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "Elmo",
  "email": "elmo@muppets.com",
  "color": "#db9a9a",
  "color_id": 1,
  "initials": "el",
  "invitation": {},
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Update member not yet linked with existing user

PUT /1/dummy_users/1
PUT https://api.plan.toggl.com/api/v5/1/dummy_users/1

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 1

Dummy User identity.

Request

Content-Type: application/json
Authorization: Bearer <token>
{
  "name": "Elmo",
  "initials": "el",
  "color_id": 33
}

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "Elmo",
  "email": "elmo@muppets.com",
  "color": "#db9a9a",
  "color_id": 1,
  "initials": "el",
  "invitation": {},
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Fetch list of members

GET /1/members
GET https://api.plan.toggl.com/api/v5/1/members

URI Parameters

workspace
integer (required) 1

Workspace identity

Request

Content-Type: application/json
Authorization: Bearer <token>

Response 200

Content-Type: application/json
[
  {
    "role": "regular",
    "active": true,
    "color": "#db9a9a",
    "color_id": 1,
    "hours_per_work_day": "3.5",
    "minutes_per_work_day": 210,
    "dummy": false,
    "picture_url": "/avatars/1/large/picture.png",
    "has_picture": true,
    "invitation": {},
    "activated_at": "null",
    "deactivated_at": "null",
    "id": 1,
    "name": "Elmo",
    "email": "elmo@muppets.com",
    "initials": "el",
    "created_at": "2016-01-01T00:00:00.00Z+00:00",
    "updated_at": "2016-01-01T00:00:00.00Z+00:00"
  }
]

Get member

GET /1/members/1
GET https://api.plan.toggl.com/api/v5/1/members/1

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 1

User identity.

Request

Content-Type: application/json
Authorization: Bearer <token>

Response 200

Content-Type: application/json
{
  "role": "regular",
  "active": true,
  "color": "#db9a9a",
  "color_id": 1,
  "hours_per_work_day": "3.5",
  "minutes_per_work_day": 210,
  "dummy": false,
  "picture_url": "/avatars/1/large/picture.png",
  "has_picture": true,
  "invitation": {},
  "activated_at": "null",
  "deactivated_at": "null",
  "id": 1,
  "name": "Elmo",
  "email": "elmo@muppets.com",
  "initials": "el",
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Update member

PUT /1/members/1
PUT https://api.plan.toggl.com/api/v5/1/members/1

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 1

User identity.

Request

Content-Type: application/json
Authorization: Bearer <token>
{
  "name": "Elmo",
  "initials": "el",
  "color": "#a1711e",
  "weight": 1
}

Response 200

Content-Type: application/json
{
  "role": "regular",
  "active": true,
  "color": "#db9a9a",
  "color_id": 1,
  "hours_per_work_day": "3.5",
  "minutes_per_work_day": 210,
  "dummy": false,
  "picture_url": "/avatars/1/large/picture.png",
  "has_picture": true,
  "invitation": {},
  "activated_at": "null",
  "deactivated_at": "null",
  "id": 1,
  "name": "Elmo",
  "email": "elmo@muppets.com",
  "initials": "el",
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Remove member

DELETE /1/members/2
DELETE https://api.plan.toggl.com/api/v5/1/members/2

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 2

User identity.

Request

Content-Type: application/json
Authorization: Bearer <token>

Response 204

Content-Type: application/json

Tasks

Fetch list of tasks

GET /1/tasks/timeline?since=&until=&users=&project=&tasks=&group=&tags=
GET https://api.plan.toggl.com/api/v5/1/tasks/timeline?since=&until=&users=&project=&tasks=&group=&tags=

URI Parameters

workspace
integer (required) 1

Workspace identity

filter
string (optional) timeline

Named filter for tasks. Allowed values are backlog or timeline. you can also put no filter, which will return any.

Choices: timeline backlog

since
string (optional) 

Only tasks after this date will be returned. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

until
string (optional) 

Only tasks before this date will be returned. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

users
array(integer) (optional) 

Filters tasks by users. Only available when filter is set to timeline.

project
integer (optional) 

Filters tasks by projects.

tasks
array(integer) (optional) 

Filters tasks by a list of ids.

group
integer (optional) 

Filters tasks by group.

tags
array(integer) (optional) 

Filters tasks by a list of tags.

Request

Authorization: Bearer <token>

Response 200

Content-Type: application/json
[
  {
    "id": 1,
    "name": "Act like muppet",
    "notes": "must try hard",
    "start_date": "2016-01-01",
    "end_date": "2016-01-01",
    "start_time": "12:00",
    "end_time": "13:00",
    "color": "#db9a9a",
    "color_id": 1,
    "estimated_hours": "3.5",
    "estimated_minutes": "210",
    "status": "done",
    "workspace_members": [
      1
    ],
    "folder_id": 1,
    "tag_ids": [
      1
    ],
    "position": 1,
    "weight": 1,
    "created_at": "2016-01-01T00:00:00.00Z+00:00",
    "updated_at": "2016-01-01T00:00:00.00Z+00:00"
  }
]

Add a task

POST /1/tasks
POST https://api.plan.toggl.com/api/v5/1/tasks

URI Parameters

workspace
integer (required) 1

Workspace identity

Request

Content-Type: application/json
Authorization: Bearer <token>
{
  "name": "Lunch with Abby",
  "start_date": "2014-01-01",
  "end_date": "2014-01-01",
  "start_time": "12:00",
  "end_time": "13:00",
  "color": "#a8ced7",
  "estimated_hours": 0,
  "pinned": false,
  "status": "done",
  "workspace_members": [
    1
  ],
  "project_id": 1
}

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "Act like muppet",
  "notes": "must try hard",
  "start_date": "2016-01-01",
  "end_date": "2016-01-01",
  "start_time": "12:00",
  "end_time": "13:00",
  "color": "#db9a9a",
  "color_id": 1,
  "estimated_hours": "3.5",
  "estimated_minutes": "210",
  "status": "done",
  "workspace_members": [
    1
  ],
  "folder_id": 1,
  "tag_ids": [
    1
  ],
  "position": 1,
  "weight": 1,
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Get a task

GET /1/tasks/1
GET https://api.plan.toggl.com/api/v5/1/tasks/1

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 1

Task identity.

Request

Authorization: Bearer <token>

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "Act like muppet",
  "notes": "must try hard",
  "start_date": "2016-01-01",
  "end_date": "2016-01-01",
  "start_time": "12:00",
  "end_time": "13:00",
  "color": "#db9a9a",
  "color_id": 1,
  "estimated_hours": "3.5",
  "estimated_minutes": "210",
  "status": "done",
  "workspace_members": [
    1
  ],
  "folder_id": 1,
  "tag_ids": [
    1
  ],
  "position": 1,
  "weight": 1,
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Update a task

PUT /1/tasks/1
PUT https://api.plan.toggl.com/api/v5/1/tasks/1

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 1

Task identity.

Request

Content-Type: application/json
Authorization: Bearer <token>
{
  "name": "Lunch with Abby",
  "start_date": "2014-01-01",
  "end_date": "2014-01-01",
  "start_time": "12:00",
  "end_time": "13:00",
  "color": "#a8ced7",
  "estimated_hours": 0,
  "pinned": false,
  "status": "done",
  "workspace_members": [
    1
  ],
  "project_id": 1
}

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "Act like muppet",
  "notes": "must try hard",
  "start_date": "2016-01-01",
  "end_date": "2016-01-01",
  "start_time": "12:00",
  "end_time": "13:00",
  "color": "#db9a9a",
  "color_id": 1,
  "estimated_hours": "3.5",
  "estimated_minutes": "210",
  "status": "done",
  "workspace_members": [
    1
  ],
  "folder_id": 1,
  "tag_ids": [
    1
  ],
  "position": 1,
  "weight": 1,
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Remove a task

DELETE /1/tasks/2
DELETE https://api.plan.toggl.com/api/v5/1/tasks/2

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 2

Task identity.

Request

Authorization: Bearer <token>

Response 204

Content-Type: application/json

Milestones

Fetch list of milestones

GET /1/milestones?since=&until=&projects=&groups=
GET https://api.plan.toggl.com/api/v5/1/milestones?since=&until=&projects=&groups=

URI Parameters

workspace
integer (required) 1

Workspace identity

since
string (optional) 

Only tasks after this date will be returned. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

until
string (optional) 

Only tasks before this date will be returned. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

projects
array(integer) (optional) 

Filters milestones by projects.

groups
array(integer) (optional) 

Filters milestones by groups.

Request

Authorization: Bearer <token>

Response 200

Content-Type: application/json
[
  {
    "id": 1,
    "name": "End of season 1",
    "color": "#db9a9a",
    "color_id": 1,
    "date": "2016-12-01",
    "done": false,
    "holiday": false,
    "group_id": 1,
    "created_at": "2016-01-01T00:00:00.00Z+00:00",
    "updated_at": "2016-01-01T00:00:00.00Z+00:00"
  }
]

Add a new milestone

POST /1/milestones
POST https://api.plan.toggl.com/api/v5/1/milestones

URI Parameters

workspace
integer (required) 1

Workspace identity

Request

Content-Type: application/json
Authorization: Bearer <token>
{
  "name": "End of season 1",
  "date": "2014-01-01",
  "done": false,
  "holiday": false,
  "group_id": null
}

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "End of season 1",
  "color": "#db9a9a",
  "color_id": 1,
  "date": "2016-12-01",
  "done": false,
  "holiday": false,
  "group_id": 1,
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Get a milestone

GET /1/milestones/1
GET https://api.plan.toggl.com/api/v5/1/milestones/1

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 1

Milestone identity.

Request

Content-Type: application/json
Authorization: Bearer <token>

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "End of season 1",
  "color": "#db9a9a",
  "color_id": 1,
  "date": "2016-12-01",
  "done": false,
  "holiday": false,
  "group_id": 1,
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Update a milestone

PUT /1/milestones/1
PUT https://api.plan.toggl.com/api/v5/1/milestones/1

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 1

Milestone identity.

Request

Content-Type: application/json
Authorization: Bearer <token>
{
  "name": "End of season 1",
  "date": "2014-01-01",
  "done": false,
  "holiday": false,
  "group_id": 1
}

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "End of season 1",
  "color": "#db9a9a",
  "color_id": 1,
  "date": "2016-12-01",
  "done": false,
  "holiday": false,
  "group_id": 1,
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Remove a milestone

DELETE /1/milestones/2
DELETE https://api.plan.toggl.com/api/v5/1/milestones/2

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 2

Milestone identity.

Request

Authorization: Bearer <token>

Response 204

Content-Type: application/json

Projects

Fetch list of projects

GET /1/projects
GET https://api.plan.toggl.com/api/v5/1/projects

URI Parameters

workspace
integer (required) 1

Workspace identity

Request

Authorization: Bearer <token>

Response 200

Content-Type: application/json
[
  {
    "id": 1,
    "name": "Quality time",
    "archived": false,
    "tags": [
      null
    ],
    "color": "#db9a9a",
    "color_id": 1,
    "created_at": "2016-01-01T00:00:00.00Z+00:00",
    "updated_at": "2016-01-01T00:00:00.00Z+00:00"
  }
]

Add a new project

POST /1/projects
POST https://api.plan.toggl.com/api/v5/1/projects

URI Parameters

workspace
integer (required) 1

Workspace identity

Request

Content-Type: application/json
Authorization: Bearer <token>
{
  "name": "Quality time",
  "color": "#8392ae"
}

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "Quality time",
  "archived": false,
  "tags": [
    null
  ],
  "color": "#db9a9a",
  "color_id": 1,
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Get a project

GET /1/projects/1
GET https://api.plan.toggl.com/api/v5/1/projects/1

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 1

Project identity.

Request

Authorization: Bearer <token>

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "Quality time",
  "archived": false,
  "tags": [
    null
  ],
  "color": "#db9a9a",
  "color_id": 1,
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Update a project

PUT /1/projects/1
PUT https://api.plan.toggl.com/api/v5/1/projects/1

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 1

Project identity.

Request

Authorization: Bearer <token>
{
  "name": "Quality time",
  "color": "#8392ae"
}

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "Quality time",
  "archived": false,
  "tags": [
    null
  ],
  "color": "#db9a9a",
  "color_id": 1,
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Remove a project

DELETE /1/projects/2
DELETE https://api.plan.toggl.com/api/v5/1/projects/2

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 2

Project identity.

Request

Authorization: Bearer <token>

Response 204

Content-Type: application/json

Groups

Fetch list of groups

GET /1/groups
GET https://api.plan.toggl.com/api/v5/1/groups

URI Parameters

workspace
integer (required) 1

Workspace identity

Request

Authorization: Bearer <token>

Response 200

Content-Type: application/json
[
  {
    "id": 1,
    "name": "Muppets",
    "memberships": [
      {
        "id": 1,
        "user_id": 1,
        "position": 1,
        "weight": 1,
        "created_at": "2016-01-01T00:00:00.00Z+00:00",
        "updated_at": "2016-01-01T00:00:00.00Z+00:00"
      }
    ],
    "created_at": "2016-01-01T00:00:00.00Z+00:00",
    "updated_at": "2016-01-01T00:00:00.00Z+00:00"
  }
]

Add a new group

POST /1/groups
POST https://api.plan.toggl.com/api/v5/1/groups

URI Parameters

workspace
integer (required) 1

Workspace identity

Request

Content-Type: application/json
Authorization: Bearer <token>
{
  "name": "Muppets",
  "user_ids": [
    1,
    2,
    3
  ]
}

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "Muppets",
  "memberships": [
    {
      "id": 1,
      "user_id": 1,
      "position": 1,
      "weight": 1,
      "created_at": "2016-01-01T00:00:00.00Z+00:00",
      "updated_at": "2016-01-01T00:00:00.00Z+00:00"
    }
  ],
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Get a group

GET /1/groups/1
GET https://api.plan.toggl.com/api/v5/1/groups/1

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 1

Group identity.

Request

Authorization: Bearer <token>

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "Muppets",
  "memberships": [
    {
      "id": 1,
      "user_id": 1,
      "position": 1,
      "weight": 1,
      "created_at": "2016-01-01T00:00:00.00Z+00:00",
      "updated_at": "2016-01-01T00:00:00.00Z+00:00"
    }
  ],
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Update a group

PUT /1/groups/1
PUT https://api.plan.toggl.com/api/v5/1/groups/1

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 1

Group identity.

Request

Authorization: Bearer <token>
{
  "name": "Muppets",
  "user_ids": [
    1,
    2,
    3
  ]
}

Response 200

Content-Type: application/json
{
  "id": 1,
  "name": "Muppets",
  "memberships": [
    {
      "id": 1,
      "user_id": 1,
      "position": 1,
      "weight": 1,
      "created_at": "2016-01-01T00:00:00.00Z+00:00",
      "updated_at": "2016-01-01T00:00:00.00Z+00:00"
    }
  ],
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Remove a group

DELETE /1/groups/2
DELETE https://api.plan.toggl.com/api/v5/1/groups/2

URI Parameters

workspace
integer (required) 1

Workspace identity

id
integer (required) 2

Group identity.

Request

Authorization: Bearer <token>

Response 204

Content-Type: application/json

Fetch list of group memberships

GET /1/groups/1/memberships
GET https://api.plan.toggl.com/api/v5/1/groups/1/memberships

URI Parameters

workspace
integer (required) 1

Workspace identity

group_id
integer (required) 1

Group identity.

Request

Authorization: Bearer <token>

Response 200

Content-Type: application/json
[
  {
    "id": 1,
    "user_id": 1,
    "position": 1,
    "weight": 1,
    "created_at": "2016-01-01T00:00:00.00Z+00:00",
    "updated_at": "2016-01-01T00:00:00.00Z+00:00"
  }
]

Add a new user to group

POST /1/groups/1/memberships
POST https://api.plan.toggl.com/api/v5/1/groups/1/memberships

URI Parameters

workspace
integer (required) 1

Workspace identity

group_id
integer (required) 1

Group identity.

Request

Content-Type: application/json
Authorization: Bearer <token>
{
  "user_id": 1
}

Response 200

Content-Type: application/json
{
  "id": 1,
  "user_id": 1,
  "position": 1,
  "weight": 1,
  "created_at": "2016-01-01T00:00:00.00Z+00:00",
  "updated_at": "2016-01-01T00:00:00.00Z+00:00"
}

Remove a group membership

DELETE /1/groups/1/memberships/2
DELETE https://api.plan.toggl.com/api/v5/1/groups/1/memberships/2

URI Parameters

workspace
integer (required) 1

Workspace identity

group_id
integer (required) 1

Group identity.

id
integer (required) 2

Membership identity.

Request

Authorization: Bearer <token>

Response 204

Content-Type: application/json