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

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

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"
  }
}