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	DEPRECATED 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)

This endpoint supports cursor-based pagination and therefore deprecates the page parameter. For more information, visit the pagination guide.

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

Welcome to the Harvest API v2 Help Center

The task object

Required permissions

List all tasks

Retrieve a task

Create a task

Update a task

Delete a task

Still have questions? We’re happy to help!