Tasks

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.

Required permissions

You must be an Administrator or Manager with permission to create and edit tasks in order to interact with the /v2/tasks endpoint. Insufficient permissions will result in a 403 Forbidden status code.

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 2000 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 2000. (Default: 2000)

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":2000,
  "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=2000",
    "next":null,
    "previous":null,
    "last":"https://api.harvestapp.com/v2/tasks?page=1&per_page=2000"
  }
}

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

Still have questions? We’re happy to help!

Contact Us