Introduction to the Harvest API

Harvest provides two API interfaces, serving two distinct roles. If you need to access and manipulate your daily timesheet the Timetracking API fits the bill. Notable uses of the Timetracking API are the widgets we provide for PC and Mac as well as other third party timesheet software integrations.

If you need to access and edit your projects, clients, users and tasks the Extended REST API is your choice (see navigation on right-side). You can use this to mass import your existing projects setup, add users and generally integrate with your existing back-office setup.

Examples

To help you get started with the Harvest API, we have created a sample Ruby script which interacts with the API, from authentication to basic API actions. Download harvest-sample.rb for more information.

API Authentication

Harvest authentication is performed via HTTP (only "Basic" is supported), and you'll need to transmit your username and password along with your request. HTTPS must be used if interacting with an account with SSL support.

To interact with Harvest you'll need to send and interpret simple XML over HTTP. You must encode the preferred format inside Content-Type and Accept headers. A simple example with curl:

$curl http://subdomain.harvestapp.com/daily -H 'Accept: application/xml' \
  -H 'Content-Type: application/xml' -u user@email.com:password

Harvest will check your role on each request, actions that are invisible to you on the UI will return HTTP 404 on the API as well. Generally admins can access all, regular users can see their own Timesheet and PMs the projects they manage. You can use a regular account for the Timetracking API, but to interact with the Extended REST API it is recommended to have a special user with admin role.

All successful requests return HTTP response codes in the 2xx range (e.g. 200, 201, etc.). Other response codes indicate a failed request, in which case an error message may be provided.

For the Timetracking API you can send and receive JSON also. Just have to send 'application/json' in the Content-Type and Accept headers. JSON is useful for Javascript based clients (e.g. Mac or PC widgets). All examples in this documentation assume XML input and output, however JSON output follows similar structure to the XML documented.

Firefox Users: Consider using the RestTest plugin to help you make requests to and see responses from the Harvest API. You need to set up your request headers with the following:

Accept: application/xml
Content-Type: application/xml
Authorization: Basic (insert your authentication string here)

You can get your authentication string by encoding, for example, with Ruby:

Base64.encode64("my@email.com:password").delete("\r\n")

Please write your application carefully, caching as much as possible. In case of abuse you may be blocked, disallowing further API access. As an act of courtesy you should also provide User-Agent strings denoting your application.

API throttle limit - HTTP 503

We have an API throttle that blocks accounts emitting more than 40 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 and make no API calls (the throttle is reset with each call). The throttle will lift itself in 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.

Notational conventions

Throughout our documentation you'll find the following set of notational conventions:

• #{expression}: Should be substituted with the value of the expression. Example: /#{project_id} should be replaced with /12345 (assuming your project_id = 12345)
• ...: For brevity we have skipped repetitive parts of the response.
• <!-- Comment -->: Optional comment in the response added for clarity. The actual response will not contain comments.

Have more questions? Please email us at: support@getharvest.com.