Projects
The project object
Attribute | Type | Description |
---|---|---|
id |
integer | Unique ID for the project. |
client |
object | An object containing the project’s client id, name, and currency. |
name |
string | Unique name for the project. |
code |
string | The code associated with the project. |
is_active |
boolean | Whether the project is active or archived. |
is_billable |
boolean | Whether the project is billable or not. |
is_fixed_fee |
boolean | Whether the project is a fixed-fee project or not. |
bill_by |
string | The method by which the project is invoiced. |
hourly_rate |
decimal | Rate for projects billed by Project Hourly Rate. |
budget |
decimal | The budget in hours for the project when budgeting by time. |
budget_by |
string | The method by which the project is budgeted. |
budget_is_monthly |
boolean | Option to have the budget reset every month. |
notify_when_over_budget |
boolean | Whether Project Managers should be notified when the project goes over budget. |
over_budget_notification_percentage |
decimal | Percentage value used to trigger over budget email alerts. |
over_budget_notification_date |
date | Date of last over budget notification. If none have been sent, this will be null. |
show_budget_to_all |
boolean | Option to show project budget to all employees. Does not apply to Total Project Fee projects. |
cost_budget |
decimal | The monetary budget for the project when budgeting by money. |
cost_budget_include_expenses |
boolean | Option for budget of Total Project Fees projects to include tracked expenses. |
fee |
decimal | The amount you plan to invoice for the project. Only used by fixed-fee projects. |
notes |
string | Project notes. |
starts_on |
date | Date the project was started. |
ends_on |
date | Date the project will end. |
created_at |
datetime | Date and time the project was created. |
updated_at |
datetime | Date and time the project was last updated. |
Required permissions
You must be an Administrator or Manager with managed projects in order to interact with the /v2/projects
endpoint. Insufficient permissions will result in a 403 Forbidden
status code.
List all projects
Returns a list of your projects. The projects are returned sorted by creation date, with the most recently created projects appearing first.
The response contains an object with a projects
property that contains an array of up to per_page
projects. Each entry in the array is a separate project object. If no more projects are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your projects.
GET /v2/projects
Parameter | Type | Description |
---|---|---|
is_active |
boolean | Pass true to only return active projects and false to return inactive projects. |
client_id |
integer | Only return projects belonging to the client with the given ID. |
updated_since |
datetime | Only return projects 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/projects" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
Retrieve a project
Retrieves the project with the given ID. Returns a project object and a 200 OK
response code if a valid identifier was provided.
GET /v2/projects/{PROJECT_ID}
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308069" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
Create a project
Creates a new project object. Returns a project object and a 201 Created
response code if the call succeeded.
POST /v2/projects
Parameter | Type | Required | Description |
---|---|---|---|
client_id |
integer | required | The ID of the client to associate this project with. |
name |
string | required | The name of the project. |
code |
string | optional | The code associated with the project. |
is_active |
boolean | optional | Whether the project is active or archived. Defaults to true . |
is_billable |
boolean | required | Whether the project is billable or not. |
is_fixed_fee |
boolean | optional | Whether the project is a fixed-fee project or not. |
bill_by |
string | required | The method by which the project is invoiced. Options: Project , Tasks , People , or none . |
hourly_rate |
decimal | optional | Rate for projects billed by Project Hourly Rate. |
budget |
decimal | optional | The budget in hours for the project when budgeting by time. |
budget_by |
string | required | The method by which the project is budgeted. Options: project (Hours Per Project), project_cost (Total Project Fees), task (Hours Per Task), task_fees (Fees Per Task), person (Hours Per Person), none (No Budget). |
budget_is_monthly |
boolean | optional | Option to have the budget reset every month. Defaults to false . |
notify_when_over_budget |
boolean | optional | Whether Project Managers should be notified when the project goes over budget. Defaults to false . |
over_budget_notification_percentage |
decimal | optional | Percentage value used to trigger over budget email alerts. Example: use 10.0 for 10.0%. |
show_budget_to_all |
boolean | optional | Option to show project budget to all employees. Does not apply to Total Project Fee projects. Defaults to false . |
cost_budget |
decimal | optional | The monetary budget for the project when budgeting by money. |
cost_budget_include_expenses |
boolean | optional | Option for budget of Total Project Fees projects to include tracked expenses. Defaults to false . |
fee |
decimal | optional | The amount you plan to invoice for the project. Only used by fixed-fee projects. |
notes |
string | optional | Project notes. |
starts_on |
date | optional | Date the project was started. |
ends_on |
date | optional | Date the project will end. |
Example Request:
curl "https://api.harvestapp.com/v2/projects" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X POST \
-H "Content-Type: application/json" \
-d '{"client_id":5735776,"name":"Your New Project","is_billable":true,"bill_by":"Project","hourly_rate":100.0,"budget_by":"project","budget":10000}'
Example Response:
Update a project
Updates the specific project by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a project object and a 200 OK
response code if the call succeeded.
PATCH /v2/projects/{PROJECT_ID}
Parameter | Type | Description |
---|---|---|
client_id |
integer | The ID of the client to associate this project with. |
name |
string | The name of the project. |
code |
string | The code associated with the project. |
is_active |
boolean | Whether the project is active or archived. Defaults to true . |
is_billable |
boolean | Whether the project is billable or not. |
is_fixed_fee |
boolean | Whether the project is a fixed-fee project or not. |
bill_by |
string | The method by which the project is invoiced. Options: Project , Tasks , People , or none . |
hourly_rate |
decimal | Rate for projects billed by Project Hourly Rate. |
budget |
decimal | The budget in hours for the project when budgeting by time. |
budget_by |
string | The method by which the project is budgeted. Options: project (Hours Per Project), project_cost (Total Project Fees), task (Hours Per Task), task_fees (Fees Per Task), person (Hours Per Person), none (No Budget). |
budget_is_monthly |
boolean | Option to have the budget reset every month. Defaults to false . |
notify_when_over_budget |
boolean | Whether Project Managers should be notified when the project goes over budget. Defaults to false . |
over_budget_notification_percentage |
decimal | Percentage value used to trigger over budget email alerts. Example: use 10.0 for 10.0%. |
show_budget_to_all |
boolean | Option to show project budget to all employees. Does not apply to Total Project Fee projects. Defaults to false . |
cost_budget |
decimal | The monetary budget for the project when budgeting by money. |
cost_budget_include_expenses |
boolean | Option for budget of Total Project Fees projects to include tracked expenses. Defaults to false . |
fee |
decimal | The amount you plan to invoice for the project. Only used by fixed-fee projects. |
notes |
string | Project notes. |
starts_on |
date | Date the project was started. |
ends_on |
date | Date the project will end. |
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308112" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"name":"New project name"}'
Example Response:
Delete a project
Deletes a project and any time entries or expenses tracked to it. However, invoices associated with the project will not be deleted. If you don’t want the project’s time entries and expenses to be deleted, you should archive the project instead.
DELETE /v2/projects/{PROJECT_ID}
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308112" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X DELETE