API reference

A REST API with familiar conventions — if you have tooling built against Harvest v2, it mostly ports by changing the base URL and token. Machine-readable spec: /api/v1/openapi.json (imports straight into Postman).

Authentication

Send Authorization: Bearer <token>. Two token kinds, both created on the in-app Developer page:

Endpoints marked manager+ or admin refuse lower-grade personal tokens — money (rates, invoices, reports) never reaches member tokens.

Conventions

Company

The authenticated workspace.

GET/v1/companyRetrieve the company

Time entries

Tracked time. Member-grade personal tokens see and modify only their own entries; submitted or approved weeks are locked.

GET/v1/time_entriesList time entries
PARAMETERS
  • from — Only entries on/after this date (YYYY-MM-DD)
  • to — Only entries on/before this date
  • user_id — Filter to one member
  • client_id — Filter by client
  • project_id — Filter by project
  • task_id — Filter by task
  • billable — true/false
  • is_billed — true = already invoiced
  • is_running — true = timer currently running
  • approval_status — unsubmitted, submitted, or approved
  • external_reference_id — Match an external reference
  • updated_since — ISO 8601 datetime
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)
POST/v1/time_entriesCreate a time entry

Personal tokens log as their owner. Weeks already submitted for approval refuse new time (422).

BODY
  • project_id — UUID, required
  • task_id — UUID, required
  • spent_date — YYYY-MM-DD, required
  • hours — Decimal hours (rounded per org policy)
  • notes — Entry notes
  • billable — Defaults true
  • external_reference.id — External system reference (e.g. issue key)
  • user_id — Required with an organization key; ignored for personal tokens
GET/v1/time_entries/{id}Retrieve a time entry
PARAMETERS
  • id (required) — The time entry id (UUID)
PATCH/v1/time_entries/{id}Update a time entry

Locked (approved/invoiced) and submitted entries return 422.

PARAMETERS
  • id (required) — The time entry id (UUID)
BODY
  • project_id — UUID
  • task_id — UUID
  • spent_date — YYYY-MM-DD (target week must be open)
  • hours — Decimal hours
  • notes — Entry notes
  • billable — true/false
  • external_reference.id — Set or replace the external reference
DELETE/v1/time_entries/{id}Delete a time entry
PARAMETERS
  • id (required) — The time entry id (UUID)
PATCH/v1/time_entries/{id}/restartRestart the timer on an entry · personal token

Personal tokens only — timers belong to a person. Stops any other running timer.

PARAMETERS
  • id (required) — The time entry id (UUID)
PATCH/v1/time_entries/{id}/stopStop the running timer on an entry
PARAMETERS
  • id (required) — The time entry id (UUID)
DELETE/v1/time_entries/{id}/external_referenceRemove an entry’s external reference
PARAMETERS
  • id (required) — The time entry id (UUID)

Clients

Clients and their currencies.

GET/v1/clientsList clients
PARAMETERS
  • name — Case-insensitive name fragment
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)
POST/v1/clientsCreate a client · manager+
BODY
  • name — Required
  • currency — 3-letter code
  • address — Postal address
  • notes — Notes
GET/v1/clients/{id}Retrieve a client
PARAMETERS
  • id (required) — The client id (UUID)
PATCH/v1/clients/{id}Update a client · manager+
PARAMETERS
  • id (required) — The client id (UUID)
BODY
  • name — Client name
  • currency — 3-letter code
  • address — Postal address
  • notes — Notes
DELETE/v1/clients/{id}Archive a client · manager+

Refuses (422) while the client has active projects.

PARAMETERS
  • id (required) — The client id (UUID)

Projects

Projects, and who is assigned to them.

GET/v1/projectsList projects
PARAMETERS
  • client_id — Filter by client
  • is_active — true/false
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)
POST/v1/projectsCreate a project · manager+
BODY
  • client_id — UUID, required
  • name — Required
  • code — Short code
  • hourly_rate — Project hourly rate
  • starts_on — YYYY-MM-DD
  • ends_on — YYYY-MM-DD
GET/v1/projects/{id}Retrieve a project
PARAMETERS
  • id (required) — The project id (UUID)
PATCH/v1/projects/{id}Update a project · manager+
PARAMETERS
  • id (required) — The project id (UUID)
BODY
  • client_id — UUID
  • name — Project name
  • code — Short code
  • is_active — false archives, true restores
  • hourly_rate — Project hourly rate
  • starts_on — YYYY-MM-DD
  • ends_on — YYYY-MM-DD
DELETE/v1/projects/{id}Archive a project · manager+
PARAMETERS
  • id (required) — The project id (UUID)
GET/v1/projects/{id}/user_assignmentsList a project’s people
PARAMETERS
  • id (required) — The project id (UUID)
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)
POST/v1/projects/{id}/user_assignmentsAssign a person to a project · manager+
PARAMETERS
  • id (required) — The project id (UUID)
BODY
  • user_id — Member UUID, required
  • is_project_manager — Grants the PM flag
  • hourly_rate — Per-assignment billable rate
PATCH/v1/projects/{id}/user_assignments/{assignmentId}Update an assignment · manager+
PARAMETERS
  • id (required) — The project id (UUID)
  • assignmentId (required) — Assignment UUID
BODY
  • is_project_manager — PM flag
  • hourly_rate — Per-assignment billable rate
DELETE/v1/projects/{id}/user_assignments/{assignmentId}Remove an assignment · manager+
PARAMETERS
  • id (required) — The project id (UUID)
  • assignmentId (required) — Assignment UUID
GET/v1/projects/{id}/task_assignmentsList a project’s tasks (compatibility view)

Tasks belong to projects here, so each task is its own assignment.

PARAMETERS
  • id (required) — The project id (UUID)
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)

Tasks

Tasks (each belongs to one project — a deviation from Harvest).

GET/v1/tasksList tasks
PARAMETERS
  • project_id — Filter by project
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)
POST/v1/tasksCreate a task · manager+
BODY
  • project_id — UUID, required
  • name — Required
  • billable_by_default — Defaults true
  • default_hourly_rate — Task rate
GET/v1/tasks/{id}Retrieve a task
PARAMETERS
  • id (required) — The task id (UUID)
PATCH/v1/tasks/{id}Update a task · manager+
PARAMETERS
  • id (required) — The task id (UUID)
BODY
  • name — Task name
  • billable_by_default — true/false
  • default_hourly_rate — Task rate
DELETE/v1/tasks/{id}Delete a task · manager+
PARAMETERS
  • id (required) — The task id (UUID)

Users

Workspace members. Rates are money — manager+ tokens only.

GET/v1/usersList users
PARAMETERS
  • role — owner, admin, manager, or member
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)
GET/v1/users/meRetrieve the token’s owner · personal token
GET/v1/users/{id}Retrieve a user
PARAMETERS
  • id (required) — The user id (UUID)
GET/v1/users/{id}/billable_ratesList a user’s billable rates · manager+
PARAMETERS
  • id (required) — The user id (UUID)
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)
GET/v1/users/{id}/cost_ratesList a user’s cost rates · manager+
PARAMETERS
  • id (required) — The user id (UUID)
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)
GET/v1/users/{id}/project_assignmentsList a user’s project assignments
PARAMETERS
  • id (required) — The user id (UUID)
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)
GET/v1/users/{id}/teammatesList a user’s direct reports
PARAMETERS
  • id (required) — The user id (UUID)
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)

Roles

Work roles (job functions), assignable to members.

GET/v1/rolesList roles
PARAMETERS
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)
POST/v1/rolesCreate a role · manager+
BODY
  • name — Required
PATCH/v1/roles/{id}Update a role · manager+
PARAMETERS
  • id (required) — The role id (UUID)
BODY
  • name — Required
DELETE/v1/roles/{id}Delete a role · manager+
PARAMETERS
  • id (required) — The role id (UUID)

Invoices

Invoices, payments, and sending. Admin tokens or organization keys only.

GET/v1/invoicesList invoices
PARAMETERS
  • state — draft, open, partially_paid, paid, closed
  • client_id — Filter by client
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)
POST/v1/invoicesCreate an invoice · admin

Provide line_items OR period_start+period_end. Generated invoices mark hours billed so nothing is double-invoiced.

BODY
  • client_id — UUID, required
  • line_items — Array of {kind, description, quantity, unit_price} for a free-form invoice
  • period_start — With period_end: generate from uninvoiced time instead
  • period_end — YYYY-MM-DD
  • grouping — task (default), person, or detailed
  • include_expenses — Defaults true
  • subject — Subject line
  • issue_date — Defaults today
  • due_date — YYYY-MM-DD
  • tax — Percent
  • discount — Percent
GET/v1/invoices/{id}Retrieve an invoice (lines + payments)
PARAMETERS
  • id (required) — The invoice id (UUID)
PATCH/v1/invoices/{id}Update a draft invoice · admin
PARAMETERS
  • id (required) — The invoice id (UUID)
BODY
  • subject — Subject
  • notes — Notes
  • issue_date — YYYY-MM-DD
  • due_date — YYYY-MM-DD
  • tax — Percent
  • discount — Percent
DELETE/v1/invoices/{id}Delete a draft invoice · admin
PARAMETERS
  • id (required) — The invoice id (UUID)
POST/v1/invoices/{id}/messagesMark an invoice sent · admin

Moves draft → open. Email delivery stays a deliberate in-app action.

PARAMETERS
  • id (required) — The invoice id (UUID)
POST/v1/invoices/{id}/paymentsRecord a payment · admin
PARAMETERS
  • id (required) — The invoice id (UUID)
BODY
  • amount — Required
  • paid_date — YYYY-MM-DD, required
  • notes — Notes
DELETE/v1/invoices/{id}/payments/{paymentId}Delete a payment · admin
PARAMETERS
  • id (required) — The invoice id (UUID)
  • paymentId (required) — Payment UUID

Estimates

Quotes that convert to invoices. Admin tokens or organization keys only.

GET/v1/estimatesList estimates · manager+
PARAMETERS
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)
POST/v1/estimatesCreate an estimate · admin
BODY
  • client_id — UUID, required
  • line_items — Array of {kind, description, quantity, unit_price}, required
  • subject — Subject
  • issue_date — Defaults today
  • tax — Percent
  • discount — Percent
GET/v1/estimates/{id}Retrieve an estimate · manager+
PARAMETERS
  • id (required) — The estimate id (UUID)
PATCH/v1/estimates/{id}Change estimate state · admin
PARAMETERS
  • id (required) — The estimate id (UUID)
BODY
  • state — sent, accepted, or declined
DELETE/v1/estimates/{id}Delete a draft estimate · admin
PARAMETERS
  • id (required) — The estimate id (UUID)
POST/v1/estimates/{id}/convertConvert to a draft invoice · admin
PARAMETERS
  • id (required) — The estimate id (UUID)

Expenses

Expenses and categories. Member tokens manage their own.

GET/v1/expensesList expenses
PARAMETERS
  • user_id — Required with an organization key
  • from — YYYY-MM-DD
  • to — YYYY-MM-DD
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)
POST/v1/expensesCreate an expense
BODY
  • spent_date — YYYY-MM-DD, required
  • total_cost — Required
  • project_id — UUID
  • expense_category_id — UUID
  • billable — true/false
  • is_reimbursable — true/false
  • notes — Notes
  • user_id — Required with an organization key
DELETE/v1/expenses/{id}Delete an expense
PARAMETERS
  • id (required) — The expense id (UUID)
GET/v1/expense_categoriesList expense categories
PARAMETERS
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)
POST/v1/expense_categoriesCreate an expense category · manager+
BODY
  • name — Required
  • unit_price — For unit-based categories

Reports

Aggregations with money — manager+ tokens or organization keys.

GET/v1/reports/time/{dimension}Time report by clients, projects, tasks, or team · manager+
PARAMETERS
  • dimension (required) — clients, projects, tasks, or team
  • from (required) — YYYY-MM-DD
  • to (required) — YYYY-MM-DD
GET/v1/reports/expenses/{dimension}Expense report by categories, projects, or team · manager+
PARAMETERS
  • dimension (required) — categories, projects, or team
  • from (required) — YYYY-MM-DD
  • to (required) — YYYY-MM-DD
GET/v1/reports/project_budgetHours budget vs actual per project · manager+
PARAMETERS
  • from (required) — YYYY-MM-DD
  • to (required) — YYYY-MM-DD
GET/v1/reports/uninvoicedApproved, unbilled hours and amounts per project · manager+
PARAMETERS
  • page — Page number, starting at 1
  • per_page — Items per page (default 100, max 2000)