Today, we’re excited to announce the launch of a new version of the Harvest API!

Our API has a long history. It was first introduced in November 2006, with a limited set of time tracking functionality. A year later, we added support for managing clients, projects, tasks, and users. In 2009, invoicing and expenses made their API debut. But the last major update to the Harvest API was made in October 2011.

The new version we’re releasing today is faster, more consistent, and more complete than our existing API (v1), and gives us a solid foundation to expose even more functionality in the future.

What’s New in API v2?

API v2 is a JSON API that allows you to interact with your Harvest account programmatically. You can track time, log expenses, create projects, and more.

Security: Authentication is even more secure. Starting with API v2, we’re replacing Basic Authentication with Personal Access Tokens via Harvest ID. To get one, sign in to your Harvest ID account and click on the Developers link in the top navigation. From there, you can create a new personal access token to authenticate yourself! You can add or destroy these as needed, so you have finer control over your tokens.

Pagination: All collection responses will be paginated so that they’re faster to generate and deliver. You’ll have the freedom to choose how many items you’d like to receive per page. We also include links to the first, last, previous, and next page.

Consistency: Consistency was a major goal for this version. We now return more appropriate HTTP response codes and use consistently coded timezone and currency codes.

Fewer Requests: We’re now nesting associated data in our responses. This means you no longer need to submit multiple requests to tell the whole story about your data. For example, in API v1, if you wanted to display a single expense along with the names of the client, project, and expense category you’d need to make 4 requests:

  1. A request to get the expense data.
  2. Another request to get the client’s name.
  3. Yet another request to get the project’s name.
  4. A final request to get the name of the expense category.

With API v2, only the first request is needed as we include the project, client, and expense category names in the response!

Estimates: Good news for those of you who use estimates: API v2 includes support for managing estimates. That simply wasn’t possible in v1.

Invoice Line Items: In API v1, invoice line items were submitted as a CSV string. Any time you wanted to update an individual line item, you’d have to re-submit ALL of them. With the new API you can create, update, and delete individual line items as needed.

External References: External references are links added to time entry notes that go to a specific part of an integration (such as a Trello card or a Basecamp to-do) when time is tracked directly from that integration. These were only returned in certain parts of API v1 and weren’t officially supported or documented. In API v2, all time entry endpoints will include an external reference if one exists.

Future Improvements: There are some things that we weren’t able to tackle before today’s launch. For example, we wanted to add API access to some of Harvest reports. We haven’t decided on exactly which reports will make it into the API, but we wanted to let you know that reporting is on the roadmap!

What about API v1?

With the launch of API v2, we’re officially deprecating API v1. We strongly recommend that new integrations with Harvest use API v2.

For those of you that are already using our API v1, don’t worry, we’ve got you covered! We’ll continue supporting API v1 until January 1st, 2019. We hope that gives you enough time to switch over to API v2.

Getting Started with API v2

We’ve worked hard to add comprehensive documentation, including example commands and responses, to make API v2  even easier to use. To get started, head over to the documentation!

We look forward to seeing what you build with API v2. Let us know if you have any feedback!