Harvest

Connect & Ingest data from Harvest

Harvest is a time tracking and invoicing tool used by teams and freelancers to log hours, manage projects, track expenses, and send invoices. The Sling Harvest connector extracts data from the Harvest REST API v2, supporting users, clients, projects, tasks, time entries, invoices, estimates, expenses, roles, and assignments.

CLI Pro Required: APIs require a CLI Pro token or Platform Plan.

Setup

The following credentials are accepted:

Secrets:

• api_key (required) -> Your Harvest Personal Access Token

• account_id (required) -> Your Harvest Account ID

Inputs (optional):

• anchor_date -> Starting date for first sync of incremental endpoints (ISO 8601 format, e.g., 2024-01-01T00:00:00Z). Defaults to 1 year ago.

Getting Your Credentials

1. Log in to Harvest

2. Go to Developer Tools

3. Click Create New Personal Access Token

4. Give the token a name (e.g., "Sling Integration")

5. Copy both the Token and Account ID

Important: The Personal Access Token grants full access to your Harvest account data. Keep it secure and use a dedicated account for production workloads.

Using sling conns

Here are examples of setting a connection named HARVEST. We must provide the type=api property:

sling conns set HARVEST type=api spec=harvest secrets='{ api_key: your_token_here, account_id: your_account_id }'

Environment Variable

See here to learn more about the .env.sling file.

export HARVEST='{ type: api, spec: harvest, secrets: { api_key: "your_token_here", account_id: "your_account_id" } }'

Sling Env File YAML

See here to learn more about the sling env.yaml file.

connections:
  HARVEST:
    type: api
    spec: harvest
    secrets:
      api_key: "your_token_here"
      account_id: "your_account_id"

Replication

Here's an example replication configuration to sync Harvest data to a PostgreSQL database:

source: HARVEST
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: harvest.{stream_name}

streams:
  # sync all endpoints
  '*':

Incremental sync for all supported endpoints:

source: HARVEST
target: MY_POSTGRES

defaults:
  object: harvest.{stream_name}

streams:
  users:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  clients:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  contacts:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  projects:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  tasks:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  roles:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  company:
    mode: full-refresh
  time_entries:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  invoices:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  invoice_messages:
    mode: full-refresh
  invoice_payments:
    mode: full-refresh
  invoice_item_categories:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  estimates:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  estimate_messages:
    mode: full-refresh
  estimate_item_categories:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  expenses:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  expense_categories:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  user_assignments:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  task_assignments:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  user_billable_rates:
    mode: full-refresh
  user_cost_rates:
    mode: full-refresh

Endpoints

Endpoint	Description	Incremental	Depends On
users	All users in the account	Yes	—
clients	All clients	Yes	—
contacts	All client contacts	Yes	—
projects	All projects	Yes	—
tasks	All tasks	Yes	—
roles	All roles	Yes	—
company	Company settings (single record)	No	—
time_entries	All time entries	Yes	—
invoices	All invoices	Yes	—
invoice_messages	Messages for each invoice	No	invoices
invoice_payments	Payments for each invoice	No	invoices
invoice_item_categories	Invoice line item categories	Yes	—
estimates	All estimates	Yes	—
estimate_messages	Messages for each estimate	No	estimates
estimate_item_categories	Estimate line item categories	Yes	—
expenses	All expenses	Yes	—
expense_categories	Expense categories	Yes	—
user_assignments	User-to-project assignments	Yes	—
task_assignments	Task-to-project assignments	Yes	—
user_billable_rates	Billable rates for each user	No	users
user_cost_rates	Cost rates for each user	No	users

The connector uses a queue-based architecture for child endpoints. The invoices endpoint populates invoice IDs into a queue consumed by invoice_messages and invoice_payments. Similarly, estimates feeds estimate_messages, and users feeds user_billable_rates and user_cost_rates.

To discover available endpoints:

sling conns discover HARVEST

Incremental Sync

Most endpoints support incremental sync using the updated_since parameter:

• First run: Fetches all records updated within the last year (or since anchor_date if provided)

• Subsequent runs: Only fetches records modified after the last sync timestamp

• Update key: updated_at

Child endpoints (invoice_messages, invoice_payments, estimate_messages, user_billable_rates, user_cost_rates) and the company endpoint always run in full-refresh mode since they don't support time-based filtering.

Rate Limiting

The Harvest API enforces a rate limit of 100 requests per 15 seconds. The connector automatically:

• Uses conservative rate limiting (5 requests/second with concurrency of 3)

• Retries with exponential backoff on 429 (rate limit) responses, up to 5 attempts

Common Use Cases

Sync All Harvest Data

source: HARVEST
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: harvest.{stream_name}

streams:
  '*':

Track Time Entries and Projects Incrementally

source: HARVEST
target: MY_POSTGRES

defaults:
  object: harvest.{stream_name}

streams:
  projects:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  tasks:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  time_entries:
    mode: incremental
    primary_key: [id]
    update_key: updated_at

Export Invoices and Expenses

source: HARVEST
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: harvest.{stream_name}

streams:
  clients:
  invoices:
  invoice_messages:
  invoice_payments:
  expenses:
  expense_categories:

If you are facing issues connecting, please reach out to us at [email protected], on discord or open a Github Issue here.