Harvest 2.5.8

There is a newer version of this package available.
See the version list below for details.
dotnet add package Harvest --version 2.5.8
                    
NuGet\Install-Package Harvest -Version 2.5.8
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Harvest" Version="2.5.8" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Harvest" Version="2.5.8" />
                    
Directory.Packages.props
<PackageReference Include="Harvest" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Harvest --version 2.5.8
                    
#r "nuget: Harvest, 2.5.8"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Harvest@2.5.8
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Harvest&version=2.5.8
                    
Install as a Cake Addin
#tool nuget:?package=Harvest&version=2.5.8
                    
Install as a Cake Tool

Harvest.Api

A .NET wrapper for the Harvest time tracking API.

NuGet License: MIT CI Codacy Badge Codacy Coverage

Installation

Install the package via NuGet:

dotnet add package Harvest

Or via the Package Manager Console:

Install-Package Harvest

Getting Started

Authentication

To use the Harvest API, you'll need:

  • An Account ID - Found in Harvest under Settings > Choose Integrations > Authorized OAuth2 API Clients
  • An Access Token - Create a Personal Access Token in the same location

Basic Usage

using Harvest;

// Create a client
using var harvestClient = new HarvestClient(new HarvestClientOptions
{
    AccountId = 123456,
    AccessToken = "your-access-token",
    // Harvest asks every request to name the application and a contact; this is optional and defaults to
    // "Harvest.Api/<version> (+https://github.com/panoramicdata/Harvest.Api)".
    UserAgent = "MyApp (ops@example.com)"
});

// Every method takes a CancellationToken as its last argument
var cancellationToken = CancellationToken.None;

// Get current user
var me = await harvestClient.Users.GetMeAsync(cancellationToken);
Console.WriteLine($"Hello, {me.FirstName}!");

// List clients (null options: Harvest's defaults, first page of up to 2000)
var clientsContainer = await harvestClient.Clients.ListAsync(null, cancellationToken);
foreach (var client in clientsContainer.Clients)
{
    Console.WriteLine($"Client: {client.Name}");
}

// List one client's active projects updated in the last week
var projectsContainer = await harvestClient.Projects.ListAsync(
    new ProjectListOptions { ClientId = 5735776, IsActive = true, UpdatedSince = DateTimeOffset.UtcNow.AddDays(-7) },
    cancellationToken);

// List this week's time entries for one project
var timeEntries = await harvestClient.TimeEntries.ListAsync(
    new TimeEntryListOptions { ProjectId = 12345678, From = new DateOnly(2025, 1, 13), To = new DateOnly(2025, 1, 19) },
    cancellationToken);

// Create a time entry
var timeEntry = await harvestClient.TimeEntries.CreateAsync(new TimeEntryCreationDto
{
    ProjectId = 12345678,
    TaskId = 87654321,
    SpentDate = new DateOnly(2025, 1, 15),
    Hours = 2.5m,
    Notes = "Working on feature X"
}, cancellationToken);

Paging

Each list call returns one page. Harvest prefers cursor paging: when the previous page's Links.NextCursor is set, pass it as ListOptions.Cursor; otherwise pass NextPage as ListOptions.Page. Stop when both are null.

var all = new List<TimeEntry>();
var options = new TimeEntryListOptions();
while (true)
{
    var page = await harvestClient.TimeEntries.ListAsync(options, cancellationToken);
    all.AddRange(page.TimeEntries);
    var cursor = page.Links?.NextCursor;
    var nextPage = cursor is null ? page.NextPage : null;
    if (cursor is null && nextPage is null)
    {
        break;
    }

    options = new TimeEntryListOptions { Cursor = cursor, Page = nextPage };
}

Errors and retries

A non-success response raises HarvestApiException, a Refit ApiException whose Message and ErrorMessage carry Harvest's own error text (StatusCode, Content and the response headers are available too). Throttled requests (HTTP 429, honouring Retry-After) and transient server errors are retried first, up to HarvestClientOptions.MaxRetries times (3 by default; set 0 to disable).

Upgrading from 2.4 and earlier

The major version of this package follows Harvest's API version (v2), so breaking changes ship in minor releases. Version 2.5 makes breaking changes:

  • Every method takes a required CancellationToken as its last parameter.
  • List methods are named ListAsync (ListMineAsync for the current user's project assignments) and take a ListOptions object (TimeEntryListOptions, ProjectListOptions) in place of the optional updatedSince, page, perPage and filter parameters. Pass null for none. TimeEntries.PatchAsync is now UpdateAsync.
  • Dates are DateOnly (SpentDate, StartsOn, From, ...); UpdatedSince is a DateTimeOffset sent in ISO 8601.
  • Nested objects are reference types (UserReference, ClientReference, ProjectReference, TaskReference, InvoiceReference), and models follow the current Harvest v2 field lists (v1-only fields were removed).
  • Optional fields of creation DTOs are nullable and omitted when unset, so Harvest applies its own defaults.
  • The undocumented user project assignment Get/Create/Update/Delete methods were removed.
  • Errors raise HarvestApiException (still a Refit ApiException).
// 2.4 and earlier
await harvestClient.Clients.ListAllAsync(page: 2, perPage: 50);
// 2.5 and later
await harvestClient.Clients.ListAsync(new ListOptions { Page = 2, PerPage = 50 }, cancellationToken);

Available APIs

The HarvestClient (and IHarvestClient) provides access to the following API endpoints:

Property Description
Accounts List the accounts the access token can reach (Harvest ID)
BillableRates List and create users' billable rates
Clients Manage clients
Companies Get and update company settings
Contacts Manage client contacts
CostRates List and create users' cost rates
EstimateItemCategories Manage estimate item categories
EstimateMessages Send estimate messages and mark estimates sent, accepted, declined or re-opened
Estimates Manage estimates and their line items
ExpenseCategories Manage expense categories
Expenses Manage expenses and their receipts
InvoiceItemCategories Manage invoice item categories
InvoiceMessages Send invoices and mark them sent, closed, re-opened or draft
InvoicePayments Record and delete invoice payments
Invoices Manage invoices and their line items
ProjectTaskAssignments Manage task assignments for projects
ProjectUserAssignments Manage user assignments for projects
Projects Manage projects
PtoAllocations PTO per-user allocations (see PTO; 403 for accounts without the PTO API)
PtoAssignments PTO holiday calendar and work schedule assignments (see PTO; 403 for accounts without the PTO API)
PtoBalances PTO time off balances (see PTO; 403 for accounts without the PTO API)
PtoHolidayCalendars PTO holiday calendars and entries (see PTO; 403 for accounts without the PTO API)
PtoRequests PTO time off requests: create, approve, decline, cancel (see PTO; 403 for accounts without the PTO API)
PtoTypes PTO time off policies (see PTO; 403 for accounts without the PTO API)
PtoWorkSchedules PTO work schedules (see PTO; 403 for accounts without the PTO API)
Reports Time, expense, uninvoiced and project budget reports (100 requests per 15 minutes)
Roles Manage roles
Tasks Manage tasks
Teammates List and replace managers' teammates
TimeEntries Create, update, delete, stop and restart time entries
UserProjectAssignments List project assignments for users
Users Manage users

Each resource is documented, with its method signatures, in documentation/. Contributors adding resources should follow docs/IMPLEMENTING.md.

Coverage

Every operation in the Harvest API v2 reference is implemented, including the gradually rolled-out PTO API and the Harvest ID accounts endpoint: 32 APIs with 149 public methods between them. Unit tests pin every request and response, with 100% line and branch coverage of the library. Verification of the newer resources against the live Harvest API is still pending; please report any field Harvest sends differently from its documentation.

Proxy Support

If you need to route requests through a proxy:

var harvestClient = new HarvestClient(new HarvestClientOptions
{
    AccountId = 123456,
    AccessToken = "your-access-token",
    ProxyUrl = "http://proxy.example.com:8080"
});

To customise the transport further, pass your own HttpMessageHandler as the second constructor argument.

API Documentation

For full API documentation, refer to the official Harvest API v2 Documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.

Acknowledgments

This library was forked from projects by:

  • Joel Potter
  • Data Research Group
  • Paul Irwin

Maintained by Panoramic Data Limited.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.5.11 51 11/13/2026
2.5.10 62 11/11/2026
2.5.8 62 11/9/2026
2.5.4 82 10/17/2026
2.5.3 75 10/15/2026
2.4.7-beta 284 12/18/2025
2.3.0 3,080 6/20/2018
2.2.0 1,270 5/23/2018
2.1.0 1,526 3/17/2018