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