Toggl (version v1.*.*)

create_client#

Create a client

Parameters

$body#

Type: object

{
  "client" : {
    "wid" : "workspace ID",
    "notes" : "notes for the client",
    "at" : "timestamp that is sent in the response",
    "name" : "name of the client"
  }
}

create_group#

Create a group

Parameters

$body#

Type: object

{
  "group" : {
    "wid" : "workspace ID",
    "at" : "timestamp that is sent in the response",
    "name" : "name of the group"
  }
}

create_project#

Create a project

Parameters

$body#

Type: object

{
  "project" : {
    "is_private" : "whether project is accessible for only project users or for all workspace users",
    "template" : "whether the project can be used as a template",
    "color" : "id of the color selected for the project",
    "active" : "whether the project is archived or not",
    "billable" : "whether the project is billable or not, available only for pro workspaces",
    "auto_estimates" : "whether the estimated hours are automatically calculated based on task estimations or manually fixed based on the value of 'estimated_hours', premium functionality",
    "wid" : "workspace ID",
    "at" : "timestamp indicating when the project was created (UTC time), read-only",
    "rate" : "hourly rate of the project, premium functionality",
    "name" : "name of the project",
    "estimated_hours" : "if auto_estimates is true then the sum of task estimations is returned, otherwise user inserted hours, premium functionality",
    "template_id" : "id of the template project used on current project's creation",
    "cid" : "client ID"
  }
}

create_tag#

Create tag

Parameters

$body#

Type: object

{
  "tag" : {
    "wid" : "workspace ID, where the tag will be used",
    "name" : "The name of the tag, unique in workspace"
  }
}

create_task#

Create a task

Parameters

$body#

Type: object

{
  "task" : {
    "uid" : "user ID, to whom the task is assigned to",
    "wid" : "workspace ID",
    "at" : "timestamp that is sent in the response for PUT, indicates the time task was last updated",
    "estimated_seconds" : "estimated duration of task in seconds",
    "name" : "The name of the task",
    "active" : "whether the task is done or not",
    "pid" : "project ID for the task",
    "tracked_seconds" : "total time tracked (in seconds) for the task"
  }
}

create_time_entry#

Create a time entry

Parameters

$body#

Type: object

{
  "time_entry" : {
    "duration" : "time entry duration in seconds. 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.",
    "wid" : "workspace ID",
    "at" : "timestamp that is sent in the response, indicates the time item was last updated",
    "stop" : "time entry stop time, ISO 8601 date and time",
    "start" : "time entry start time, ISO 8601 date and time",
    "description" : "description",
    "pid" : "project ID",
    "created_with" : "the name of your client app",
    "billable" : "available for pro workspaces",
    "duronly" : "should Toggl show the start and stop time of this time entry?",
    "tid" : "task ID",
    "tags" : [ "string" ]
  }
}

create_user_for_project#

Create a project user. To create multiple project users for a single project, you must add multiple user ids separated with a comma with the uid parameter.

Parameters

$body#

Type: object

{
  "project_user" : {
    "uid" : { },
    "wid" : "workspace ID",
    "at" : "timestamp that is sent in the response, indicates when the project user was last updated",
    "manager" : "admin rights for this project",
    "rate" : "hourly rate for the project user (only for pro workspaces) in the currency of the project's client or in workspace default currency.",
    "pid" : "project ID",
    "fields" : "fullname: full name of the user, who is added to the project"
  }
}

delete_client#

Delete a client

Parameters

client_id (required)#

client ID

Type: integer

delete_group#

Delete a group

Parameters

group_id (required)#

group ID

Type: integer

delete_multiple_projects#

Delete multiple projects

Parameters

project_ids (required)#

multiple project IDs

Type: array

[ "project ID" ]

delete_multiple_users_for_project#

Delete multiple project users

Parameters

project_user_ids (required)#

multiple project user IDs

Type: array

[ "project user ID" ]

delete_project#

Delete a project

Parameters

project_id (required)#

project ID

Type: integer

delete_tag#

Delete a tag

Parameters

tag_id (required)#

tag ID

Type: integer

delete_task#

Delete a task

Parameters

task_id (required)#

multiple task IDs

Type: object

{ }

delete_time_entry#

Delete a time entry

Parameters

time_entry_id (required)#

time entry ID

Type: integer

delete_user_for_project#

Delete a project user

Parameters

project_user_id (required)#

project user ID

Type: integer

delete_workspace_user#

Delete workspace user.

Parameters

workspace_user_id (required)#

workspace user ID

Type: integer

get_client#

Get client details

Parameters

client_id (required)#

client ID

Type: integer

get_current_user_data#

Get current user data

Parameters

since#

retrieve objects which have changed after certain time. The value should be a unix timestamp.

Type: string

with_related_data#

whether to get all the workspaces, clients, projects, tasks, time entries and tags which the user can see

Type: boolean

get_dashboard_data#

Get dashboard data. Dashboard's main purpose is to give an overview of what users in the workspace are doing and have been doing.

Parameters

workspace_id (required)#

workspace ID

Type: integer

get_detailed_report#

The detailed report returns the time entries for the requested parameters/filters.

Parameters

user_agent (required)#

The name of your application or your email address so we can get in touch in case you're doing something wrong.

Type: string

workspace_id (required)#

The workspace whose data you want to access.

Type: integer

billable#

Type: string

Potential values: yes, no, both

client_ids#

A list of client IDs separated by a comma. Use "0" if you want to filter out time entries without a client.

Type: object

{ }

description#

Matches against time entry descriptions.

Type: string

display_hours#

Determines whether to display hours as a decimal number or with minutes.

Type: string

Potential values: decimal, minutes

distinct_rates#

Type: string

Potential values: on, off

members_of_group_ids#

A list of group IDs separated by a comma. This limits provided user_ids to the members of the given groups.

Type: array

[ "group ID" ]

or_members_of_group_ids#

A list of group IDs separated by a comma. This extends provided user_ids with the members of the given groups.

Type: array

[ "GroupId" ]

order_desc#

"on" for descending, or "off" for ascending order.

Type: string

Potential values: on, off

order_field#

Type: string

Potential values: date, description, duration, user

page#

Type: integer

project_ids#

A list of project IDs separated by a comma. Use "0" if you want to filter out time entries without a project.

Type: object

{ }

rounding#

Rounds time according to workspace settings.

Type: string

Potential values: on, off

since#

ISO 8601 date (YYYY-MM-DD) format. Defaults to today - 6 days.

Type: string

tag_ids#

A list of tag IDs separated by a comma. Use "0" if you want to filter out time entries without a tag.

Type: object

{ }

task_ids#

A list of task IDs separated by a comma. Use "0" if you want to filter out time entries without a task.

Type: object

{ }

time_entry_ids#

A list of time entry IDs separated by a comma.

Type: array

[ "GroupId" ]

until#

ISO 8601 date (YYYY-MM-DD) format. Note: Maximum date span (until - since) is one year. Defaults to today, unless since is in future or more than year ago, in this case until is since + 6 days.

Type: string

user_ids#

A list of user IDs separated by a comma.

Type: array

[ "user ID" ]

without_description#

Filters out the time entries which do not have a description (literally "(no description)").

Type: boolean

get_project#

Get project data

Parameters

project_id (required)#

project ID

Type: integer

get_project_users_for_workspace#

Get workspace project users

Parameters

workspace_id (required)#

workspace ID

Type: integer

get_projects_for_client#

Get client projects

Parameters

client_id (required)#

client ID

Type: integer

active#

By default true. If false, only archived projects are returned.

Type: string

Potential values: true, false, both

get_running_time_entry#

This operation has no parameters

get_summary_report#

Summary report returns the aggregated time entries data. time entries for the requested

Parameters

user_agent (required)#

The name of your application or your email address so we can get in touch in case you're doing something wrong.

Type: string

workspace_id (required)#

The workspace whose data you want to access.

Type: integer

billable#

Type: string

Potential values: yes, no, both

client_ids#

A list of client IDs separated by a comma. Use "0" if you want to filter out time entries without a client.

Type: object

{ }

description#

Matches against time entry descriptions.

Type: string

display_hours#

Determines whether to display hours as a decimal number or with minutes.

Type: string

Potential values: decimal, minutes

distinct_rates#

Type: string

Potential values: on, off

grouped_time_entry_ids#

Type: boolean

grouping#

Type: string

Potential values: projects, clients, users

members_of_group_ids#

A list of group IDs separated by a comma. This limits provided user_ids to the members of the given groups.

Type: array

[ "group ID" ]

or_members_of_group_ids#

A list of group IDs separated by a comma. This extends provided user_ids with the members of the given groups.

Type: array

[ "GroupId" ]

order_desc#

"on" for descending, or "off" for ascending order.

Type: string

Potential values: on, off

order_field#

Type: string

Potential values: title, duration, amount

project_ids#

A list of project IDs separated by a comma. Use "0" if you want to filter out time entries without a project.

Type: object

{ }

rounding#

Rounds time according to workspace settings.

Type: string

Potential values: on, off

since#

ISO 8601 date (YYYY-MM-DD) format. Defaults to today - 6 days.

Type: string

subgrouping#

Type: string

Potential values: time_entries, tasks, users, projects, clients

subgrouping_ids#

Type: boolean

tag_ids#

A list of tag IDs separated by a comma. Use "0" if you want to filter out time entries without a tag.

Type: object

{ }

task_ids#

A list of task IDs separated by a comma. Use "0" if you want to filter out time entries without a task.

Type: object

{ }

time_entry_ids#

A list of time entry IDs separated by a comma.

Type: array

[ "GroupId" ]

until#

ISO 8601 date (YYYY-MM-DD) format. Note: Maximum date span (until - since) is one year. Defaults to today, unless since is in future or more than year ago, in this case until is since + 6 days.

Type: string

user_ids#

A list of user IDs separated by a comma.

Type: array

[ "user ID" ]

without_description#

Filters out the time entries which do not have a description (literally "(no description)").

Type: boolean

get_task#

Get task details

Parameters

task_id (required)#

task ID

Type: integer

get_time_entry#

Get time entry details

Parameters

time_entry_id (required)#

time entry ID

Type: integer

get_weekly_report#

The weekly report gives aggregated 7 day durations or earnings grouped by users and projects.

Parameters

user_agent (required)#

The name of your application or your email address so we can get in touch in case you're doing something wrong.

Type: string

workspace_id (required)#

The workspace whose data you want to access.

Type: integer

billable#

Type: string

Potential values: yes, no, both

calculate#

Type: string

Potential values: time, earnings

client_ids#

A list of client IDs separated by a comma. Use "0" if you want to filter out time entries without a client.

Type: object

{ }

description#

Matches against time entry descriptions.

Type: string

display_hours#

Determines whether to display hours as a decimal number or with minutes.

Type: string

Potential values: decimal, minutes

distinct_rates#

Type: string

Potential values: on, off

grouping#

Type: string

Potential values: users, projects

members_of_group_ids#

A list of group IDs separated by a comma. This limits provided user_ids to the members of the given groups.

Type: array

[ "group ID" ]

or_members_of_group_ids#

A list of group IDs separated by a comma. This extends provided user_ids with the members of the given groups.

Type: array

[ "GroupId" ]

order_desc#

"on" for descending, or "off" for ascending order.

Type: string

Potential values: on, off

order_field#

Type: string

Potential values: title, day1, day2, day3, day4, day5, day6, day7, week_total

project_ids#

A list of project IDs separated by a comma. Use "0" if you want to filter out time entries without a project.

Type: object

{ }

rounding#

Rounds time according to workspace settings.

Type: string

Potential values: on, off

since#

ISO 8601 date (YYYY-MM-DD) format. Defaults to today - 6 days.

Type: string

tag_ids#

A list of tag IDs separated by a comma. Use "0" if you want to filter out time entries without a tag.

Type: object

{ }

task_ids#

A list of task IDs separated by a comma. Use "0" if you want to filter out time entries without a task.

Type: object

{ }

time_entry_ids#

A list of time entry IDs separated by a comma.

Type: array

[ "GroupId" ]

user_ids#

A list of user IDs separated by a comma.

Type: array

[ "user ID" ]

without_description#

Filters out the time entries which do not have a description (literally "(no description)").

Type: boolean

get_workspace#

Get single workspace

Parameters

workspace_id (required)#

workspace ID

Type: integer

invite_users_to_workspace#

Invite users to workspace

Parameters

workspace_id (required)#

workspace ID

Type: integer

$body#

Type: object

{
  "emails" : [ "string" ]
}

list_clients#

This operation has no parameters

list_clients_for_workspace#

Get workspace clients

Parameters

workspace_id (required)#

workspace ID

Type: integer

list_groups_for_workspace#

Get workspace groups

Parameters

workspace_id (required)#

workspace ID

Type: integer

list_projects_for_workspace#

Get workspace projects

Parameters

workspace_id (required)#

workspace ID

Type: integer

list_tags_for_workspace#

Get workspace tags

Parameters

workspace_id (required)#

workspace ID

Type: integer

list_tasks_for_project#

List project tasks

Parameters

project_id (required)#

project ID

Type: integer

list_tasks_for_workspace#

Get workspace tasks

Parameters

workspace_id (required)#

workspace ID

Type: integer

list_time_entries#

Get time entries started in a specific time range. Default is last 9 days.

Parameters

end_date#

Type: string

start_date#

Type: string

list_users_for_project#

List project users

Parameters

project_id (required)#

project ID

Type: integer

list_users_for_workspace#

Get workspace users

Parameters

workspace_id (required)#

workspace ID

Type: integer

list_workspace_users#

Get workspace users. This request returns not the user objects, but the workspace_user objects (the connection between user and workspace)

Parameters

workspace_id (required)#

workspace ID

Type: integer

list_workspaces#

This operation has no parameters

reset_api_token#

This operation has no parameters

sign_up_new_user#

Parameters

$body#

Type: object

{
  "user" : {
    "image_url" : "url with the user's profile picture",
    "timezone" : "timezone user has set on the \"My profile\" page ( IANA TZ timezones )",
    "api_token" : "API token",
    "timeofday_format" : "string",
    "beginning_of_week" : "(integer 0-6, Sunday=0)",
    "jquery_date_format" : "string",
    "send_weekly_report" : "if user receives weekly report",
    "language" : "user's language",
    "default_wid" : "default workspace id",
    "store_start_and_stop_time" : "whether start and stop time are saved on time entry",
    "password" : "password at least 6 characters long",
    "at" : "timestamp of last changes",
    "new_blog_post" : { },
    "openid_enabled" : "google signin enabled",
    "jquery_timeofday_format" : "string",
    "date_format" : "string",
    "send_timer_notifications" : "email user about long-running (more than 8 hours) tasks",
    "fullname" : "Full name of user",
    "email" : "Email address",
    "sidebar_piechart" : "should a piechart be shown on the sidebar",
    "send_product_emails" : "Toggl can send newsletters over e-mail to the user",
    "current_password" : "password at least 6 characters long"
  }
}

start_time_entry#

Start a time entry

Parameters

$body#

Type: object

{
  "time_entry" : {
    "duration" : "time entry duration in seconds. 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.",
    "wid" : "workspace ID",
    "at" : "timestamp that is sent in the response, indicates the time item was last updated",
    "stop" : "time entry stop time, ISO 8601 date and time",
    "start" : "time entry start time, ISO 8601 date and time",
    "description" : "description",
    "pid" : "project ID",
    "created_with" : "the name of your client app",
    "billable" : "available for pro workspaces",
    "duronly" : "should Toggl show the start and stop time of this time entry?",
    "tid" : "task ID",
    "tags" : [ "string" ]
  }
}

stop_time_entry#

Stop a time entry

Parameters

time_entry_id (required)#

time entry ID

Type: integer

update_client#

Update a client

Parameters

client_id (required)#

client ID

Type: integer

$body#

Type: object

{
  "client" : {
    "wid" : "workspace ID",
    "notes" : "notes for the client",
    "at" : "timestamp that is sent in the response",
    "name" : "name of the client"
  }
}

update_group#

Update a group

Parameters

group_id (required)#

group ID

Type: integer

$body#

Type: object

{
  "group" : {
    "wid" : "workspace ID",
    "at" : "timestamp that is sent in the response",
    "name" : "name of the group"
  }
}

update_multiple_users_for_project#

Update multiple project users

Parameters

project_user_ids (required)#

multiple project user IDs

Type: array

[ "project user ID" ]

$body#

Type: object

{
  "project_user" : {
    "uid" : { },
    "wid" : "workspace ID",
    "at" : "timestamp that is sent in the response, indicates when the project user was last updated",
    "manager" : "admin rights for this project",
    "rate" : "hourly rate for the project user (only for pro workspaces) in the currency of the project's client or in workspace default currency.",
    "pid" : "project ID",
    "fields" : "fullname: full name of the user, who is added to the project"
  }
}

update_project#

Update project data

Parameters

project_id (required)#

project ID

Type: integer

$body#

Type: object

{
  "project" : {
    "is_private" : "whether project is accessible for only project users or for all workspace users",
    "template" : "whether the project can be used as a template",
    "color" : "id of the color selected for the project",
    "active" : "whether the project is archived or not",
    "billable" : "whether the project is billable or not, available only for pro workspaces",
    "auto_estimates" : "whether the estimated hours are automatically calculated based on task estimations or manually fixed based on the value of 'estimated_hours', premium functionality",
    "wid" : "workspace ID",
    "at" : "timestamp indicating when the project was created (UTC time), read-only",
    "rate" : "hourly rate of the project, premium functionality",
    "name" : "name of the project",
    "estimated_hours" : "if auto_estimates is true then the sum of task estimations is returned, otherwise user inserted hours, premium functionality",
    "template_id" : "id of the template project used on current project's creation",
    "cid" : "client ID"
  }
}

update_tag#

Update a tag

Parameters

tag_id (required)#

tag ID

Type: integer

$body#

Type: object

{
  "tag" : {
    "wid" : "workspace ID, where the tag will be used",
    "name" : "The name of the tag, unique in workspace"
  }
}

update_task#

Update one or more tasks

Parameters

task_id (required)#

multiple task IDs

Type: object

{ }

$body#

Type: object

{
  "task" : {
    "uid" : "user ID, to whom the task is assigned to",
    "wid" : "workspace ID",
    "at" : "timestamp that is sent in the response for PUT, indicates the time task was last updated",
    "estimated_seconds" : "estimated duration of task in seconds",
    "name" : "The name of the task",
    "active" : "whether the task is done or not",
    "pid" : "project ID for the task",
    "tracked_seconds" : "total time tracked (in seconds) for the task"
  }
}

update_time_entry#

Update a time entry (or multiple time entries)

Parameters

time_entry_id (required)#

one or more time entry IDs

Type: object

{ }

$body#

Type: object

{
  "time_entry" : {
    "duration" : "time entry duration in seconds. 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.",
    "wid" : "workspace ID",
    "at" : "timestamp that is sent in the response, indicates the time item was last updated",
    "stop" : "time entry stop time, ISO 8601 date and time",
    "start" : "time entry start time, ISO 8601 date and time",
    "description" : "description",
    "pid" : "project ID",
    "created_with" : "the name of your client app",
    "billable" : "available for pro workspaces",
    "duronly" : "should Toggl show the start and stop time of this time entry?",
    "tid" : "task ID",
    "tags" : [ "string" ]
  }
}

update_user_data#

Update user data

Parameters

$body#

Type: object

{
  "user" : {
    "image_url" : "url with the user's profile picture",
    "timezone" : "timezone user has set on the \"My profile\" page ( IANA TZ timezones )",
    "api_token" : "API token",
    "timeofday_format" : "string",
    "beginning_of_week" : "(integer 0-6, Sunday=0)",
    "jquery_date_format" : "string",
    "send_weekly_report" : "if user receives weekly report",
    "language" : "user's language",
    "default_wid" : "default workspace id",
    "store_start_and_stop_time" : "whether start and stop time are saved on time entry",
    "password" : "password at least 6 characters long",
    "at" : "timestamp of last changes",
    "new_blog_post" : { },
    "openid_enabled" : "google signin enabled",
    "jquery_timeofday_format" : "string",
    "date_format" : "string",
    "send_timer_notifications" : "email user about long-running (more than 8 hours) tasks",
    "fullname" : "Full name of user",
    "email" : "Email address",
    "sidebar_piechart" : "should a piechart be shown on the sidebar",
    "send_product_emails" : "Toggl can send newsletters over e-mail to the user",
    "current_password" : "password at least 6 characters long"
  }
}

update_user_for_project#

Update a project user

Parameters

project_user_id (required)#

project user ID

Type: integer

$body#

Type: object

{
  "project_user" : {
    "uid" : { },
    "wid" : "workspace ID",
    "at" : "timestamp that is sent in the response, indicates when the project user was last updated",
    "manager" : "admin rights for this project",
    "rate" : "hourly rate for the project user (only for pro workspaces) in the currency of the project's client or in workspace default currency.",
    "pid" : "project ID",
    "fields" : "fullname: full name of the user, who is added to the project"
  }
}

update_workspace#

Update workspace

Parameters

workspace_id (required)#

workspace ID

Type: integer

$body#

Type: object

{
  "workspace" : {
    "premium" : "If it's a pro workspace or not. Shows if someone is paying for the workspace or not",
    "at" : "timestamp that indicates the time workspace was last updated",
    "only_admins_may_create_projects" : "whether only the admins can create projects or everybody",
    "logo_url" : "URL pointing to the logo (if set, otherwise omitted)",
    "rounding_minutes" : "round up to nearest minute",
    "name" : "the name of the workspace",
    "admin" : "shows whether currently requesting user has admin access to the workspace",
    "rounding" : "type of rounding: -1 = round down, 0 = nearest, 1 = round up",
    "only_admins_see_billable_rates" : "whether only the admins can see billable rates or everybody",
    "default_hourly_rate" : "default hourly rate for workspace, won't be shown to non-admins if the only_admins_see_billable_rates flag is set to true",
    "default_currency" : "default currency for workspace"
  }
}

update_workspace_user#

Update workspace user. Only the admin flag can be changed.

Parameters

workspace_user_id (required)#

workspace user ID

Type: integer

$body#

Type: object

{
  "workspace_user" : {
    "uid" : "user id of the workspace user",
    "invite_url" : "if user has not accepted the invitation the url for accepting his/her invitation is sent when the request is made by workspace_admin",
    "admin" : "if user is workspace admin",
    "active" : "if the workspace user has accepted the invitation to this workspace",
    "id" : "workspace user id"
  }
}