# 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. {% hint style="success" %} **CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform). {% endhint %} ## 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](https://www.getharvest.com/) 2. Go to [Developer Tools](https://id.getharvest.com/developers) 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** {% hint style="warning" %} **Important:** The Personal Access Token grants full access to your Harvest account data. Keep it secure and use a dedicated account for production workloads. {% endhint %} ### Using `sling conns` Here are examples of setting a connection named `HARVEST`. We must provide the `type=api` property: {% code overflow="wrap" %} ```bash sling conns set HARVEST type=api spec=harvest secrets='{ api_key: your_token_here, account_id: your_account_id }' ``` {% endcode %} ### Environment Variable See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file. {% code overflow="wrap" %} ```bash export HARVEST='{ type: api, spec: harvest, secrets: { api_key: "your_token_here", account_id: "your_account_id" } }' ``` {% endcode %} ### Sling Env File YAML See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file. ```yaml 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: ```yaml source: HARVEST target: MY_POSTGRES defaults: mode: full-refresh object: harvest.{stream_name} streams: # sync all endpoints '*': ``` **Incremental sync for all supported endpoints:** ```yaml 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: ```bash 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 ```yaml source: HARVEST target: MY_POSTGRES defaults: mode: full-refresh object: harvest.{stream_name} streams: '*': ``` ### Track Time Entries and Projects Incrementally ```yaml 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 ```yaml 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 , on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.slingdata.io/connections/api-connections/harvest.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.