General Information

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.

Authorization

All requests to the Harvest API are made on the behalf of an actual user (see the OAuth 2.0 Authentication section for detail on authenticating your requests).

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)

Still have questions? We’re happy to help!

Contact Us