Admin permissions required.

The task object

Attribute Type Description
id integer Unique ID for the task.
name string The name of the task.
billable_by_default boolean Used in determining whether default tasks should be marked billable when creating a new project.
default_hourly_rate decimal The hourly rate to use for this task when it is added to a project.
is_default boolean Whether this task should be automatically added to future projects.
is_active boolean Whether this task is active or archived.
created_at datetime Date and time the task was created.
updated_at datetime Date and time the task was last updated.

List all tasks

Returns a list of your tasks. The tasks are returned sorted by creation date, with the most recently created tasks appearing first.

The response contains an object with a tasks property that contains an array of up to per_page tasks. Each entry in the array is a separate task object. If no more tasks are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your tasks.

GET /v2/tasks
Parameter Type Description
is_active boolean Pass true to only return active tasks and false to return inactive tasks.
updated_since datetime Only return tasks that have been updated since the given date and time.
page integer The page number to use in pagination. For instance, if you make a list request and receive 100 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 100. (Default: 100)

Example Request:

curl "https://api.harvestapp.com/v2/tasks" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)"

Example Response:

{
"tasks":[
{
"id":8083800,
"name":"Business Development",
"billable_by_default":false,
"default_hourly_rate":0.0,
"is_default":false,
"is_active":true,
"created_at":"2017-06-26T22:08:25Z",
"updated_at":"2017-06-26T22:08:25Z"
},
{
"id":8083369,
"name":"Research",
"billable_by_default":false,
"default_hourly_rate":0.0,
"is_default":true,
"is_active":true,
"created_at":"2017-06-26T20:41:00Z",
"updated_at":"2017-06-26T21:53:34Z"
},
{
"id":8083368,
"name":"Project Management",
"billable_by_default":true,
"default_hourly_rate":100.0,
"is_default":true,
"is_active":true,
"created_at":"2017-06-26T20:41:00Z",
"updated_at":"2017-06-26T21:14:10Z"
},
{
"id":8083366,
"name":"Programming",
"billable_by_default":true,
"default_hourly_rate":100.0,
"is_default":true,
"is_active":true,
"created_at":"2017-06-26T20:41:00Z",
"updated_at":"2017-06-26T21:14:07Z"
},
{
"id":8083365,
"name":"Graphic Design",
"billable_by_default":true,
"default_hourly_rate":100.0,
"is_default":true,
"is_active":true,
"created_at":"2017-06-26T20:41:00Z",
"updated_at":"2017-06-26T21:14:02Z"
}
],
"per_page":100,
"total_pages":1,
"total_entries":5,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/tasks?page=1&per_page=100",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/tasks?page=1&per_page=100"
}
}

Retrieve a task

Retrieves the task with the given ID. Returns a task object and a 200 OK response code if a valid identifier was provided.

GET /v2/tasks/{TASK_ID}

Example Request:

curl "https://api.harvestapp.com/v2/tasks/8083800" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)"

Example Response:

{
"id":8083800,
"name":"Business Development",
"billable_by_default":false,
"default_hourly_rate":0.0,
"is_default":false,
"is_active":true,
"created_at":"2017-06-26T22:08:25Z",
"updated_at":"2017-06-26T22:08:25Z"
}

Create a task

Creates a new task object. Returns a task object and a 201 Created response code if the call succeeded.

POST /v2/tasks
Parameter Type Required Description
name string required The name of the task.
billable_by_default boolean optional Used in determining whether default tasks should be marked billable when creating a new project. Defaults to true.
default_hourly_rate decimal optional The default hourly rate to use for this task when it is added to a project. Defaults to 0.
is_default boolean optional Whether this task should be automatically added to future projects. Defaults to false.
is_active boolean optional Whether this task is active or archived. Defaults to true.

Example Request:

curl "https://api.harvestapp.com/v2/tasks" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"New Task Name","hourly_rate":"120.0"}'

Example Response:

{
"id":8083782,
"name":"New Task Name",
"billable_by_default":true,
"default_hourly_rate":0,
"is_default":false,
"is_active":true,
"created_at":"2017-06-26T22:04:31Z",
"updated_at":"2017-06-26T22:04:31Z"
}

Update a task

Updates the specific task by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a task object and a 200 OK response code if the call succeeded.

PATCH /v2/tasks/{TASK_ID}
Parameter Type Description
name string The name of the task.
billable_by_default boolean Used in determining whether default tasks should be marked billable when creating a new project.
default_hourly_rate decimal The default hourly rate to use for this task when it is added to a project.
is_default boolean Whether this task should be automatically added to future projects.
is_active boolean Whether this task is active or archived.

Example Request:

curl "https://api.harvestapp.com/v2/tasks/8083782" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"is_default":"true"}'

Example Response:

{
"id":8083782,
"name":"New Task Name",
"billable_by_default":true,
"default_hourly_rate":0,
"is_default":true,
"is_active":true,
"created_at":"2017-06-26T22:04:31Z",
"updated_at":"2017-06-26T22:04:54Z"
}

Delete a task

Delete a task. Deleting a task is only possible if it has no time entries associated with it. Returns a 200 OK response code if the call succeeded.

DELETE /v2/tasks/{TASK_ID}

Example Request:

curl "https://api.harvestapp.com/v2/tasks/8083782" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X DELETE