Harvest API Essential Guide

What type of API does Harvest provide?

Key Points to Consider

• The most common API types discussed in the search results are REST, GraphQL, SOAP, and gRPC.

• Each API type has its own strengths and use cases:

  • REST APIs are widely adopted and flexible, using standard HTTP methods for data operations.

  • GraphQL provides more precise control over data fetching and is growing in popularity.

  • SOAP is more rigid but offers built-in security features, often used in enterprise environments.

  • gRPC is mentioned as a fast option for distributed systems.

Best Practices

• Choose an API type based on your specific project needs, existing tech stack, and developer preferences.

• Consider factors like flexibility, performance, security, and ecosystem support when selecting an API type.

• REST is often a good choice for simpler APIs or when you're new to API design.

• GraphQL can be beneficial for complex, nested data structures or highly interactive frontends.

• SOAP may be suitable for enterprise-scale distributed systems requiring detailed responses and error handling.

Does the Harvest API have webhooks?

Based on the search results provided, it appears that the official Harvest API does not have native webhook support. Here are the key points to consider:

1. The official Harvest API documentation does not mention webhooks.

2. The Harvest API is described as a REST API that allows programmatic interaction with Harvest accounts for tracking time, logging expenses, creating projects, etc.

3. The API supports various HTTP methods (GET, POST, PATCH) for making requests and retrieving data.

4. While webhooks are not natively supported, there are third-party integration options available:

   • Zapier offers integrations between Harvest and webhooks. This allows you to set up workflows where Harvest events can trigger webhooks or vice versa.

   • For example, one popular template is "Start a Harvest timer from a webhook".

5. It's worth noting that the search results primarily focus on the Harvest API itself and third-party integrations, rather than native webhook support.

In summary, the official Harvest API does not appear to have native webhook support. However, you can use third-party services like Zapier to create webhook-like functionality by integrating Harvest with webhook services. This allows you to set up automated workflows based on Harvest events or trigger Harvest actions from external webhooks.

Rate Limits and other limitations

Here are the key points about the API rate limits for the Harvest API:

General API Rate Limit

• The rate limit for general API requests is 100 requests per 15 seconds [1][2].

Reports API Rate Limit

• The rate limit for Reports API requests is 100 requests per 15 minutes [2].

Rate Limit Exceeded Response

• When the rate limit is exceeded, Harvest will send an HTTP 429 status code [1][2].
• The number of seconds until the throttle is lifted is sent via the Retry-After HTTP header [1][2].

Rate Limit Headers

Harvest provides the following headers to help track rate limit status [2]:

• X-RateLimit-Limit: The maximum number of requests allowed in the current period
• X-RateLimit-Remaining: The number of requests remaining in the current period
• X-RateLimit-Reset: The time at which the current rate limit window resets (in UTC epoch seconds)

Key Considerations

• The API throttle blocks accounts emitting more than the specified number of calls in the given time period [1].
• For batch processes or API developers still perfecting code, this throttle may be an inadvertent blocker. In such cases, wait a bit and try again [1][2].
• The throttle resets with each call, so it will lift itself in a few minutes and API calls can resume [1][2].
• You can use GET /account/rate_limit_status to programmatically query your current throttle status [1].

Best Practices

• Write your application carefully, caching when possible [2].
• In case of abuse, you may be blocked from further API access [2].
• Include a User-Agent header with your application name and contact information [2].

By adhering to these rate limits and following best practices, you can ensure smooth integration with the Harvest API while avoiding potential disruptions due to exceeding the allowed request rates.

Latest API Version

Based on the search results provided, here is the answer to your question:

The most recent version of the Harvest API is V2.

Key points to consider:

1. Harvest API V2 is a REST API that allows programmatic interaction with Harvest accounts.

2. It supports various operations like tracking time, logging expenses, creating projects, and more.

3. The API uses OAuth2 or Personal Access Tokens for authentication.

4. API requests require specific headers, including Authorization, Harvest-Account-Id, and User-Agent.

5. Responses are formatted in JSON and use standard HTTP response codes.

Code example for making a GET request to the Harvest API V2:

curl https://api.harvestapp.com/v2/tasks?page=2&per_page=10 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp ([email protected])"

Best practices:

1. Always include a User-Agent header with your application name and contact information.

2. Use appropriate HTTP methods (GET, POST, PATCH) depending on the operation.

3. When submitting data, use either JSON format or form data, and specify the Content-Type header accordingly.

4. Handle rate limiting and respect the API's usage limits.

5. Securely store and manage your API access tokens.

It's important to note that while the search results also mention a Harvest API from Greenhouse, this appears to be a different product. The question specifically asks about the Harvest API, which refers to the time tracking and project management tool by Harvest, not the recruiting tool by Greenhouse.

How to get a Harvest developer account and API Keys?

To get a developer account for Harvest and create an API integration, you'll need to follow these steps:

1. Create a Harvest account

If you don't already have one, sign up for a Harvest account at https://www.getharvest.com/.

2. Access the Developer tools

Once logged in to your Harvest account:

1. Go to the Harvest ID website (https://id.getharvest.com/)
2. Click on the "Developers" link in the top navigation.

3. Create a Personal Access Token

For quick API access and testing:

1. In the Developers section, look for the option to create a Personal Access Token.
2. Click to generate a new token.
3. Give your token a descriptive name.
4. Copy and securely store the generated token - you won't be able to see it again.

4. Set up an OAuth2 Application (for integrations used by others)

If you're building an integration for other users:

1. In the Developers section, look for the option to register a new OAuth2 Application.
2. Provide the required information:
   • Name of your application
   • Redirect URL (where users will be sent after authentication)
   • Whether it's a multi-account or single-account integration
   • Which products you need access to (Harvest, Forecast, or both)

5. Manage API Permissions

For both Personal Access Tokens and OAuth2 Applications:

1. Review the permissions granted to your token/application.
2. Adjust permissions as needed to ensure you have access to the required endpoints.

What can you do with the Harvest API?

Based on the search results, here is a list of data models you can interact with using the Harvest API, along with what is possible for each:

1. Client

   • Contains details about customers in your Harvest account
   • Possible actions: Create, read, update, delete client information

2. Client Contacts

   • Contains details of contacts associated with client accounts
   • Possible actions: Add, view, edit, remove contact information

3. Invoices

   • Contains details about the sale of products and services
   • Possible actions: Create, view, update, delete invoices; manage charges, adjustments, payments, discounts, and taxes

4. Invoice Item Categories

   • Contains details of groups associated with invoice items
   • Possible actions: Create, view, update, delete categories

5. Estimates

   • Contains details of proposals for financial transactions sent to clients
   • Possible actions: Create, view, update, delete estimates

6. Estimate Item Categories

   • Contains details of categories associated with estimated items
   • Possible actions: Create, view, update, delete categories

7. Expenses

   • Contains details of amounts spent by clients for buying services or products
   • Possible actions: Create, view, update, delete expenses

8. Expense Categories

   • Contains details of groups created to track spending and organize expenses
   • Possible actions: Create, view, update, delete categories

9. Projects

   • Contains details of all tasks associated with clients
   • Possible actions: Create, view, update, delete projects

10. Project User Assignments

    • Contains details of users associated with each project
    • Possible actions: Assign, view, update, remove user assignments

11. Project Task Assignments

    • Contains details of task assignments for each user associated with projects
    • Possible actions: Assign, view, update, remove task assignments

12. Roles

    • Contains details of privileges and profiles specifying user permissions
    • Possible actions: Create, view, update, delete roles

13. Tasks

    • Contains list of different operations performed within projects
    • Possible actions: Create, view, update, delete tasks

14. Time Entries

    • Contains details of time entries submitted by users to record time spent on tasks
    • Possible actions: Create, view, update, delete time entries

15. Users

    • Contains details of all users with access to the Harvest account
    • Possible actions: Create, view, update, delete user accounts

For each of these data models, you can typically perform CRUD (Create, Read, Update, Delete) operations using the Harvest API. The API allows you to interact with these models programmatically, enabling you to automate various tasks and integrate Harvest data with other systems.

Additionally, the Harvest API provides access to various reports, including:

• Expense Reports
• Uninvoiced Report
• Time Reports
• Project Budget Report

When working with the API, keep in mind the following:

• The API uses REST principles and returns JSON-formatted responses
• Authentication is required using OAuth2 or Personal Access Tokens
• There are rate limits in place (100 API calls per 15 minutes)
• Pagination is used, with each API response fetching up to 100 records per page