Introduction - The Harvest API

General

Harvest provides two API interfaces, serving two distinct roles. If you need to access and manipulate your daily timesheet, use the Time Tracking API. Harvest for Mac uses this API, as do many third-party integrations.

Furthermore, our API can be used to edit or import projects, tasks, and users, and generally integrate with a new or existing back-office setup.

Please remember to write your application carefully, caching when possible.

In case of abuse you may be blocked, disallowing further API access. As an act of courtesy, please provide User-Agent strings denoting your application.

Troubleshooting

If you’re running into problems with a specific implementation, please try the request in a client like Postman to narrow down where things are going wrong.

If you still need help, drop us a line. Please make sure to include the full request you’re having trouble with, including any headers—we need these to do any troubleshooting on your behalf.

In most cases, the omission of the Content-Type and Accept headers are the root cause of unexpected errors from the API.

Share Your Creation

If you’ve built something interesting with the Harvest API or the Harvest Platform, share the love! Created a library or other cool connector that others might find useful? Add it to our Community Creations and Hacks page, and join the ranks of other great projects our users have made!

If it’s a connector for another app, ping us — we may be able to list it on our Add-ons page.

Authorization

All requests to the Harvest API are made on the behalf of an actual user (see the HTTP Basic Authentication or OAuth 2.0 Authentication sections for detail on authenticating your requests). You can use a regular account for requests against the Time Tracking API, but for private integrations accessing the Extended REST API we recommend creating a special admin user. Harvest will check your role on each request, and actions that are unavailable to you on the UI will be unavailable over the API as well.

Administrators can access all API resources, while regular users are limited to their own timesheets. Project Managers can access projects they manage in addition to their own timesheets.

Supported Data Formats

The Harvest API supports both XML and JSON data formats. For an XML request, send application/xml in the Accept and Content-Type headers. Send application/json for JSON responses.

Throttle Limit - HTTP 503

We have an API throttle that blocks accounts emitting more than 100 calls per 15 seconds. We reserve the right to tune the limitations, but they are always set high enough to allow a well-behaving interactive program to do its job. For batch processes and API developers who still need to perfect their code, this throttle may be an inadvertent blocker. Just wait a bit, and try again. Since the throttle is reset with each call, the throttle will lift itself in a few minutes and API calls may resume.

When the rate limit is exceeded Harvest will send an HTTP 503 status code. The number of seconds until the throttle is lifted is sent via the Retry-After HTTP header, as specified in RFC 2616.

You can use GET /account/rate_limit_status to programmatically query your current throttle status.

Notational Conventions

Throughout our documentation you’ll find the following set of notational conventions: {expression} Should be substituted with the value of the expression.

For example, /{project_id} should be replaced with /12345 (assuming your project_id is 12345)