Harvest 2.5.4
See the version list below for details.
dotnet add package Harvest --version 2.5.4
NuGet\Install-Package Harvest -Version 2.5.4
<PackageReference Include="Harvest" Version="2.5.4" />
<PackageVersion Include="Harvest" Version="2.5.4" />
<PackageReference Include="Harvest" />
paket add Harvest --version 2.5.4
#r "nuget: Harvest, 2.5.4"
#:package Harvest@2.5.4
#addin nuget:?package=Harvest&version=2.5.4
#tool nuget:?package=Harvest&version=2.5.4
Harvest.Api
A .NET wrapper for the Harvest time tracking API.
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
CancellationTokenas its last parameter. - List methods are named
ListAsync(ListMineAsyncfor the current user's project assignments) and take aListOptionsobject (TimeEntryListOptions,ProjectListOptions) in place of the optionalupdatedSince,page,perPageand filter parameters. Passnullfor none.TimeEntries.PatchAsyncis nowUpdateAsync. - Dates are
DateOnly(SpentDate,StartsOn,From, ...);UpdatedSinceis aDateTimeOffsetsent 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/Deletemethods were removed. - Errors raise
HarvestApiException(still a RefitApiException).
// 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 | Versions 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. |
-
net10.0
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.13)
- Refit (>= 16.3.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.