This is page 1 of 2. Use http://codebase.md/adrian-dotco/harvest-mcp-server?lines=false&page={x} to view the full context.
# Directory Structure
```
├── .github
│ └── workflows
│ ├── claude-code-review.yml
│ └── claude.yml
├── .gitignore
├── docs
│ └── harvest_api_docs
│ ├── 01_introduction
│ │ ├── 01_overview.md
│ │ ├── 02_postman_collection.md
│ │ ├── 03_code_samples.md
│ │ ├── 04_supported_timezones.md
│ │ ├── 05_supported_currencies.md
│ │ ├── 06_pagination.md
│ │ └── README.md
│ ├── 02_authentication
│ │ ├── 01_authentication.md
│ │ └── README.md
│ ├── 03_clients_api
│ │ ├── 01_clients.md
│ │ ├── 02_client_contacts.md
│ │ └── README.md
│ ├── 04_company
│ │ ├── 01_company.md
│ │ └── README.md
│ ├── 05_invoices
│ │ ├── 01_invoice_item_categories.md
│ │ ├── 02_invoice_messages.md
│ │ ├── 03_invoice_payments.md
│ │ ├── 04_invoices.md
│ │ └── README.md
│ ├── 06_estimates
│ │ ├── 01_estimate_item_categories.md
│ │ ├── 02_estimate_messages.md
│ │ ├── 03_estimates.md
│ │ └── README.md
│ ├── 07_expenses
│ │ ├── expense_categories.md
│ │ └── expenses.md
│ ├── 08_tasks
│ │ └── tasks.md
│ ├── 09_timesheets
│ │ └── time_entries.md
│ ├── 10_projects
│ │ ├── project_task_assignments.md
│ │ ├── project_user_assignments.md
│ │ └── projects.md
│ ├── 11_roles
│ │ └── roles.md
│ ├── 12_users
│ │ ├── billable_rates.md
│ │ ├── cost_rates.md
│ │ ├── project_assignments.md
│ │ ├── teammates.md
│ │ └── users.md
│ ├── 13_reports
│ │ ├── expenses.md
│ │ ├── project_budget.md
│ │ ├── time.md
│ │ └── uninvoiced.md
│ └── README.md
├── LICENSE
├── llms-install.md
├── package-lock.json
├── package.json
├── README.md
├── src
│ ├── index.ts
│ ├── setup.ts
│ └── types
│ └── chrono-node.d.ts
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
# Dependencies
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Build output
build/
dist/
*.tsbuildinfo
# Environment variables
.env
.env.local
.env.*.local
# IDE and editor files
.idea/
.vscode/
*.swp
*.swo
.DS_Store
Thumbs.db
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/02_authentication/README.md:
--------------------------------------------------------------------------------
```markdown
# Authentication
This directory contains documentation for authenticating with the Harvest API v2:
1. [Authentication](01_authentication.md)
- Personal Access Tokens
- OAuth2 Authentication
- Authorization Flows
- Scopes
- Account Access
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/04_company/README.md:
--------------------------------------------------------------------------------
```markdown
# Company API
This directory contains documentation for managing company settings in the Harvest API v2:
1. [Company](01_company.md)
- Company Object and Attributes
- Retrieving Company Information
- Updating Company Settings
- Example Responses
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/03_clients_api/README.md:
--------------------------------------------------------------------------------
```markdown
# Clients API
This directory contains documentation for the Clients API endpoints:
1. [Clients](01_clients.md)
- Manage client information
- CRUD operations for clients
- Client object structure and attributes
2. [Client Contacts](02_client_contacts.md)
- Manage client contact information
- CRUD operations for contacts
- Contact object structure and attributes
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/06_estimates/README.md:
--------------------------------------------------------------------------------
```markdown
# Estimates API
This directory contains documentation for working with estimates in the Harvest API v2:
1. [Estimate Item Categories](01_estimate_item_categories.md)
- Managing estimate item categories
- Category types and properties
- CRUD operations
2. [Estimate Messages](02_estimate_messages.md)
- Sending estimate messages
- Message templates
- State changes via messages
- Email notifications
3. [Estimates](03_estimates.md)
- Main estimate operations
- Creating and managing estimates
- Managing estimate states
- Line items management
- Estimate properties and attributes
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/05_invoices/README.md:
--------------------------------------------------------------------------------
```markdown
# Invoices API
This directory contains documentation for working with invoices in the Harvest API v2:
1. [Invoice Item Categories](01_invoice_item_categories.md)
- Managing invoice item categories
- Category types and properties
- CRUD operations
2. [Invoice Messages](02_invoice_messages.md)
- Sending invoice messages
- Message templates
- State changes via messages
- Email notifications
3. [Invoice Payments](03_invoice_payments.md)
- Recording payments
- Payment options
- Payment management
- Thank you messages
4. [Invoices](04_invoices.md)
- Main invoice operations
- Creating invoices (free-form and from time/expenses)
- Managing invoice states
- Line items management
- Invoice properties and attributes
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/01_introduction/README.md:
--------------------------------------------------------------------------------
```markdown
# Introduction
This directory contains the introduction and overview documentation for the Harvest API v2:
1. [Overview](01_overview.md)
- API Requests and Responses
- Rate Limiting
- Data Types
2. [Postman Collection](02_postman_collection.md)
- Importing and Using the Collection
- Authorization Setup
- Running Requests
3. [Code Samples](03_code_samples.md)
- Programming Language Examples
- OAuth Sample
4. [Supported Time Zones](04_supported_timezones.md)
- List of Supported Time Zones
- UTC Offsets
- DST Information
5. [Supported Currencies](05_supported_currencies.md)
- List of Supported Currencies
- Currency Codes
6. [Pagination](06_pagination.md)
- Pagination Parameters
- Response Format
- Example Usage
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
# Harvest Natural Language Time Entry MCP Server
An MCP server that lets you log Harvest time entries using natural language, including special handling for leave requests. This server makes time tracking more intuitive by understanding natural language inputs and automatically handling common scenarios like leave requests.
<a href="https://glama.ai/mcp/servers/u2bir05hxy">
<img width="380" height="200" src="https://glama.ai/mcp/servers/u2bir05hxy/badge" alt="Harvest Natural Language Time Entry Server MCP server" />
</a>
## Features
- 🗣️ Natural language time entry parsing
- 🏖️ Special leave request handling (e.g., "I'm off sick today")
- ⏰ Configurable work day hours
- 🌍 Timezone support
- 🎯 Automatic project and task matching
- 📅 Smart date parsing (today, yesterday, etc.)
## Prerequisites
- Node.js installed
- A Harvest account
- Personal access token from [Harvest Developer Tools](https://id.getharvest.com/developers)
- Account ID (shown on the same page as your token)
## Installation
### Installation
1. Install the [Claude desktop app](https://claude.ai/desktop)
2. Clone this repository:
```bash
git clone https://github.com/adrian-dotco/harvest-mcp-server.git
cd harvest-mcp-server
```
3. Install dependencies and build:
```bash
npm install
npm run build
```
4. Run the setup script:
```bash
node build/setup.js
```
5. Follow the prompts to enter your:
- Harvest Personal Access Token (from https://id.getharvest.com/developers)
- Harvest Account ID
- Standard work day hours (default: 7.5)
- Timezone (default: Australia/Perth)
6. Restart Claude desktop app
That's it! You can now use natural language time tracking in Claude.
### Staying Updated
To update to the latest version:
```bash
git pull
npm install
npm run build
```
The setup script will have configured Claude to use your local build of the server, so any updates you pull will be automatically available after rebuilding.
## Usage
The server provides several tools for interacting with Harvest:
### log_time
Log time entries using natural language. Examples:
Regular time entries:
```
"2 hours on Project X doing development work today"
"45 minutes on Project Y testing yesterday"
"3.5 hours on Project Z meetings last Friday"
```
Leave requests (automatically uses standard work day hours):
```
"I'm off sick today"
"I'm unwell today"
"Taking annual leave next week"
```
### get_time_report
Get time reports using natural language queries. Examples:
1. Time Period Options:
```
"Show time report for last month"
"Get time summary for this week"
"Show hours from January 1st to January 31st"
"Report time for Q1"
"Show me yesterday's hours"
```
2. Report Types:
- By Project (default):
```
"Show time report for last month"
"Get project hours for this week"
```
- By Client:
```
"Show time report by client for this month"
"Get hours by client for Q1"
```
- By Task:
```
"Show time summary by task for January"
"Get task breakdown for last week"
```
- By Team Member:
```
"Show team hours for last week"
"Get time report by user for this month"
```
3. Report Details:
Each report includes:
- Total hours worked
- Billable vs non-billable hours
- Billable amounts (if you have permission)
- Project/client/task/user details based on report type
### list_projects
List all available Harvest projects:
```
List my projects
```
### list_tasks
List available tasks for a specific project:
```
Show tasks for Project X
```
### list_entries
View recent time entries:
```
Show my recent time entries
```
## Configuration
The server supports these environment variables:
- `HARVEST_ACCESS_TOKEN`: Your Harvest personal access token
- `HARVEST_ACCOUNT_ID`: Your Harvest account ID
- `STANDARD_WORK_DAY_HOURS`: Default hours for a full work day (default: 7.5)
- `TIMEZONE`: Your timezone (default: Australia/Perth)
## Development
The server is built using:
- TypeScript
- MCP SDK
- chrono-node for natural language date parsing
- Harvest API v2
To contribute:
1. Fork the repository
2. Create a feature branch
3. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) for details
```
--------------------------------------------------------------------------------
/src/types/chrono-node.d.ts:
--------------------------------------------------------------------------------
```typescript
declare module 'chrono-node' {
interface ParsedResult {
start: {
date: () => Date;
};
end?: {
date: () => Date;
};
}
export function parse(text: string): ParsedResult[];
export function parseDate(text: string): Date | null;
}
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./build",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/08_tasks/tasks.md:
--------------------------------------------------------------------------------
```markdown
# Tasks
## The task object
Attribute | Type | Description
--------- | ---- | -----------
`id` | integer | Unique ID for the task.
`name` | string | The name of the task.
`billable_by_default` | boolean | Used in determining whether default tasks should be marked billable when creating a new project.
`default_hourly_rate` | decimal | The hourly rate to use for this task when it is added to a project.
`is_default` | boolean | Whether this task should be automatically added to future projects.
`is_active` | boolean | Whether this task is active or archived.
`created_at` | datetime | Date and time the task was created.
`updated_at` | datetime | Date and time the task was last updated.
## Required permissions
You must be an Administrator or Manager with permission to create and edit tasks in order to interact with the
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/06_estimates/01_estimate_item_categories.md:
--------------------------------------------------------------------------------
```markdown
# Estimate Item Categories
Admin permissions required.
## The Estimate Item Category Object
### Attributes:
- id (integer): Unique ID for the category
- name (string): Category name
- created_at (datetime): Creation timestamp
- updated_at (datetime): Last update timestamp
## Available Endpoints
### List All Categories
```
GET /v2/estimate_item_categories
```
Parameters:
- updated_since (datetime): Filter by update date
- per_page (integer): Records per page (1-2000)
### Retrieve a Category
```
GET /v2/estimate_item_categories/{ESTIMATE_ITEM_CATEGORY_ID}
```
### Create a Category
```
POST /v2/estimate_item_categories
```
Required Parameters:
- name (string): Category name
### Update a Category
```
PATCH /v2/estimate_item_categories/{ESTIMATE_ITEM_CATEGORY_ID}
```
Updateable Parameters:
- name (string): Category name
### Delete a Category
```
DELETE /v2/estimate_item_categories/{ESTIMATE_ITEM_CATEGORY_ID}
```
## Example Response
```json
{
"id": 1378704,
"name": "Product",
"created_at": "2017-06-26T20:41:00Z",
"updated_at": "2017-06-26T20:41:00Z"
}
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "harvest-mcp-server-setup",
"version": "0.1.2",
"description": "Natural language time tracking with Harvest",
"type": "module",
"bin": {
"harvest-mcp-server-setup": "./build/setup.js"
},
"files": [
"build"
],
"scripts": {
"build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\" && node -e \"require('fs').chmodSync('build/setup.js', '755')\"",
"prepare": "npm run build",
"watch": "tsc --watch",
"inspector": "npx @modelcontextprotocol/inspector build/index.js"
},
"dependencies": {
"@modelcontextprotocol/sdk": "0.6.0",
"axios": "^1.7.9",
"chrono-node": "^2.7.8"
},
"devDependencies": {
"@types/node": "^20.11.24",
"typescript": "^5.3.3"
},
"publishConfig": {
"access": "public"
},
"keywords": [
"harvest",
"time-tracking",
"mcp",
"claude",
"natural-language"
],
"author": "Adrian",
"license": "MIT",
"repository": {
"type": "git",
"url": "git+https://github.com/adrian-dotco/harvest-mcp-server.git"
},
"bugs": {
"url": "https://github.com/adrian-dotco/harvest-mcp-server/issues"
},
"homepage": "https://github.com/adrian-dotco/harvest-mcp-server#readme"
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/01_introduction/02_postman_collection.md:
--------------------------------------------------------------------------------
```markdown
# Postman Collection
## Introduction
We've created a collection in Postman that allows you to easily try out and experiment with various API requests. To get started, all you have to do is import the collection into your Postman workspace and set up the authorization variables.
## Importing the Collection
Importing the collection is easy; simply click the **Run in Postman** button in the Harvest documentation and the collection will be imported into your active workspace.
**Note:** You only need to import the collection once.
## Authorization
The Postman collection uses environment variables for authorization. That allows you to enter your account ID and access token in one location, rather than having to do it for each request.
To set up your authorization variables:
1. Click the ellipsis (...) next to the collection's name
2. Select "Edit" from the dropdown
3. From the "Variables" tab, replace the values for:
- HARVEST_ACCOUNT_ID
- Bearer ACCESS_TOKEN
4. Click "Update" at the bottom
## Running a Request
1. Some requests require additional parameters:
- Required parameters show a checked box
- Optional parameters are grayed out
2. Fill in necessary parameters
3. Click "Send" to execute the request
The response will be displayed in JSON format in the response pane.
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/01_introduction/01_overview.md:
--------------------------------------------------------------------------------
```markdown
# Overview
The Harvest V2 API is a REST API that allows you to interact with your Harvest account programmatically. You can track time, log expenses, create projects, and more.
## API Requests
Harvest requires applications to authenticate all requests with OAuth2 or Personal Access Tokens. The following HTTP methods are supported:
- GET
- POST
- PATCH
- DELETE
### Request Headers Required
- Authorization: Bearer $ACCESS_TOKEN
- Harvest-Account-Id: $ACCOUNT_ID
- User-Agent: MyApp (<[email protected]>)
### Parameters
- GET requests: Include in URL query string
- POST/PATCH requests: Include in request body (JSON or form data)
- For JSON, use Content-Type: application/json header
## API Responses
Responses are formatted in JSON. HTTP status codes indicate success or failure:
- 200: Success
- 201: New object created
- 403: Unauthorized
- 404: Not found
- 422: Processing errors
- 429: Request throttled
- 500: Server error
## Rate Limiting
- General API requests: 100 requests per 15 seconds
- Reports API requests: 100 requests per 15 minutes
- HTTP 429 status sent when limit exceeded
- Retry-After header indicates seconds until throttle lifted
## Data Types
- boolean: true/false
- string: "foo"
- integer: 42
- decimal: 6.8
- date: "2017-12-31"
- datetime: "2017-12-31T14:59:22Z"
- time: "14:59" or "2:59pm"
- array: [1, 2, 3]
- object: { name: "value" }
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/01_introduction/03_code_samples.md:
--------------------------------------------------------------------------------
```markdown
# Code Samples
## Programming Language Examples
Sample code for accessing the v2 API is available in multiple languages:
- [Java](https://github.com/harvesthq/harvest_api_samples/blob/master/v2/HarvestAPISample.java)
- [C#](https://github.com/harvesthq/harvest_api_samples/blob/master/v2/harvest_api_sample.cs)
- [Go](https://github.com/harvesthq/harvest_api_samples/blob/master/v2/harvest_api_sample.go)
- [JavaScript](https://github.com/harvesthq/harvest_api_samples/blob/master/v2/harvest_api_sample.js)
- [PHP](https://github.com/harvesthq/harvest_api_samples/blob/master/v2/harvest_api_sample.php)
- [PowerShell](https://github.com/harvesthq/harvest_api_samples/blob/master/v2/harvest_api_sample.ps1)
- [Python](https://github.com/harvesthq/harvest_api_samples/blob/master/v2/harvest_api_sample.py)
- [Ruby](https://github.com/harvesthq/harvest_api_samples/blob/master/v2/harvest_api_sample.rb)
- [Visual Basic](https://github.com/harvesthq/harvest_api_samples/blob/master/v2/harvest_api_sample.vbs)
- [Google Apps Script](https://github.com/harvesthq/harvest_api_samples/blob/master/v2/harvest_api_sample.gs)
## OAuth Sample
A live demo of the OAuth implicit grant flow from a client-side application is available at:
[https://harvesthq.github.io/harvest_api_samples/](https://harvesthq.github.io/harvest_api_samples/)
The [source code](https://github.com/harvesthq/harvest_api_samples/tree/master/v2/oauth) for the OAuth demo is also available.
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/05_invoices/01_invoice_item_categories.md:
--------------------------------------------------------------------------------
```markdown
# Invoice Item Categories
Admin or Project Manager permissions required.
## The Invoice Item Category Object
### Attributes:
- id (integer): Unique ID for the invoice item category
- name (string): The name of the invoice item category
- use_as_service (boolean): Whether used for billable hours when generating an invoice
- use_as_expense (boolean): Whether used for expenses when generating an invoice
- created_at (datetime): Creation timestamp
- updated_at (datetime): Last update timestamp
## Available Endpoints
### List All Invoice Item Categories
```
GET /v2/invoice_item_categories
```
Parameters:
- updated_since (datetime): Filter by update date
- per_page (integer): Records per page (1-2000)
### Retrieve an Invoice Item Category
```
GET /v2/invoice_item_categories/{INVOICE_ITEM_CATEGORY_ID}
```
### Create an Invoice Item Category
```
POST /v2/invoice_item_categories
```
Required Parameters:
- name (string): Category name
### Update an Invoice Item Category
```
PATCH /v2/invoice_item_categories/{INVOICE_ITEM_CATEGORY_ID}
```
Updateable Parameters:
- name (string): Category name
### Delete an Invoice Item Category
```
DELETE /v2/invoice_item_categories/{INVOICE_ITEM_CATEGORY_ID}
```
Only possible if both `use_as_service` and `use_as_expense` are false.
## Example Response
```json
{
"id": 1466293,
"name": "Product",
"use_as_service": false,
"use_as_expense": true,
"created_at": "2017-06-26T20:41:00Z",
"updated_at": "2017-06-26T20:41:00Z"
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/03_clients_api/01_clients.md:
--------------------------------------------------------------------------------
```markdown
# Clients
## The Client Object
### Attributes:
- id (integer): Unique ID for the client
- name (string): Client description
- is_active (boolean): Active or archived status
- address (string): Physical address
- statement_key (string): Used for invoice dashboard URL
- currency (string): Associated currency code
- created_at (datetime): Creation timestamp
- updated_at (datetime): Last update timestamp
## Required Permissions
Administrator or Manager with client creation/editing permissions required.
## Endpoints
### List All Clients
```
GET /v2/clients
```
Parameters:
- is_active (boolean): Filter active/inactive clients
- updated_since (datetime): Filter by update date
- per_page (integer): Records per page (1-2000)
### Retrieve a Client
```
GET /v2/clients/{CLIENT_ID}
```
### Create a Client
```
POST /v2/clients
```
Required Parameters:
- name (string)
Optional Parameters:
- is_active (boolean)
- address (string)
- currency (string)
### Update a Client
```
PATCH /v2/clients/{CLIENT_ID}
```
Updateable Parameters:
- name
- is_active
- address
- currency
### Delete a Client
```
DELETE /v2/clients/{CLIENT_ID}
```
Only possible if client has no associated projects, invoices, or estimates.
## Example Response
```json
{
"id": 5735776,
"name": "123 Industries",
"is_active": true,
"address": "123 Main St.\r\nAnytown, LA 71223",
"statement_key": "0a39d3e33c8058cf7c3f8097d854c64e",
"created_at": "2017-06-26T21:02:12Z",
"updated_at": "2017-06-26T21:34:11Z",
"currency": "EUR"
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/03_clients_api/02_client_contacts.md:
--------------------------------------------------------------------------------
```markdown
# Client Contacts
## The Contact Object
### Attributes:
- id (integer): Unique ID for the contact
- client (object): Object containing client id and name
- title (string): Contact's title
- first_name (string): Contact's first name
- last_name (string): Contact's last name
- email (string): Email address
- phone_office (string): Office phone number
- phone_mobile (string): Mobile phone number
- fax (string): Fax number
- created_at (datetime): Creation timestamp
- updated_at (datetime): Last update timestamp
## Required Permissions
Administrator or Manager with permission to create and edit clients.
## Endpoints
### List All Contacts
```
GET /v2/contacts
```
Parameters:
- client_id (integer): Filter by client
- updated_since (datetime): Filter by update date
- per_page (integer): Records per page (1-2000)
### Retrieve a Contact
```
GET /v2/contacts/{CONTACT_ID}
```
### Create a Contact
```
POST /v2/contacts
```
Required Parameters:
- client_id (integer)
- first_name (string)
Optional Parameters:
- title (string)
- last_name (string)
- email (string)
- phone_office (string)
- phone_mobile (string)
- fax (string)
### Update a Contact
```
PATCH /v2/contacts/{CONTACT_ID}
```
Updateable Parameters:
- All create parameters
### Delete a Contact
```
DELETE /v2/contacts/{CONTACT_ID}
```
## Example Response
```json
{
"id": 4706479,
"title": "Owner",
"first_name": "Jane",
"last_name": "Doe",
"email": "[email protected]",
"phone_office": "(203) 697-8885",
"phone_mobile": "(203) 697-8886",
"fax": "(203) 697-8887",
"created_at": "2017-06-26T21:20:07Z",
"updated_at": "2017-06-26T21:27:07Z",
"client": {
"id": 5735774,
"name": "ABC Corp"
}
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/05_invoices/03_invoice_payments.md:
--------------------------------------------------------------------------------
```markdown
# Invoice Payments
## The Invoice Payment Object
### Attributes:
- id (integer): Unique ID for the payment
- amount (decimal): The amount of the payment
- paid_at (datetime): Date and time the payment was made
- paid_date (date): Date the payment was made
- recorded_by (string): Name of person who recorded payment
- recorded_by_email (string): Email of person who recorded payment
- notes (string): Any notes associated with the payment
- transaction_id (string): Card authorization or PayPal transaction ID
- payment_gateway (object): Payment gateway ID and name
- created_at (datetime): Creation timestamp
- updated_at (datetime): Last update timestamp
## Required Permissions
Administrator or Manager with invoice permissions required.
## Available Endpoints
### List Payments for an Invoice
```
GET /v2/invoices/{INVOICE_ID}/payments
```
Parameters:
- updated_since (datetime): Filter by update date
- per_page (integer): Records per page (1-2000)
### Create a Payment
```
POST /v2/invoices/{INVOICE_ID}/payments
```
Required Parameters:
- amount (decimal): Payment amount
Optional Parameters:
- paid_at (datetime): Payment timestamp (use either paid_at or paid_date)
- paid_date (date): Payment date (use either paid_at or paid_date)
- notes (string): Payment notes
- send_thank_you (boolean): Send thank you email if invoice will be fully paid
### Delete a Payment
```
DELETE /v2/invoices/{INVOICE_ID}/payments/{PAYMENT_ID}
```
## Example Response
```json
{
"id": 10336386,
"amount": 1575.86,
"paid_at": "2017-07-24T13:32:18Z",
"paid_date": "2017-07-24",
"recorded_by": "Jane Bar",
"recorded_by_email": "[email protected]",
"notes": "Paid by phone",
"transaction_id": null,
"created_at": "2017-07-28T14:42:44Z",
"updated_at": "2017-07-28T14:42:44Z",
"payment_gateway": {
"id": null,
"name": null
}
}
```
--------------------------------------------------------------------------------
/.github/workflows/claude-code-review.yml:
--------------------------------------------------------------------------------
```yaml
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
# Optional: Only run on specific file changes
# paths:
# - "src/**/*.ts"
# - "src/**/*.tsx"
# - "src/**/*.js"
# - "src/**/*.jsx"
jobs:
claude-review:
# Optional: Filter by PR author
# if: |
# github.event.pull_request.user.login == 'external-contributor' ||
# github.event.pull_request.user.login == 'new-developer' ||
# github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
issues: read
id-token: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 1
- name: Run Claude Code Review
id: claude-review
uses: anthropics/claude-code-action@v1
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
prompt: |
Please review this pull request and provide feedback on:
- Code quality and best practices
- Potential bugs or issues
- Performance considerations
- Security concerns
- Test coverage
Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
# or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
```
--------------------------------------------------------------------------------
/.github/workflows/claude.yml:
--------------------------------------------------------------------------------
```yaml
name: Claude Code
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
issues:
types: [opened, assigned]
pull_request_review:
types: [submitted]
jobs:
claude:
if: |
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
(github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
issues: read
id-token: write
actions: read # Required for Claude to read CI results on PRs
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 1
- name: Run Claude Code
id: claude
uses: anthropics/claude-code-action@v1
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
# This is an optional setting that allows Claude to read CI results on PRs
additional_permissions: |
actions: read
# Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
# prompt: 'Update the pull request description to include a summary of changes.'
# Optional: Add claude_args to customize behavior and configuration
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
# or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
# claude_args: '--model claude-opus-4-1-20250805 --allowed-tools Bash(gh pr:*)'
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/02_authentication/01_authentication.md:
--------------------------------------------------------------------------------
```markdown
# Authentication
The V2 API supports two authentication methods:
## Personal Access Tokens
- Quickest way to start using the API
- Created in the Developers section of Harvest ID
- Provides token and account IDs
- Best for personal scripts and automation
- Has full 'all' scope access by default
### Using Personal Access Token:
1. Header Authentication:
```bash
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
https://api.harvestapp.com/v2/users/me
```
2. Query String Authentication:
```bash
curl -H "User-Agent: MyApp ([email protected])" \
"https://api.harvestapp.com/v2/users/me?access_token=$ACCESS_TOKEN&account_id=$ACCOUNT_ID"
```
## OAuth2 Authentication
For building integrations that other users can use. Requires registering an OAuth2 Application with:
- Name
- Redirect URL
- Multi Account setting
- Product scope (Harvest, Forecast, or both)
### OAuth2 Authorization Flows:
1. Server-side Applications (Authorization Code flow):
- Redirect user to: https://id.getharvest.com/oauth2/authorize?client_id={CLIENT_ID}&response_type=code
- Exchange authorization code for tokens
- Use refresh token to get new access token when needed
2. Client-side Applications (Implicit Grant flow):
- Redirect user to: https://id.getharvest.com/oauth2/authorize?client_id={CLIENT_ID}&response_type=token
- Receives access token directly
- No refresh token provided
## Scopes
Available scopes:
- harvest:{ACCOUNT_ID} - access to specific Harvest account
- forecast:{ACCOUNT_ID} - access to specific Forecast account
- harvest:all - access to all Harvest accounts
- forecast:all - access to all Forecast accounts
- all - access to all accounts
## Account Access
Check accessible accounts using:
```bash
GET https://id.getharvest.com/api/v2/accounts
```
Returns user info and list of accessible accounts with their IDs and products.
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/04_company/01_company.md:
--------------------------------------------------------------------------------
```markdown
# Company
Admin permissions required for all company endpoints.
## The Company Object
### Attributes:
- base_uri (string): The Harvest URL for the company
- full_domain (string): The Harvest domain
- name (string): Company name
- is_active (boolean): Active/archived status
- week_start_day (string): Start of week (Saturday/Sunday/Monday)
- wants_timestamp_timers (boolean): Time tracking method
- time_format (string): decimal or hours_minutes
- date_format (string): Date display format
- plan_type (string): trial, free, or plan name
- clock (string): 12h or 24h
- currency_code_display (string): Currency code display setting
- currency_symbol_display (string): Currency symbol display setting
- decimal_symbol (string): Decimal formatting symbol
- thousands_separator (string): Number formatting separator
- color_scheme (string): Web client color scheme
- weekly_capacity (integer): Weekly capacity in seconds
- expense_feature (boolean): Expense module status
- invoice_feature (boolean): Invoice module status
- estimate_feature (boolean): Estimate module status
- approval_feature (boolean): Approval module status
- team_feature (boolean): Team module status
## Available Endpoints
### Retrieve Company Info
```
GET /v2/company
```
Returns company object for authenticated user.
### Update Company Settings
```
PATCH /v2/company
```
#### Updateable Parameters:
- wants_timestamp_timers (boolean)
- weekly_capacity (integer)
## Example Response
```json
{
"base_uri": "https://{ACCOUNT_SUBDOMAIN}.harvestapp.com",
"full_domain": "{ACCOUNT_SUBDOMAIN}.harvestapp.com",
"name": "API Examples",
"is_active": true,
"week_start_day": "Monday",
"wants_timestamp_timers": true,
"time_format": "hours_minutes",
"date_format": "%Y-%m-%d",
"plan_type": "sponsored",
"expense_feature": true,
"invoice_feature": true,
"estimate_feature": true,
"approval_feature": true,
"clock": "12h",
"currency_code_display": "iso_code_none",
"currency_symbol_display": "symbol_before",
"decimal_symbol": ".",
"thousands_separator": ",",
"color_scheme": "orange",
"weekly_capacity": 126000
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/01_introduction/06_pagination.md:
--------------------------------------------------------------------------------
```markdown
# Pagination
Most requests that return multiple records are paginated. The response includes:
- A `links` section with URLs to retrieve the `first`, `next`, `previous`, and `last` pages
- Metadata values for `page`, `total_pages`, `total_entries`, `next_page`, and `previous_page`
For cursor-based pagination, `page`, `next_page`, and `previous_page` will be `null` except for first and last pages.
**Note:** Always use the pagination URLs provided in the `links` section instead of constructing pagination links manually.
## Pagination Parameters
Paginated endpoints support these optional parameters:
### per_page
- Controls number of records per page
- Default and maximum: 2000
- If not specified, returns maximum records
- Values larger than maximum return 422 error
### page or cursor
- Indicates which page of records to return
- Mutually exclusive - don't use together
- `cursor` takes precedence if both provided
- Avoid using directly - use `links` URLs instead
## Example Paginated Response
First page request:
```
GET /v2/clients
```
Response:
```json
{
"clients": [
"{2000 client objects}"
],
"page": 1,
"total_pages": 3,
"total_entries": 257,
"next_page": 2,
"previous_page": null,
"links": {
"first": "https://api.harvestapp.com/v2/clients?page=1&per_page=2000&ref=first",
"next": "https://api.harvestapp.com/v2/clients?cursor=eyJhZnRlciI6eyJpZCI6MzAwN319&per_page=2000&ref=next_cursor",
"previous": null,
"last": "https://api.harvestapp.com/v2/clients?page=3&per_page=2000&ref=last"
}
}
```
Second page request (using `next` URL from links):
```
GET /v2/clients?cursor=eyJhZnRlciI6eyJpZCI6MzAwN319&per_page=2000&ref=next_cursor
```
Last page response:
```json
{
"clients": [
"{57 client objects}"
],
"page": 3,
"total_pages": 3,
"total_entries": 257,
"next_page": null,
"previous_page": 2,
"links": {
"first": "https://api.harvestapp.com/v2/clients?page=1&per_page=2000&ref=first",
"next": null,
"previous": "https://api.harvestapp.com/v2/clients?page=4&per_page=2000&ref=previous",
"last": "https://api.harvestapp.com/v2/clients?page=3&per_page=2000&ref=last"
}
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/06_estimates/02_estimate_messages.md:
--------------------------------------------------------------------------------
```markdown
# Estimate Messages
## The Estimate Message Object
### Attributes:
- id (integer): Unique ID for the message
- sent_by (string): Name of the user that created the message
- sent_by_email (string): Email of the user that created the message
- sent_from (string): Name of the user that the message was sent from
- sent_from_email (string): Email of the user that message was sent from
- recipients (array): Array of message recipients
- subject (string): The message subject
- body (string): The message body
- send_me_a_copy (boolean): Whether to email copy to current user
- event_type (string): Type of estimate event (send, accept, decline, re-open, view, invoice)
- created_at (datetime): Creation timestamp
- updated_at (datetime): Last update timestamp
### Message Recipient Object
- name (string): Name of the message recipient
- email (string): Email of the message recipient
## Required Permissions
Administrator or Manager with estimate permissions required.
## Available Endpoints
### List Messages for an Estimate
```
GET /v2/estimates/{ESTIMATE_ID}/messages
```
Parameters:
- updated_since (datetime): Filter by update date
- per_page (integer): Records per page (1-2000)
### Create a Message
```
POST /v2/estimates/{ESTIMATE_ID}/messages
```
Required Parameters:
- recipients (array): Array of recipient objects
Optional Parameters:
- subject (string): Message subject
- body (string): Message body
- send_me_a_copy (boolean): Send copy to current user
- event_type (string): Estimate event type
### Delete a Message
```
DELETE /v2/estimates/{ESTIMATE_ID}/messages/{MESSAGE_ID}
```
### Mark Draft as Sent
```
POST /v2/estimates/{ESTIMATE_ID}/messages
```
With event_type: "send"
### Mark as Accepted
```
POST /v2/estimates/{ESTIMATE_ID}/messages
```
With event_type: "accept"
### Mark as Declined
```
POST /v2/estimates/{ESTIMATE_ID}/messages
```
With event_type: "decline"
### Re-open Closed Estimate
```
POST /v2/estimates/{ESTIMATE_ID}/messages
```
With event_type: "re-open"
## Example Response
```json
{
"id": 2666240,
"sent_by": "Bob Powell",
"sent_by_email": "[email protected]",
"sent_from": "Bob Powell",
"sent_from_email": "[email protected]",
"send_me_a_copy": true,
"created_at": "2017-08-25T21:27:52Z",
"updated_at": "2017-08-25T21:27:52Z",
"recipients": [
{
"name": "Richard Roe",
"email": "[email protected]"
},
{
"name": "Bob Powell",
"email": "[email protected]"
}
],
"event_type": null,
"subject": "Estimate #1001",
"body": "Here is our estimate."
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/06_estimates/03_estimates.md:
--------------------------------------------------------------------------------
```markdown
# Estimates
## The Estimate Object
### Attributes:
- id (integer): Unique ID for the estimate
- client (object): Client ID and name
- line_items (array): Array of estimate line items
- creator (object): Creator's ID and name
- client_key (string): Used for public web invoice URL
- number (string): Estimate number
- purchase_order (string): PO number
- amount (decimal): Total amount including taxes/discounts
- tax (decimal): Tax percentage
- tax_amount (decimal): Calculated tax amount
- tax2 (decimal): Second tax percentage
- tax2_amount (decimal): Calculated second tax amount
- discount (decimal): Discount percentage
- discount_amount (decimal): Calculated discount amount
- subject (string): Estimate subject
- notes (string): Additional notes
- currency (string): Currency code
- state (string): Status (draft, sent, accepted, declined)
- issue_date (date): Date issued
- sent_at (datetime): When sent
- accepted_at (datetime): When accepted
- declined_at (datetime): When declined
- created_at (datetime): Creation timestamp
- updated_at (datetime): Last update timestamp
### Line Item Object
- id (integer): Unique ID for line item
- kind (string): Item category name
- description (string): Line item description
- quantity (integer): Unit quantity
- unit_price (decimal): Price per unit
- amount (decimal): Line total (quantity * unit_price)
- taxed (boolean): Whether tax applies
- taxed2 (boolean): Whether second tax applies
## Required Permissions
Administrator or Manager with estimate permissions required.
## Available Endpoints
### List All Estimates
```
GET /v2/estimates
```
Parameters:
- client_id (integer): Filter by client
- updated_since (datetime): Filter by update date
- from (date): Filter by issue date start
- to (date): Filter by issue date end
- state (string): Filter by state
- per_page (integer): Records per page (1-2000)
### Retrieve an Estimate
```
GET /v2/estimates/{ESTIMATE_ID}
```
### Create an Estimate
```
POST /v2/estimates
```
Required Parameters:
- client_id (integer)
Optional Parameters:
- number (string)
- purchase_order (string)
- tax (decimal)
- tax2 (decimal)
- discount (decimal)
- subject (string)
- notes (string)
- currency (string)
- issue_date (date)
- line_items (array)
### Update an Estimate
```
PATCH /v2/estimates/{ESTIMATE_ID}
```
Accepts all create parameters
### Delete an Estimate
```
DELETE /v2/estimates/{ESTIMATE_ID}
```
### Line Items Management
#### Create Line Item
```
PATCH /v2/estimates/{ESTIMATE_ID}
```
With line_items array containing new items
#### Update Line Item
```
PATCH /v2/estimates/{ESTIMATE_ID}
```
With line_items array containing item ID and updates
#### Delete Line Item
```
PATCH /v2/estimates/{ESTIMATE_ID}
```
With line_items array containing item ID and _destroy:true
```
--------------------------------------------------------------------------------
/llms-install.md:
--------------------------------------------------------------------------------
```markdown
# AI Installation Guide for Harvest MCP Server
This guide provides specific instructions for AI agents like Claude to help users install and configure the Harvest MCP server.
## Installation Steps
1. Dependencies:
- Verify Node.js is installed by running `node --version`
- If not installed, guide user to download from https://nodejs.org
2. Repository Setup:
```bash
git clone https://github.com/yourusername/harvest-mcp-server.git
cd harvest-mcp-server
npm install
npm run build
```
3. Harvest Credentials:
- Direct user to https://id.getharvest.com/developers
- Help them locate:
- Personal Access Token (under "Create New Personal Access Token")
- Account ID (shown at top of page)
4. Configuration:
- For VSCode users:
- Path: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- For Claude desktop app users:
- Path: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Configuration template:
```json
{
"mcpServers": {
"harvest": {
"command": "node",
"args": ["ABSOLUTE_PATH/build/index.js"],
"env": {
"HARVEST_ACCESS_TOKEN": "user's-token",
"HARVEST_ACCOUNT_ID": "user's-account-id",
"STANDARD_WORK_DAY_HOURS": "7.5",
"TIMEZONE": "Australia/Perth"
},
"disabled": false,
"autoApprove": []
}
}
}
```
## Verification Steps
1. Check server builds successfully:
```bash
npm run build
```
2. Verify configuration:
- Ensure all environment variables are set
- Confirm file paths are absolute
- Check timezone matches user's location
3. Test basic functionality:
- List projects: `List my projects`
- Simple time entry: `2 hours on Project X today`
- Leave request: `I'm off sick today`
## Troubleshooting
Common issues and solutions:
1. "HARVEST_ACCESS_TOKEN and HARVEST_ACCOUNT_ID environment variables are required"
- Verify credentials are correctly set in configuration
- Check for typos in token and account ID
2. "Could not find matching project"
- List available projects first
- Ensure project name matches exactly
3. Server not starting
- Verify absolute path in configuration
- Check Node.js is installed
- Ensure build completed successfully
## Configuration Options
Help users customize their installation:
1. Work Day Hours:
- Default: 7.5
- Can be changed via STANDARD_WORK_DAY_HOURS
2. Timezone:
- Default: Australia/Perth
- Use IANA timezone names
- Example alternatives:
- America/New_York
- Europe/London
- Asia/Tokyo
3. Leave Types:
- Default: Sick/Carer's Leave
- Matches "[LV] Leave" project
- Triggered by keywords: "sick", "ill", "unwell"
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/05_invoices/02_invoice_messages.md:
--------------------------------------------------------------------------------
```markdown
# Invoice Messages
## The Invoice Message Object
### Attributes:
- id (integer): Unique ID for the message
- sent_by (string): Name of the user that created the message
- sent_by_email (string): Email of the user that created the message
- sent_from (string): Name of the user that the message was sent from
- sent_from_email (string): Email of the user that message was sent from
- recipients (array): Array of message recipients
- subject (string): The message subject
- body (string): The message body
- include_link_to_client_invoice (boolean): DEPRECATED - True when payment_options assigned
- attach_pdf (boolean): Whether to attach invoice PDF to email
- send_me_a_copy (boolean): Whether to email copy to current user
- thank_you (boolean): Whether this is a thank you message
- event_type (string): Type of invoice event (close, draft, re-open, send)
- reminder (boolean): Whether this is a reminder message
- send_reminder_on (date): Date reminder email will be sent
- created_at (datetime): Creation timestamp
- updated_at (datetime): Last update timestamp
### Message Recipient Object
- name (string): Name of the message recipient
- email (string): Email of the message recipient
## Required Permissions
Administrator or Manager with invoice permissions required.
## Available Endpoints
### List Messages for an Invoice
```
GET /v2/invoices/{INVOICE_ID}/messages
```
Parameters:
- updated_since (datetime): Filter by update date
- per_page (integer): Records per page (1-2000)
### Create and Send Message
```
POST /v2/invoices/{INVOICE_ID}/messages
```
Parameters:
- recipients (array): Array of recipient objects
- subject (string): Message subject
- body (string): Message body
- attach_pdf (boolean): Attach PDF to email
- send_me_copy (boolean): Send copy to current user
- thank_you (boolean): Is thank you message
- event_type (string): Invoice event type
### Get Message Template
```
GET /v2/invoices/{INVOICE_ID}/messages/new
```
Parameters:
- thank_you (boolean): Get thank you message template
- reminder (boolean): Get reminder message template
### Delete Message
```
DELETE /v2/invoices/{INVOICE_ID}/messages/{MESSAGE_ID}
```
### Mark Draft as Sent
```
POST /v2/invoices/{INVOICE_ID}/messages
```
With event_type: "send"
### Mark as Closed
```
POST /v2/invoices/{INVOICE_ID}/messages
```
With event_type: "close"
### Re-open Closed Invoice
```
POST /v2/invoices/{INVOICE_ID}/messages
```
With event_type: "re-open"
### Mark as Draft
```
POST /v2/invoices/{INVOICE_ID}/messages
```
With event_type: "draft"
## Example Response
```json
{
"id": 27835324,
"sent_by": "Bob Powell",
"sent_by_email": "[email protected]",
"sent_from": "Bob Powell",
"sent_from_email": "[email protected]",
"include_link_to_client_invoice": false,
"send_me_a_copy": true,
"thank_you": false,
"reminder": false,
"send_reminder_on": null,
"created_at": "2017-08-23T22:25:59Z",
"updated_at": "2017-08-23T22:25:59Z",
"attach_pdf": true,
"event_type": null,
"recipients": [
{
"name": "Richard Roe",
"email": "[email protected]"
},
{
"name": "Bob Powell",
"email": "[email protected]"
}
],
"subject": "Invoice #1001",
"body": "The invoice is attached below."
}
```
--------------------------------------------------------------------------------
/src/setup.ts:
--------------------------------------------------------------------------------
```typescript
#!/usr/bin/env node
import * as readline from 'readline';
import * as fs from 'fs';
import * as path from 'path';
import * as os from 'os';
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout
});
const question = (query: string): Promise<string> => {
return new Promise((resolve) => {
rl.question(query, resolve);
});
};
async function setup() {
console.log('\n🌱 Harvest MCP Server Setup\n');
// Get Harvest credentials
console.log('First, we need your Harvest credentials.');
console.log('You can find these at: https://id.getharvest.com/developers\n');
const token = await question('Personal Access Token: ');
const accountId = await question('Account ID: ');
// Get work day configuration
console.log('\nNow, let\'s configure your work day settings.\n');
const hours = await question('Standard work day hours (default: 7.5): ');
const timezone = await question('Timezone (default: Australia/Perth): ');
// Create configuration
const config = {
mcpServers: {
"harvest-server": {
command: "node",
args: [path.join(process.cwd(), "build/index.js")],
env: {
HARVEST_ACCESS_TOKEN: token,
HARVEST_ACCOUNT_ID: accountId,
STANDARD_WORK_DAY_HOURS: hours || '7.5',
TIMEZONE: timezone || 'Australia/Perth'
},
disabled: false,
autoApprove: []
}
}
};
// Determine Claude config paths
const desktopConfigPath = path.join(os.homedir(), 'Library/Application Support/Claude/claude_desktop_config.json');
const vscodeConfigPath = path.join(os.homedir(), 'Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json');
// Update Claude desktop config
try {
let existingConfig = {};
if (fs.existsSync(desktopConfigPath)) {
existingConfig = JSON.parse(fs.readFileSync(desktopConfigPath, 'utf8'));
}
const newConfig = {
...existingConfig,
mcpServers: {
...(existingConfig as any).mcpServers,
...config.mcpServers
}
};
fs.writeFileSync(desktopConfigPath, JSON.stringify(newConfig, null, 2));
console.log('\n✅ Claude desktop app configured successfully');
} catch (error) {
console.log('\n⚠️ Could not configure Claude desktop app');
console.log('You may need to add this configuration manually to:');
console.log(desktopConfigPath);
console.log('\nConfiguration to add:');
console.log(JSON.stringify(config, null, 2));
}
// Update VSCode config if it exists
try {
if (fs.existsSync(vscodeConfigPath)) {
let existingConfig = JSON.parse(fs.readFileSync(vscodeConfigPath, 'utf8'));
const newConfig = {
...existingConfig,
mcpServers: {
...(existingConfig as any).mcpServers,
...config.mcpServers
}
};
fs.writeFileSync(vscodeConfigPath, JSON.stringify(newConfig, null, 2));
console.log('✅ VSCode extension configured successfully');
}
} catch (error) {
// VSCode config is optional, so we don't show an error
}
console.log('\n🎉 Setup complete!');
console.log('\nPlease:');
console.log('1. Restart the Claude desktop app');
console.log('2. Try a test command like: "Show time report for this week"\n');
rl.close();
}
setup().catch(console.error);
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/01_introduction/04_supported_timezones.md:
--------------------------------------------------------------------------------
```markdown
# Supported Time Zones
The following time zones are supported via the v2 API. Use the **Harvest Name** of any `timezone` field to specify what time zone to use.
| Harvest Name | TZ Name | UTC Offset | UTC DST Offset |
|--------------|---------|------------|----------------|
| American Samoa | Pacific/Pago_Pago | -11:00 | -11:00 |
| International Date Line West | Pacific/Midway | -11:00 | -11:00 |
| Midway Island | Pacific/Midway | -11:00 | -11:00 |
| Hawaii | Pacific/Honolulu | -10:00 | -10:00 |
| Alaska | America/Juneau | -09:00 | -08:00 |
| Pacific Time (US & Canada) | America/Los_Angeles | -08:00 | -07:00 |
| Tijuana | America/Tijuana | -08:00 | -07:00 |
| Arizona | America/Phoenix | -07:00 | -07:00 |
| Mountain Time (US & Canada) | America/Denver | -07:00 | -06:00 |
| Central America | America/Guatemala | -06:00 | -06:00 |
| Central Time (US & Canada) | America/Chicago | -06:00 | -05:00 |
| Mexico City | America/Mexico_City | -06:00 | -05:00 |
| Saskatchewan | America/Regina | -06:00 | -06:00 |
| Bogota | America/Bogota | -05:00 | -05:00 |
| Eastern Time (US & Canada) | America/New_York | -05:00 | -04:00 |
| Indiana (East) | America/Indiana/Indianapolis | -05:00 | -04:00 |
| Lima | America/Lima | -05:00 | -05:00 |
| Atlantic Time (Canada) | America/Halifax | -04:00 | -03:00 |
| Caracas | America/Caracas | -04:00 | -04:00 |
| La Paz | America/La_Paz | -04:00 | -04:00 |
| Santiago | America/Santiago | -03:00 | -04:00 |
| Newfoundland | America/St_Johns | -03:30 | -02:30 |
| Brasilia | America/Sao_Paulo | -02:00 | -03:00 |
| Buenos Aires | America/Argentina/Buenos_Aires | -03:00 | -03:00 |
| Mid-Atlantic | Atlantic/South_Georgia | -02:00 | -02:00 |
| Azores | Atlantic/Azores | -01:00 | +00:00 |
| Dublin | Europe/Dublin | +00:00 | +01:00 |
| London | Europe/London | +00:00 | +01:00 |
| UTC | Etc/UTC | +00:00 | +00:00 |
| Amsterdam | Europe/Amsterdam | +01:00 | +02:00 |
| Berlin | Europe/Berlin | +01:00 | +02:00 |
| Paris | Europe/Paris | +01:00 | +02:00 |
| Prague | Europe/Prague | +01:00 | +02:00 |
| Rome | Europe/Rome | +01:00 | +02:00 |
| Stockholm | Europe/Stockholm | +01:00 | +02:00 |
| Vienna | Europe/Vienna | +01:00 | +02:00 |
| Athens | Europe/Athens | +02:00 | +03:00 |
| Helsinki | Europe/Helsinki | +02:00 | +03:00 |
| Kiev | Europe/Kiev | +02:00 | +03:00 |
| Minsk | Europe/Minsk | +03:00 | +03:00 |
| Moscow | Europe/Moscow | +03:00 | +03:00 |
| Istanbul | Europe/Istanbul | +03:00 | +03:00 |
| Dubai | Asia/Dubai | +04:00 | +04:00 |
| Tehran | Asia/Tehran | +03:30 | +04:30 |
| Kabul | Asia/Kabul | +04:30 | +04:30 |
| Karachi | Asia/Karachi | +05:00 | +05:00 |
| Mumbai | Asia/Kolkata | +05:30 | +05:30 |
| Kathmandu | Asia/Kathmandu | +05:45 | +05:45 |
| Dhaka | Asia/Dhaka | +06:00 | +06:00 |
| Bangkok | Asia/Bangkok | +07:00 | +07:00 |
| Jakarta | Asia/Jakarta | +07:00 | +07:00 |
| Singapore | Asia/Singapore | +08:00 | +08:00 |
| Hong Kong | Asia/Hong_Kong | +08:00 | +08:00 |
| Beijing | Asia/Shanghai | +08:00 | +08:00 |
| Tokyo | Asia/Tokyo | +09:00 | +09:00 |
| Seoul | Asia/Seoul | +09:00 | +09:00 |
| Adelaide | Australia/Adelaide | +10:30 | +09:30 |
| Darwin | Australia/Darwin | +09:30 | +09:30 |
| Brisbane | Australia/Brisbane | +10:00 | +10:00 |
| Sydney | Australia/Sydney | +11:00 | +10:00 |
| Vladivostok | Asia/Vladivostok | +10:00 | +10:00 |
| Solomon Is. | Pacific/Guadalcanal | +11:00 | +11:00 |
| Auckland | Pacific/Auckland | +13:00 | +12:00 |
| Fiji | Pacific/Fiji | +13:00 | +12:00 |
| Samoa | Pacific/Apia | +14:00 | +13:00 |
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/05_invoices/04_invoices.md:
--------------------------------------------------------------------------------
```markdown
# Invoices
## The Invoice Object
### Attributes:
- id (integer): Unique ID for the invoice
- client (object): Client ID and name
- line_items (array): Array of invoice line items
- estimate (object): Associated estimate ID
- retainer (object): Associated retainer ID
- creator (object): Creator's ID and name
- client_key (string): Used for public invoice URL
- number (string): Invoice number
- purchase_order (string): PO number
- amount (decimal): Total amount including taxes/discounts
- due_amount (decimal): Amount currently due
- tax (decimal): Tax percentage
- tax_amount (decimal): Calculated tax amount
- tax2 (decimal): Second tax percentage
- tax2_amount (decimal): Calculated second tax amount
- discount (decimal): Discount percentage
- discount_amount (decimal): Calculated discount amount
- subject (string): Invoice subject
- notes (string): Additional notes
- currency (string): Currency code
- state (string): Status (draft, open, paid, closed)
- period_start (date): Start of billing period
- period_end (date): End of billing period
- issue_date (date): Date issued
- due_date (date): Date due
- payment_term (string): Payment terms
- payment_options (array): Payment methods enabled
- sent_at (datetime): When sent
- paid_at (datetime): When paid
- paid_date (date): Date paid
- closed_at (datetime): When closed
- recurring_invoice_id (integer): Associated recurring invoice ID
- created_at (datetime): Creation timestamp
- updated_at (datetime): Last update timestamp
### Line Item Object
- id (integer): Unique ID for line item
- project (object): Associated project details
- kind (string): Item category name
- description (string): Line item description
- quantity (decimal): Unit quantity
- unit_price (decimal): Price per unit
- amount (decimal): Line total (quantity * unit_price)
- taxed (boolean): Whether tax applies
- taxed2 (boolean): Whether second tax applies
## Required Permissions
Administrator or Manager with invoice permissions required.
## Available Endpoints
### List All Invoices
```
GET /v2/invoices
```
Parameters:
- client_id (integer): Filter by client
- project_id (integer): Filter by project
- updated_since (datetime): Filter by update date
- from (date): Filter by issue date start
- to (date): Filter by issue date end
- state (string): Filter by state
- per_page (integer): Records per page (1-2000)
### Retrieve an Invoice
```
GET /v2/invoices/{INVOICE_ID}
```
### Create a Free-form Invoice
```
POST /v2/invoices
```
Required Parameters:
- client_id (integer)
Optional Parameters:
- retainer_id (integer)
- estimate_id (integer)
- number (string)
- purchase_order (string)
- tax (decimal)
- tax2 (decimal)
- discount (decimal)
- subject (string)
- notes (string)
- currency (string)
- issue_date (date)
- due_date (date)
- payment_term (string)
- payment_options (array)
- line_items (array)
### Create an Invoice from Time/Expenses
```
POST /v2/invoices
```
Additional Parameters for Import:
- line_items_import (object):
- project_ids (array)
- time (object):
- summary_type (string)
- from/to (date)
- expenses (object):
- summary_type (string)
- from/to (date)
- attach_receipts (boolean)
### Update an Invoice
```
PATCH /v2/invoices/{INVOICE_ID}
```
Accepts all create parameters
### Delete an Invoice
```
DELETE /v2/invoices/{INVOICE_ID}
```
### Line Items Management
#### Create Line Item
```
PATCH /v2/invoices/{INVOICE_ID}
```
With line_items array containing new items
#### Update Line Item
```
PATCH /v2/invoices/{INVOICE_ID}
```
With line_items array containing item ID and updates
#### Delete Line Item
```
PATCH /v2/invoices/{INVOICE_ID}
```
With line_items array containing item ID and _destroy:true
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/12_users/teammates.md:
--------------------------------------------------------------------------------
```markdown
User Teammates
The teammate object⚭
Attribute Type Description
id int Unique ID for the teammate
first_name string The first name of the teammate
last_name string The last name of the teammate
email string The email of the teammate
Required permissions⚭
You must be an Administrator in order to interact with the /v2/users/{USER_ID}/teammates endpoint. Insufficient permissions will result in a 403 Forbidden status code.
List all assigned teammates for a specific user⚭
Returns a list of assigned teammates for the user identified by USER_ID. The USER_ID must belong to a user that is a Manager, if not, a 422 Unprocessable Entity status code will be returned.
The response contains an object with a teammates property that contains an array of up to per_page teammates. Each entry in the array is a separate teammate object. If no more teammates are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your teammates.
GET /v2/users/{USER_ID}/teammates
Parameter Type Description
page integer DEPRECATED The page number to use in pagination. For instance, if you make a list request and receive 100 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
This endpoint supports cursor-based pagination and therefore deprecates the page parameter. For more information, visit the pagination guide.
Example Request:
curl "https://api.harvestapp.com/v2/users/1782959/teammates" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"teammates":[
{
"id":3230547,
"first_name":"Jim",
"last_name":"Allen",
"email":"[email protected]"
},
{
"id":1782884,
"first_name":"Bob",
"last_name":"Powell",
"email":"[email protected]"
}
],
"per_page":100,
"total_pages":1,
"total_entries":2,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/users/1782959/teammates?page=1&per_page=100",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/users/1782959/teammates?page=1&per_page=100"
}
}
Update a user’s assigned teammates⚭
Updates the the assigned teammates for a specific user. Returns list of assigned teammates and a 200 OK response code if the call succeeded. The USER_ID must belong to a user that is a Manager, if not, a 422 Unprocessable Entity status code will be returned.
Adding teammates for the first time will add the people_manager access role to the Manager. Any IDs not included in the teammate_ids that are currently assigned will be unassigned from the Manager. Use an empty array to unassign all users. This will also remove the people_manager access role from the Manager.
PATCH /v2/users/{USER_ID}/teammates
Parameter Type Required Description
teammate_ids array of user ids required Full list of user IDs to be assigned to the Manager.
Example Request:
curl "https://api.harvestapp.com/v2/users/1782959/teammates" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"teammate_ids":[3230547, 3230575]}'
Example Response
{
"teammates":[
{
"id":3230547,
"first_name":"Jim",
"last_name":"Allen",
"email":"[email protected]"
},
{
"id":3230575,
"first_name": "Gary",
"last_name": "Brookes",
"email": "[email protected]"
}
]
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/13_reports/project_budget.md:
--------------------------------------------------------------------------------
```markdown
Project Budget Report
The Project Budget Report highlights budget information for projects that have been assigned a budget.
Who can see what in the Project Budget Report?
Administrators can see all projects in the Project Budget Report.
Project Managers can see projects they manage and assigned projects they do not manage that have been set to Show project report to everyone on the project.
Regular Users can only see assigned projects that have been set to Show project report to everyone on the project.
The result object⚭
Attribute Type Description
client_id integer The ID of the client associated with this project.
client_name string The name of the client associated with this project.
project_id integer The ID of the project.
project_name string The name of the project.
budget_is_monthly boolean Whether the budget is reset every month.
budget_by string The method by which the project is budgeted. Options: project (Hours Per Project), project_cost (Total Project Fees), task (Hours Per Task), task_fees (Fees Per Task), person (Hours Per Person), none (No Budget).
is_active boolean Whether the project is active or archived.
budget decimal The budget in hours or money for the project when budgeting by time. If the project is budgeted by money, this value will only be visible to Administrators and Project Managers with the View billable rates and amounts permission.
budget_spent decimal The total hours or money spent against the project’s budget. If Time Rounding is turned on, the hours will be rounded according to your settings. If the project is budgeted by money, this value will only be visible to Administrators and Project Managers with the View billable rates and amounts permission.
budget_remaining decimal The total hours or money remaining in the project’s budget. If Time Rounding is turned on, the hours will be rounded according to your settings. If the project is budgeted by money, this value will only be visible to Administrators and Project Managers with the View billable rates and amounts permission.
Project Budget Report⚭
The response contains an object with a results property that contains an array of up to per_page results. Each entry in the array is a separate result object. If no more results are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your results.
GET /v2/reports/project_budget
Parameter Type Required Description
page integer optional The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer optional The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
is_active boolean optional Pass true to only return active projects and false to return inactive projects.
Example Request:
curl
"https://api.harvestapp.com/v2/reports/project_budget" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"results": [
{
"project_id": 14308069,
"project_name": "Online Store - Phase 1",
"client_id": 5735776,
"client_name": "123 Industries",
"budget_is_monthly": false,
"budget_by": "project",
"is_active": true,
"budget": 200,
"budget_spent": 4,
"budget_remaining": 196
},
{
"project_id": 14307913,
"project_name": "Marketing Website",
"client_id": 5735774,
"client_name": "ABC Corp",
"budget_is_monthly": false,
"budget_by": "project",
"is_active": true,
"budget": 50,
"budget_spent": 2,
"budget_remaining": 48
}
],
"per_page": 2000,
"total_pages": 1,
"total_entries": 2,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/reports/project_budget?page=1&per_page=2000",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/reports/project_budget?page=1&per_page=2000"
}
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/13_reports/uninvoiced.md:
--------------------------------------------------------------------------------
```markdown
Uninvoiced Report
The Uninvoiced Report highlights the uninvoiced hours and expenses for all billable projects in a given timeframe.
The result object⚭
Attribute Type Description
client_id integer The ID of the client associated with the reported hours and expenses.
client_name string The name of the client associated with the reported hours and expenses.
project_id integer The ID of the project associated with the reported hours and expenses.
project_name string The name of the project associated with the reported hours and expenses.
currency string The currency code associated with the tracked hours for this result.
total_hours decimal The total hours for the given timeframe and project. If Time Rounding is turned on, the hours will be rounded according to your settings.
uninvoiced_hours decimal The total hours for the given timeframe and project that have not been invoiced. If Time Rounding is turned on, the hours will be rounded according to your settings.
uninvoiced_expenses decimal The total amount for billable expenses for the timeframe and project that have not been invoiced.
uninvoiced_amount decimal The total amount (time and expenses) for the timeframe and project that have not been invoiced.
Required permissions⚭
Administrators can see all projects in the Uninvoiced Report. Managers with permission to create invoices can only see projects they manage.
Uninvoiced Report⚭
The response contains an object with a results property that contains an array of up to per_page results. Each entry in the array is a separate result object. If no more results are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your results.
Note: Each request requires both the from and to parameters to be supplied in the URL’s query string. The timeframe supplied cannot exceed 1 year (365 days).
GET /v2/reports/uninvoiced
Parameter Type Required Description
from date required Only report on time entries and expenses with a spent_date on or after the given date.
to date required Only report on time entries and expenses with a spent_date on or before the given date.
include_fixed_fee boolean optional Whether or not to include fixed-fee projects in the response. (Default: true)
page integer optional The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer optional The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
Example Request:
curl
"https://api.harvestapp.com/v2/reports/uninvoiced?from=20170101&to=20171231" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"results": [
{
"client_id": 5735776,
"client_name": "123 Industries",
"project_id": 14308069,
"project_name": "Online Store - Phase 1",
"currency": "EUR",
"total_hours": 4,
"uninvoiced_hours": 0,
"uninvoiced_expenses": 100,
"uninvoiced_amount": 100
},
{
"client_id": 5735776,
"client_name": "123 Industries",
"project_id": 14808188,
"project_name": "Task Force",
"currency": "EUR",
"total_hours": 0.5,
"uninvoiced_hours": 0.5,
"uninvoiced_expenses": 0,
"uninvoiced_amount": 50
},
{
"client_id": 5735774,
"client_name": "ABC Corp",
"project_id": 14307913,
"project_name": "Marketing Website",
"currency": "USD",
"total_hours": 2,
"uninvoiced_hours": 0,
"uninvoiced_expenses": 0,
"uninvoiced_amount": 0
}
],
"per_page": 2000,
"total_pages": 1,
"total_entries": 3,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/reports/uninvoiced?from=20170101&page=1&per_page=2000&to=20171231",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/reports/uninvoiced?from=20170101&page=1&per_page=2000&to=20171231"
}
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/01_introduction/05_supported_currencies.md:
--------------------------------------------------------------------------------
```markdown
# Supported Currencies
The following currencies are supported via the v2 API. Use the code in any `currency` field to specify what currency to use.
| Name | Code |
|------|------|
| United States Dollar | USD |
| Euro | EUR |
| British Pound | GBP |
| Australian Dollar | AUD |
| Canadian Dollar | CAD |
| Japanese Yen | JPY |
| United Arab Emirates Dirham | AED |
| Afghan Afghani | AFN |
| Albanian Lek | ALL |
| Armenian Dram | AMD |
| Netherlands Antillean Gulden | ANG |
| Angolan Kwanza | AOA |
| Argentine Peso | ARS |
| Aruban Florin | AWG |
| Azerbaijani Manat | AZN |
| Bosnia and Herzegovina Convertible Mark | BAM |
| Barbadian Dollar | BBD |
| Bangladeshi Taka | BDT |
| Bulgarian Lev | BGN |
| Bahraini Dinar | BHD |
| Burundian Franc | BIF |
| Bermudian Dollar | BMD |
| Brunei Dollar | BND |
| Bolivian Boliviano | BOB |
| Brazilian Real | BRL |
| Bahamian Dollar | BSD |
| Bhutanese Ngultrum | BTN |
| Botswana Pula | BWP |
| Belarusian Ruble | BYN |
| Belarusian Ruble | BYR |
| Belize Dollar | BZD |
| Congolese Franc | CDF |
| Swiss Franc | CHF |
| Chilean Peso | CLP |
| Chinese Renminbi Yuan | CNY |
| Colombian Peso | COP |
| Costa Rican Colón | CRC |
| Cuban Peso | CUP |
| Cape Verdean Escudo | CVE |
| Czech Koruna | CZK |
| Djiboutian Franc | DJF |
| Danish Krone | DKK |
| Dominican Peso | DOP |
| Algerian Dinar | DZD |
| Egyptian Pound | EGP |
| Eritrean Nakfa | ERN |
| Ethiopian Birr | ETB |
| Fijian Dollar | FJD |
| Falkland Pound | FKP |
| Georgian Lari | GEL |
| Ghanaian Cedi | GHS |
| Gibraltar Pound | GIP |
| Gambian Dalasi | GMD |
| Guinean Franc | GNF |
| Guatemalan Quetzal | GTQ |
| Guyanese Dollar | GYD |
| Hong Kong Dollar | HKD |
| Honduran Lempira | HNL |
| Croatian Kuna | HRK |
| Haitian Gourde | HTG |
| Hungarian Forint | HUF |
| Indonesian Rupiah | IDR |
| Israeli New Sheqel | ILS |
| Indian Rupee | INR |
| Iraqi Dinar | IQD |
| Iranian Rial | IRR |
| Icelandic Króna | ISK |
| Jamaican Dollar | JMD |
| Jordanian Dinar | JOD |
| Kenyan Shilling | KES |
| Kyrgyzstani Som | KGS |
| Cambodian Riel | KHR |
| Comorian Franc | KMF |
| North Korean Won | KPW |
| South Korean Won | KRW |
| Kuwaiti Dinar | KWD |
| Cayman Islands Dollar | KYD |
| Kazakhstani Tenge | KZT |
| Lao Kip | LAK |
| Lebanese Pound | LBP |
| Sri Lankan Rupee | LKR |
| Liberian Dollar | LRD |
| Lesotho Loti | LSL |
| Lithuanian Litas | LTL |
| Latvian Lats | LVL |
| Libyan Dinar | LYD |
| Moroccan Dirham | MAD |
| Moldovan Leu | MDL |
| Malagasy Ariary | MGA |
| Macedonian Denar | MKD |
| Myanmar Kyat | MMK |
| Mongolian Tögrög | MNT |
| Macanese Pataca | MOP |
| Mauritanian Ouguiya | MRO |
| Mauritian Rupee | MUR |
| Maldivian Rufiyaa | MVR |
| Malawian Kwacha | MWK |
| Mexican Peso | MXN |
| Malaysian Ringgit | MYR |
| Mozambican Metical | MZN |
| Namibian Dollar | NAD |
| Nigerian Naira | NGN |
| Nicaraguan Córdoba | NIO |
| Norwegian Krone | NOK |
| Nepalese Rupee | NPR |
| New Zealand Dollar | NZD |
| Omani Rial | OMR |
| Panamanian Balboa | PAB |
| Peruvian Sol | PEN |
| Papua New Guinean Kina | PGK |
| Philippine Peso | PHP |
| Pakistani Rupee | PKR |
| Polish Złoty | PLN |
| Paraguayan Guaraní | PYG |
| Qatari Riyal | QAR |
| Romanian Leu | RON |
| Serbian Dinar | RSD |
| Russian Ruble | RUB |
| Rwandan Franc | RWF |
| Saudi Riyal | SAR |
| Solomon Islands Dollar | SBD |
| Seychellois Rupee | SCR |
| Sudanese Pound | SDG |
| Swedish Krona | SEK |
| Singapore Dollar | SGD |
| Saint Helenian Pound | SHP |
| Sierra Leonean Leone | SLL |
| Somali Shilling | SOS |
| Surinamese Dollar | SRD |
| South Sudanese Pound | SSP |
| São Tomé and Príncipe Dobra | STD |
| Salvadoran Colón | SVC |
| Syrian Pound | SYP |
| Swazi Lilangeni | SZL |
| Thai Baht | THB |
| Tajikistani Somoni | TJS |
| Turkmenistani Manat | TMT |
| Tunisian Dinar | TND |
| Tongan Paʻanga | TOP |
| Turkish Lira | TRY |
| Trinidad and Tobago Dollar | TTD |
| New Taiwan Dollar | TWD |
| Tanzanian Shilling | TZS |
| Ukrainian Hryvnia | UAH |
| Ugandan Shilling | UGX |
| Uruguayan Peso | UYU |
| Uzbekistan Som | UZS |
| Venezuelan Bolívar | VEF |
| Vietnamese Đồng | VND |
| Vanuatu Vatu | VUV |
| Samoan Tala | WST |
| Central African CFA Franc | XAF |
| East Caribbean Dollar | XCD |
| West African CFA Franc | XOF |
| CFP Franc | XPF |
| Yemeni Rial | YER |
| South African Rand | ZAR |
| Zambian Kwacha | ZMW |
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/12_users/cost_rates.md:
--------------------------------------------------------------------------------
```markdown
User Cost Rates
The cost rate object⚭
Attribute Type Description
id integer Unique ID for the cost rate.
amount decimal The amount of the cost rate.
start_date date The date the cost rate is effective.
end_date date The date the cost rate is no longer effective. This date is calculated by Harvest.
created_at datetime Date and time the cost rate was created.
updated_at datetime Date and time the cost rate was last updated.
Required permissions⚭
You must be an Administrator in order to interact with the /v2/users/{USER_ID}/cost_rates endpoint. Insufficient permissions will result in a 403 Forbidden status code.
List all cost rates for a specific user⚭
Returns a list of cost rates for the user identified by USER_ID. The cost rates are returned sorted by start_date, with the oldest starting cost rates appearing first.
The response contains an object with a cost_rates property that contains an array of up to per_page cost rates. Each entry in the array is a separate cost rate object. If no more cost rates are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your cost rates.
GET /v2/users/{USER_ID}/cost_rates
Parameter Type Description
page integer DEPRECATED The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
This endpoint supports cursor-based pagination and therefore deprecates the page parameter. For more information, visit the pagination guide.
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/users/3226125/cost_rates" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Copy to Clipboard
Example response:⚭
{
"cost_rates": [
{
"id": 825301,
"amount": 9.25,
"start_date": "2019-01-01",
"end_date": "2019-05-31",
"created_at": "2020-05-01T13:19:09Z",
"updated_at": "2020-05-01T13:19:17Z"
},
{
"id": 825302,
"amount": 11.0,
"start_date": "2019-06-01",
"end_date": "2019-12-31",
"created_at": "2020-05-01T13:19:17Z",
"updated_at": "2020-05-01T13:19:24Z"
},
{
"id": 825303,
"amount": 12.5,
"start_date": "2020-01-01",
"end_date": "2020-04-30",
"created_at": "2020-05-01T13:19:24Z",
"updated_at": "2020-05-01T13:19:31Z"
},
{
"id": 825304,
"amount": 15.25,
"start_date": "2020-05-01",
"end_date": null,
"created_at": "2020-05-01T13:19:31Z",
"updated_at": "2020-05-01T13:19:31Z"
}
],
"per_page": 2000,
"total_pages": 1,
"total_entries": 4,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/users/3226125/cost_rates?page=1&per_page=2000",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/users/3226125/cost_rates?page=1&per_page=2000"
}
}
Retrieve a cost rate⚭
Retrieves the cost rate with the given ID. Returns a cost rate object and a 200 OK response code if a valid identifier was provided.
GET /v2/users/{USER_ID}/cost_rates/{COST_RATE_ID}
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/users/3226125/cost_rates/125068554" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Copy to Clipboard
Example response:⚭
{
"id": 825301,
"amount": 9.25,
"start_date": "2019-01-01",
"end_date": "2019-05-31",
"created_at": "2020-05-01T13:19:09Z",
"updated_at": "2020-05-01T13:19:17Z"
}
Create a cost rate⚭
Creates a new cost rate object. Returns a cost rate object and a 201 Created response code if the call succeeded.
Creating a cost rate with no start_date will replace a user’s existing rate(s).
Creating a cost rate with a start_date that is before a user’s existing rate(s) will replace those cost rates with the new one.
POST /v2/users/{USER_ID}/cost_rates
Parameter Type Required Description
amount decimal required The amount of the cost rate.
start_date date optional The date the cost rate is effective. Cannot be a date in the future.
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/users/3226125/cost_rates" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X POST \
-H "Content-Type: application/json" \
-d '{"amount":13.0,"start_date":"2020-04-05"}'
Copy to Clipboard
Example response:⚭
{
"id": 825305,
"amount": 13.0,
"start_date": "2020-04-05",
"end_date": null,
"created_at": "2020-05-01T13:23:27Z",
"updated_at": "2020-05-01T13:23:27Z"
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/12_users/billable_rates.md:
--------------------------------------------------------------------------------
```markdown
User Billable Rates
The billable rate object⚭
Attribute Type Description
id integer Unique ID for the billable rate.
amount decimal The amount of the billable rate.
start_date date The date the billable rate is effective.
end_date date The date the billable rate is no longer effective. This date is calculated by Harvest.
created_at datetime Date and time the billable rate was created.
updated_at datetime Date and time the billable rate was last updated.
Required permissions⚭
You must be an Administrator or Manager with permission to edit billable rates in order to interact with the /v2/users/{USER_ID}/billable_rates endpoint. Insufficient permissions will result in a 403 Forbidden status code.
List all billable rates for a specific user⚭
Returns a list of billable rates for the user identified by USER_ID. The billable rates are returned sorted by start_date, with the oldest starting billable rates appearing first.
The response contains an object with a billable_rates property that contains an array of up to per_page billable rates. Each entry in the array is a separate billable rate object. If no more billable rates are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your billable rates.
GET /v2/users/{USER_ID}/billable_rates
Parameter Type Description
page integer DEPRECATED The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
This endpoint supports cursor-based pagination and therefore deprecates the page parameter. For more information, visit the pagination guide.
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/users/3226125/billable_rates" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Copy to Clipboard
Example response:⚭
{
"billable_rates": [
{
"id": 1836493,
"amount": 8.25,
"start_date": "2019-01-01",
"end_date": "2019-05-31",
"created_at": "2020-05-01T13:17:42Z",
"updated_at": "2020-05-01T13:17:50Z"
},
{
"id": 1836494,
"amount": 9.5,
"start_date": "2019-06-01",
"end_date": "2019-12-31",
"created_at": "2020-05-01T13:17:50Z",
"updated_at": "2020-05-01T13:18:02Z"
},
{
"id": 1836495,
"amount": 9.5,
"start_date": "2020-01-01",
"end_date": "2020-04-30",
"created_at": "2020-05-01T13:18:02Z",
"updated_at": "2020-05-01T13:18:10Z"
},
{
"id": 1836496,
"amount": 15.0,
"start_date": "2020-05-01",
"end_date": null,
"created_at": "2020-05-01T13:18:10Z",
"updated_at": "2020-05-01T13:18:10Z"
}
],
"per_page": 2000,
"total_pages": 1,
"total_entries": 4,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/users/3226125/billable_rates?page=1&per_page=2000",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/users/3226125/billable_rates?page=1&per_page=2000"
}
}
Retrieve a billable rate⚭
Retrieves the billable rate with the given ID. Returns a billable rate object and a 200 OK response code if a valid identifier was provided.
GET /v2/users/{USER_ID}/billable_rates/{billable_RATE_ID}
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/users/3226125/billable_rates/1836493" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Copy to Clipboard
Example response:⚭
{
"id": 1836493,
"amount": 8.25,
"start_date": "2019-01-01",
"end_date": "2019-05-31",
"created_at": "2020-05-01T13:17:42Z",
"updated_at": "2020-05-01T13:17:50Z"
}
Create a billable rate⚭
Creates a new billable rate object. Returns a billable rate object and a 201 Created response code if the call succeeded.
Creating a billable rate with no start_date will replace a user’s existing rate(s).
Creating a billable rate with a start_date that is before a user’s existing rate(s) will replace those billable rates with the new one.
POST /v2/users/{USER_ID}/billable_rates
Parameter Type Required Description
amount decimal required The amount of the billable rate.
start_date date optional The date the billable rate is effective. Cannot be a date in the future.
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/users/3226125/billable_rates" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X POST \
-H "Content-Type: application/json" \
-d '{"amount":5.0,"start_date":"2020-05-05"}'
Copy to Clipboard
Example response:⚭
{
"id": 1836555,
"amount": 5.0,
"start_date": 2020-05-01,
"end_date": null,
"created_at": "2020-05-01T15:04:20Z",
"updated_at": "2020-05-01T15:04:20Z"
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/11_roles/roles.md:
--------------------------------------------------------------------------------
```markdown
Roles
The role object⚭
Attribute Type Description
id integer Unique ID for the role.
name string The name of the role.
user_ids array of integers The IDs of the users assigned to this role.
created_at datetime Date and time the role was created.
updated_at datetime Date and time the role was last updated.
Required permissions⚭
You must be an Administrator in order to interact with the /v2/roles endpoint. Insufficient permissions will result in a 403 Forbidden status code.
List all roles⚭
Returns a list of roles in the account. The roles are returned sorted by creation date, with the most recently created roles appearing first.
The response contains an object with a roles property that contains an array of up to per_page roles. Each entry in the array is a separate role object. If no more roles are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your roles.
GET /v2/roles
Parameter Type Description
page integer DEPRECATED The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
This endpoint supports cursor-based pagination and therefore deprecates the page parameter. For more information, visit the pagination guide.
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/roles" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Copy to Clipboard
Example response:⚭
{
"roles": [
{
"id": 618100,
"name": "Designer",
"created_at": "2020-04-17T10:09:41Z",
"updated_at": "2020-04-17T10:09:41Z",
"user_ids": []
},
{
"id": 618099,
"name": "Developer",
"created_at": "2020-04-17T10:08:43Z",
"updated_at": "2020-04-17T10:08:43Z",
"user_ids": []
},
{
"id": 617630,
"name": "Sales",
"created_at": "2020-04-16T16:59:59Z",
"updated_at": "2020-04-16T16:59:59Z",
"user_ids": [
2084359,
3122373,
3122374
]
}
],
"per_page": 2000,
"total_pages": 1,
"total_entries": 2,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/roles?page=1&per_page=2000",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/roles?page=1&per_page=2000"
}
}
Retrieve a role⚭
Retrieves the role with the given ID. Returns a role object and a 200 OK response code if a valid identifier was provided.
GET /v2/roles/{ROLE_ID}
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/roles/617630" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Copy to Clipboard
Example response:⚭
{
"id": 617630,
"name": "Sales",
"created_at": "2020-04-16T16:59:59Z",
"updated_at": "2020-04-16T16:59:59Z",
"user_ids": [
2084359,
3122373,
3122374
]
}
Create a role⚭
Creates a new role object. Returns a role object and a 201 Created response code if the call succeeded.
POST /v2/roles
Parameter Type Required Description
name string required The name of the role.
user_ids array of integers optional The IDs of the users assigned to this role.
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/roles" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X POST \
-H "Content-Type: application/json" \
-d '{"name":"Marketing","user_ids":[3122374,3122373,2084359]}'
Copy to Clipboard
Example response:⚭
{
"id": 617670,
"name": "Marketing",
"created_at": "2020-04-16T18:18:30Z",
"updated_at": "2020-04-16T18:18:30Z",
"user_ids": [
3122374,
3122373,
2084359
]
}
Update a role⚭
Updates the specific role by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a role object and a 200 OK response code if the call succeeded.
PATCH /v2/roles/{ROLE_ID}
Parameter Type Required Description
name string optional The name of the role.
user_ids array of integers optional The IDs of the users assigned to this role.
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/roles/618099" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"name":"HR","user_ids":[2084359,3122373,3122374]}'
Copy to Clipboard
Example response:⚭
{
"id": 618099,
"name": "HR",
"created_at": "2020-04-16T17:00:38Z",
"updated_at": "2020-04-16T17:00:57Z",
"user_ids": [
2084359
]
}
Delete a role⚭
Delete a role. Deleting a role will unlink it from any users it was assigned to. Returns a 200 OK response code if the call succeeded.
DELETE /v2/roles/{ROLE_ID}
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/roles/617631" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X DELETE
Copy to Clipboard
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/07_expenses/expense_categories.md:
--------------------------------------------------------------------------------
```markdown
# Expense Categories
Admin permissions required.
## The expense category object
Attribute | Type | Description
--------- | ---- | -----------
`id` | integer | Unique ID for the expense category.
`name` | string | The name of the expense category.
`unit_name` | string | The unit name of the expense category.
`unit_price` | decimal | The unit price of the expense category.
`is_active` | boolean | Whether the expense category is active or archived.
`created_at` | datetime | Date and time the expense category was created.
`updated_at` | datetime | Date and time the expense category was last updated.
## List all expense categories
Returns a list of your expense categories. The expense categories are returned sorted by creation date, with the most recently created expense categories appearing first.
The response contains an object with a `expense_categories` property that contains an array of up to `per_page` expense categories. Each entry in the array is a separate expense category object. If no more expense categories are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your expense categories.
```
GET /v2/expense_categories
```
Parameter | Type | Description
--------- | ---- | -----------
`is_active` | boolean | Pass `true` to only return active expense categories and `false` to return inactive expense categories.
`updated_since` | datetime | Only return expense categories that have been updated since the given date and time.
`page` | integer | **DEPRECATED** The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include `page=2` to retrieve the next page of the list. (Default: 1)
`per_page` | integer | The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
This endpoint supports cursor-based pagination and therefore deprecates the `page` parameter. For more information, visit the [pagination guide](/api-v2/introduction/overview/pagination/).
### Example Request
```bash
curl "https://api.harvestapp.com/v2/expense_categories" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
```
### Example Response
```json
{
"expense_categories":[
{
"id":4197501,
"name":"Lodging",
"unit_name":null,
"unit_price":null,
"is_active":true,
"created_at":"2017-06-27T15:01:32Z",
"updated_at":"2017-06-27T15:01:32Z"
},
{
"id":4195930,
"name":"Mileage",
"unit_name":"mile",
"unit_price":0.535,
"is_active":true,
"created_at":"2017-06-26T20:41:00Z",
"updated_at":"2017-06-26T20:41:00Z"
},
{
"id":4195928,
"name":"Transportation",
"unit_name":null,
"unit_price":null,
"is_active":true,
"created_at":"2017-06-26T20:41:00Z",
"updated_at":"2017-06-26T20:41:00Z"
},
{
"id":4195926,
"name":"Meals",
"unit_name":null,
"unit_price":null,
"is_active":true,
"created_at":"2017-06-26T20:41:00Z",
"updated_at":"2017-06-26T20:41:00Z"
}
],
"per_page":2000,
"total_pages":1,
"total_entries":4,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/expense_categories?page=1&per_page=2000",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/expense_categories?page=1&per_page=2000"
}
}
```
## Retrieve an expense category
Retrieves the expense category with the given ID. Returns an expense category object and a `200 OK` response code if a valid identifier was provided.
```
GET /v2/expense_categories/{EXPENSE_CATEGORY_ID}
```
### Example Request
```bash
curl "https://api.harvestapp.com/v2/expense_categories/4197501" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
```
### Example Response
```json
{
"id":4197501,
"name":"Lodging",
"unit_name":null,
"unit_price":null,
"is_active":true,
"created_at":"2017-06-27T15:01:32Z",
"updated_at":"2017-06-27T15:01:32Z"
}
```
## Create an expense category
Creates a new expense category object. Returns an expense category object and a `201 Created` response code if the call succeeded.
```
POST /v2/expense_categories
```
Parameter | Type | Required | Description
--------- | ---- | -------- | -----------
`name` | string | required | The name of the expense category.
`unit_name` | string | optional | The unit name of the expense category.
`unit_price` | decimal | optional | The unit price of the expense category.
`is_active` | boolean | optional | Whether the expense category is active or archived. Defaults to `true`.
### Example Request
```bash
curl "https://api.harvestapp.com/v2/expense_categories" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X POST \
-H "Content-Type: application/json" \
-d '{"name":"Other"}'
```
### Example Response
```json
{
"id":4197514,
"name":"Other",
"unit_name":null,
"unit_price":null,
"is_active":true,
"created_at":"2017-06-27T15:04:23Z",
"updated_at":"2017-06-27T15:04:23Z"
}
```
## Update an expense category
Updates the specific expense category by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns an expense category object and a `200 OK` response code if the call succeeded.
```
PATCH /v2/expense_categories/{EXPENSE_CATEGORY_ID}
```
Parameter | Type | Description
--------- | ---- | -----------
`name` | string | The name of the expense category.
`unit_name` | string | The unit name of the expense category.
`unit_price` | decimal | The unit price of the expense category.
`is_active` | boolean | Whether the expense category is active or archived.
### Example Request
```bash
curl "https://api.harvestapp.com/v2/expense_categories/4197514" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"is_active":false}'
```
### Example Response
```json
{
"id":4197514,
"name":"Other",
"unit_name":null,
"unit_price":null,
"is_active":false,
"created_at":"2017-06-27T15:04:23Z",
"updated_at":"2017-06-27T15:04:58Z"
}
```
## Delete an expense category
Delete an expense category. Returns a `200 OK` response code if the call succeeded.
```
DELETE /v2/expense_categories/{EXPENSE_CATEGORY_ID}
```
### Example Request
```bash
curl "https://api.harvestapp.com/v2/expense_categories/4197514" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X DELETE
```
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/13_reports/expenses.md:
--------------------------------------------------------------------------------
```markdown
Expense Reports
Expense reports show expense totals for each client, project, expense category, or user, where expenses are present for a given timeframe.
The response contains an object with a results property that contains an array of up to per_page results. Each entry in the array is a separate result object. If no more results are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your results.
Note: Each expense report request requires both the from and to parameters to be supplied in the URL’s query string. The timeframe supplied cannot exceed 1 year (365 days).
The result object⚭
Attribute Type Description
client_id integer The ID of the client associated with the reported expenses. Only returned in the Client and Project reports.
client_name string The name of the client associated with the reported expenses. Only returned in the Client and Project reports.
project_id integer The ID of the project associated with the reported expenses. Only returned in the Client and Project reports.
project_name string The name of the project associated with the reported expenses. Only returned in the Client and Project reports.
expense_category_id integer The ID of the expense category associated with the reported expenses. Only returned in the Expense Category report.
expense_category_name string The name of the expense category associated with the reported expenses. Only returned in the Expense Category report.
user_id integer The ID of the user associated with the reported expenses. Only returned in the Team report.
user_name string The name of the user associated with the reported expenses. Only returned in the Team report.
is_contractor boolean The contractor status of the user associated with the reported expenses. Only returned in the Team report.
total_amount decimal The totaled cost for all expenses for the given timeframe, subject (client, project, expense category, or user), and currency.
billable_amount decimal The totaled cost for billable expenses for the given timeframe, subject (client, project, expense category, or user), and currency.
currency string The currency code associated with the expenses for this result.
Required permissions⚭
If you’re an Administrator, you’ll see all clients, projects, expense categories, and users for the account. Managers will see their own expenses, plus those for any projects or teammates they manage. Members will only see their own expenses.
Clients Report⚭
GET /v2/reports/expenses/clients
Parameter Type Required Description
from date required Only report on expenses with a spent_date on or after the given date.
to date required Only report on expenses with a spent_date on or before the given date.
page integer optional The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer optional The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
Example Request:
curl
"https://api.harvestapp.com/v2/reports/expenses/clients?from=20170101&to=20171231" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"results": [
{
"client_id": 5735776,
"client_name": "123 Industries",
"total_amount": 100,
"billable_amount": 100,
"currency": "EUR"
},
{
"client_id": 5735774,
"client_name": "ABC Corp",
"total_amount": 133.35,
"billable_amount": 133.35,
"currency": "USD"
}
],
"per_page": 2000,
"total_pages": 1,
"total_entries": 2,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/reports/expenses/clients?from=20170101&page=1&per_page=2000&to=20171231",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/reports/expenses/clients?from=20170101&page=1&per_page=2000&to=20171231"
}
}
Projects Report⚭
GET /v2/reports/expenses/projects
Parameter Type Required Description
from date required Only report on expenses with a spent_date on or after the given date.
to date required Only report on expenses with a spent_date on or before the given date.
page integer optional The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer optional The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
Example Request:
curl
"https://api.harvestapp.com/v2/reports/expenses/projects?from=20170101&to=20171231" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"results": [
{
"client_id": 5735774,
"client_name": "ABC Corp",
"project_id": 14307913,
"project_name": "[MW] Marketing Website",
"total_amount": 133.35,
"billable_amount": 133.35,
"currency": "USD"
},
{
"client_id": 5735776,
"client_name": "123 Industries",
"project_id": 14308069,
"project_name": "[OS1] Online Store - Phase 1",
"total_amount": 100,
"billable_amount": 100,
"currency": "EUR"
}
],
"per_page": 2000,
"total_pages": 1,
"total_entries": 2,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/reports/expenses/projects?from=20170101&page=1&per_page=2000&to=20171231",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/reports/expenses/projects?from=20170101&page=1&per_page=2000&to=20171231"
}
}
Expense Categories Report⚭
GET /v2/reports/expenses/categories
Parameter Type Required Description
from date required Only report on expenses with a spent_date on or after the given date.
to date required Only report on expenses with a spent_date on or before the given date.
page integer optional The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer optional The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
Example Request:
curl
"https://api.harvestapp.com/v2/reports/expenses/categories?from=20170101&to=20171231" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"results": [
{
"expense_category_id": 4197501,
"expense_category_name": "Lodging",
"total_amount": 100,
"billable_amount": 100,
"currency": "EUR"
},
{
"expense_category_id": 4195926,
"expense_category_name": "Meals",
"total_amount": 100,
"billable_amount": 100,
"currency": "EUR"
},
{
"expense_category_id": 4195926,
"expense_category_name": "Meals",
"total_amount": 33.35,
"billable_amount": 33.35,
"currency": "USD"
}
],
"per_page": 2000,
"total_pages": 1,
"total_entries": 3,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/reports/expenses/categories?from=20170101&page=1&per_page=2000&to=20171231",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/reports/expenses/categories?from=20170101&page=1&per_page=2000&to=20171231"
}
}
Team Report⚭
GET /v2/reports/expenses/team
Parameter Type Required Description
from date required Only report on expenses with a spent_date on or after the given date.
to date required Only report on expenses with a spent_date on or before the given date.
page integer optional The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer optional The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
Example Request:
curl
"https://api.harvestapp.com/v2/reports/expenses/team?from=20170101&to=20171231" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"results": [
{
"user_id": 1782884,
"user_name": "Bob Powell",
"is_contractor": false,
"total_amount": 100,
"billable_amount": 100,
"currency": "USD"
},
{
"user_id": 1782959,
"user_name": "Kim Allen",
"is_contractor": false,
"total_amount": 100,
"billable_amount": 100,
"currency": "EUR"
},
{
"user_id": 1782959,
"user_name": "Kim Allen",
"is_contractor": false,
"total_amount": 33.35,
"billable_amount": 33.35,
"currency": "USD"
}
],
"per_page": 2000,
"total_pages": 1,
"total_entries": 3,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/reports/expenses/team?from=20170101&page=1&per_page=2000&to=20171231",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/reports/expenses/team?from=20170101&page=1&per_page=2000&to=20171231"
}
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/13_reports/time.md:
--------------------------------------------------------------------------------
```markdown
Time Reports
Time reports show the hours and billable information for each client, project, task, or user, where tracked time is present for a given timeframe.
The response contains an object with a results property that contains an array of up to per_page results. Each entry in the array is a separate result object. If no more results are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your results.
Note: Each time report request requires both the from and to parameters to be supplied in the URL’s query string. The timeframe supplied cannot exceed 1 year (365 days).
The result object⚭
Attribute Type Description
client_id integer The ID of the client associated with the reported hours. Only returned in the Client and Project reports.
client_name string The name of the client associated with the reported hours. Only returned in the Client and Project reports.
project_id integer The ID of the project associated with the reported hours. Only returned in the Client and Project reports.
project_name string The name of the project associated with the reported hours. Only returned in the Client and Project reports.
task_id integer The ID of the task associated with the reported hours. Only returned in the Task report.
task_name string The name of the task associated with the reported hours. Only returned in the Task report.
user_id integer The ID of the user associated with the reported hours. Only returned in the Team report.
user_name string The name of the user associated with the reported hours. Only returned in the Team report.
weekly_capacity integer The number of hours per week this person is available to work in seconds, in half hour increments. For example, if a person’s capacity is 35 hours, the API will return 126000 seconds. Only returned in the Team report.
avatar_url string The URL to the user’s avatar image. Only returned in the Team report.
is_contractor boolean The contractor status of the user associated with the reported hours. Only returned in the Team report.
total_hours decimal The totaled hours for the given timeframe, subject (client, project, task, or user), and currency. If Time Rounding is turned on, the hours will be rounded according to your settings.
billable_hours decimal The totaled billable hours for the given timeframe, subject (client, project, task, or user), and currency. If Time Rounding is turned on, the hours will be rounded according to your settings.
currency string The currency code associated with the tracked hours for this result. Only visible to Administrators and Project Managers with the View billable rates and amounts permission.
billable_amount decimal The totaled billable amount for the billable hours above. Only visible to Administrators and Project Managers with the View billable rates and amounts permission.
Required permissions⚭
If you’re an Administrator, you’ll see all clients, projects, tasks, and users for the account. Managers will see their own tracked time, plus time tracked against any projects or teammates they manage. Members will only see their own tracked time.
Clients Report⚭
GET /v2/reports/time/clients
Parameter Type Required Description
from date required Only report on time entries with a spent_date on or after the given date.
to date required Only report on time entries with a spent_date on or before the given date.
include_fixed_fee string optional When true, billable amounts will be calculated and included for fixed fee projects.
page integer optional The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer optional The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
Example Request:
curl
"https://api.harvestapp.com/v2/reports/time/clients?from=20170101&to=20171231" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"results": [
{
"client_id": 5735776,
"client_name": "123 Industries",
"total_hours": 4.5,
"billable_hours": 3.5,
"currency": "EUR",
"billable_amount": 350
},
{
"client_id": 5735774,
"client_name": "ABC Corp",
"total_hours": 2,
"billable_hours": 2,
"currency": "USD",
"billable_amount": 200
}
],
"per_page": 2000,
"total_pages": 1,
"total_entries": 2,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/reports/time/clients?from=20170101&page=1&per_page=2000&to=20171231",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/reports/time/clients?from=20170101&page=1&per_page=2000&to=20171231"
}
}
Projects Report⚭
GET /v2/reports/time/projects
Parameter Type Required Description
from date required Only report on time entries with a spent_date on or after the given date.
to date required Only report on time entries with a spent_date on or before the given date.
include_fixed_fee string optional When true, billable amounts will be calculated and included for fixed fee projects.
page integer optional The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer optional The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
Example Request:
curl
"https://api.harvestapp.com/v2/reports/time/projects?from=20170101&to=20171231" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"results": [
{
"project_id": 14307913,
"project_name": "[MW] Marketing Website",
"client_id": 5735774,
"client_name": "ABC Corp",
"total_hours": 2,
"billable_hours": 2,
"currency": "USD",
"billable_amount": 200
},
{
"project_id": 14308069,
"project_name": "[OS1] Online Store - Phase 1",
"client_id": 5735776,
"client_name": "123 Industries",
"total_hours": 4,
"billable_hours": 3,
"currency": "EUR",
"billable_amount": 300
},
{
"project_id": 14808188,
"project_name": "[TF] Task Force",
"client_id": 5735776,
"client_name": "123 Industries",
"total_hours": 0.5,
"billable_hours": 0.5,
"currency": "EUR",
"billable_amount": 50
}
],
"per_page": 2000,
"total_pages": 1,
"total_entries": 3,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/reports/time/projects?from=20170101&page=1&per_page=2000&to=20171231",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/reports/time/projects?from=20170101&page=1&per_page=2000&to=20171231"
}
}
Tasks Report⚭
GET /v2/reports/time/tasks
Parameter Type Required Description
from date required Only report on time entries with a spent_date on or after the given date.
to date required Only report on time entries with a spent_date on or before the given date.
include_fixed_fee string optional When true, billable amounts will be calculated and included for fixed fee projects.
page integer optional The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer optional The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
Example Request:
curl
"https://api.harvestapp.com/v2/reports/time/tasks?from=20170101&to=20171231" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"results": [
{
"task_id": 8083365,
"task_name": "Graphic Design",
"total_hours": 2,
"billable_hours": 2,
"currency": "USD",
"billable_amount": 200
},
{
"task_id": 8083366,
"task_name": "Programming",
"total_hours": 1.5,
"billable_hours": 1.5,
"currency": "EUR",
"billable_amount": 150
},
{
"task_id": 8083368,
"task_name": "Project Management",
"total_hours": 1.5,
"billable_hours": 1.5,
"currency": "EUR",
"billable_amount": 150
},
{
"task_id": 8083368,
"task_name": "Project Management",
"total_hours": 0.5,
"billable_hours": 0.5,
"currency": "USD",
"billable_amount": 50
},
{
"task_id": 8083369,
"task_name": "Research",
"total_hours": 1,
"billable_hours": 0,
"currency": "EUR",
"billable_amount": 0
}
],
"per_page": 2000,
"total_pages": 1,
"total_entries": 5,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/reports/time/tasks?from=20170101&page=1&per_page=2000&to=20171231",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/reports/time/tasks?from=20170101&page=1&per_page=2000&to=20171231"
}
}
Team Report⚭
GET /v2/reports/time/team
Parameter Type Required Description
from date required Only report on time entries with a spent_date on or after the given date.
to date required Only report on time entries with a spent_date on or before the given date.
include_fixed_fee string optional When true, billable amounts will be calculated and included for fixed fee projects.
page integer optional The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer optional The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
Example Request:
curl
"https://api.harvestapp.com/v2/reports/time/team?from=20170101&to=20171231" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"results": [
{
"user_id": 1795925,
"user_name": "Jane Smith",
"is_contractor": false,
"total_hours": 0.5,
"billable_hours": 0.5,
"currency": "EUR",
"billable_amount": 50,
"weekly_capacity": 126000,
"avatar_url":"https://cache.harvestapp.com/assets/profile_images/abraj_albait_towers.png?1498516481"
},
{
"user_id": 1782959,
"user_name": "Kim Allen",
"is_contractor": false,
"total_hours": 4,
"billable_hours": 3,
"currency": "EUR",
"billable_amount": 300,
"weekly_capacity": 126000,
"avatar_url":"https://cache.harvestapp.com/assets/profile_images/cornell_clock_tower.png?1498515345"
},
{
"user_id": 1782959,
"user_name": "Kim Allen",
"is_contractor": false,
"total_hours": 2,
"billable_hours": 2,
"currency": "USD",
"billable_amount": 200,
"weekly_capacity": 126000,
"avatar_url":"https://cache.harvestapp.com/assets/profile_images/allen_bradley_clock_tower.png?1498509661"
}
],
"per_page": 2000,
"total_pages": 1,
"total_entries": 3,
"next_page": null,
"previous_page": null,
"page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/reports/time/team?from=20170101&page=1&per_page=2000&to=20171231",
"next": null,
"previous": null,
"last": "https://api.harvestapp.com/v2/reports/time/team?from=20170101&page=1&per_page=2000&to=20171231"
}
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/12_users/project_assignments.md:
--------------------------------------------------------------------------------
```markdown
User Project Assignments
The project assignment object⚭
Attribute Type Description
id integer Unique ID for the project assignment.
is_active boolean Whether the project assignment is active or archived.
is_project_manager boolean Determines if the user has Project Manager permissions for the project.
use_default_rates boolean Determines which billable rate(s) will be used on the project for this user when bill_by is People. When true, the project will use the user’s default billable rates. When false, the project will use the custom rate defined on this user assignment.
hourly_rate decimal Custom rate used when the project’s bill_by is People and use_default_rates is false.
budget decimal Budget used when the project’s budget_by is person.
created_at datetime Date and time the project assignment was created.
updated_at datetime Date and time the project assignment was last updated.
project object An object containing the assigned project id, name, and code.
client object An object containing the project’s client id and name.
task_assignments array Array of task assignment objects associated with the project.
Required permissions⚭
Anyone may access their own project assignments. The currently authenticated user, including Members, can use the /v2/users/{USER_ID}/project_assignments endpoint to view their own project assignments.
To access other people’s project assignments, you must be an Administrator, or Manager with assigned teammates, in order to interact with the /v2/users/{USER_ID}/project_assignments endpoint. Insufficient permissions will result in a 403 Forbidden status code.
List active project assignments⚭
Returns a list of active project assignments for the user identified by USER_ID. The project assignments are returned sorted by creation date, with the most recently created project assignments appearing first.
The response contains an object with a project_assignments property that contains an array of up to per_page project assignments. Each entry in the array is a separate project assignment object. If no more project assignments are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your project assignments.
GET /v2/users/{USER_ID}/project_assignments
Parameter Type Description
updated_since datetime Only return project assignments that have been updated since the given date and time.
page integer DEPRECATED The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
This endpoint supports cursor-based pagination and therefore deprecates the page parameter. For more information, visit the pagination guide.
Example Request:
curl "https://api.harvestapp.com/v2/users/1782959/project_assignments" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"project_assignments":[
{
"id":125068554,
"is_project_manager":true,
"is_active":true,
"use_default_rates":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"client":{
"id":5735776,
"name":"123 Industries"
},
"task_assignments":[
{
"id":155505013,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083365,
"name":"Graphic Design"
}
},
{
"id":155505014,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083366,
"name":"Programming"
}
},
{
"id":155505015,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083368,
"name":"Project Management"
}
},
{
"id":155505016,
"billable":false,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:54:06Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083369,
"name":"Research"
}
}
]
},
{
"id":125068553,
"is_project_manager":true,
"is_active":true,
"use_default_rates":false,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0,
"project":{
"id":14307913,
"name":"Marketing Website",
"code":"MW"
},
"client":{
"id":5735774,
"name":"ABC Corp"
},
"task_assignments":[
{
"id":155502709,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083365,
"name":"Graphic Design"
}
},
{
"id":155502710,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083366,
"name":"Programming"
}
},
{
"id":155502711,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083368,
"name":"Project Management"
}
},
{
"id":155505153,
"billable":false,
"is_active":true,
"created_at":"2017-06-26T21:53:20Z",
"updated_at":"2017-06-26T21:54:31Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083369,
"name":"Research"
}
}
]
}
],
"per_page":2000,
"total_pages":1,
"total_entries":2,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/users/1782959/project_assignments?page=1&per_page=2000",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/users/1782959/project_assignments?page=1&per_page=2000"
}
}
List active project assignments for the currently authenticated user⚭
Returns a list of your active project assignments for the currently authenticated user. The project assignments are returned sorted by creation date, with the most recently created project assignments appearing first.
The response contains an object with a project_assignments property that contains an array of up to per_page project assignments. Each entry in the array is a separate project assignment object. If no more project assignments are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your project assignments.
GET /v2/users/me/project_assignments
Parameter Type Description
page integer The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
Example Request:
curl "https://api.harvestapp.com/v2/users/me/project_assignments" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"project_assignments":[
{
"id":125066109,
"is_project_manager":true,
"is_active":true,
"use_default_rates":true,
"budget":null,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"client":{
"id":5735776,
"name":"123 Industries"
},
"task_assignments":[
{
"id":155505013,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083365,
"name":"Graphic Design"
}
},
{
"id":155505014,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083366,
"name":"Programming"
}
},
{
"id":155505015,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083368,
"name":"Project Management"
}
},
{
"id":155505016,
"billable":false,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:54:06Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083369,
"name":"Research"
}
}
]
},
{
"id":125063975,
"is_project_manager":true,
"is_active":true,
"use_default_rates":false,
"budget":null,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"project":{
"id":14307913,
"name":"Marketing Website",
"code":"MW"
},
"client":{
"id":5735774,
"name":"ABC Corp"
},
"task_assignments":[
{
"id":155502709,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083365,
"name":"Graphic Design"
}
},
{
"id":155502710,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083366,
"name":"Programming"
}
},
{
"id":155502711,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083368,
"name":"Project Management"
}
},
{
"id":155505153,
"billable":false,
"is_active":true,
"created_at":"2017-06-26T21:53:20Z",
"updated_at":"2017-06-26T21:54:31Z",
"hourly_rate":100.0,
"budget":null,
"task":{
"id":8083369,
"name":"Research"
}
}
]
}
],
"per_page":2000,
"total_pages":1,
"total_entries":2,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/users/1782884/project_assignments?page=1&per_page=2000",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/users/1782884/project_assignments?page=1&per_page=2000"
}
}
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/07_expenses/expenses.md:
--------------------------------------------------------------------------------
```markdown
Expenses
The expense object⚭
Attribute Type Description
id integer Unique ID for the expense.
client object An object containing the expense’s client id, name, and currency.
project object An object containing the expense’s project id, name, and code.
expense_category object An object containing the expense’s expense category id, name, unit_price, and unit_name.
user object An object containing the id and name of the user that recorded the expense.
user_assignment object A user assignment object of the user that recorded the expense.
receipt object An object containing the expense’s receipt URL and file name.
invoice object Once the expense has been invoiced, this field will include the associated invoice’s id and number.
notes string Textual notes used to describe the expense.
units integer The quantity of units used to calculate the total_cost of the expense.
total_cost decimal The total amount of the expense.
billable boolean Whether the expense is billable or not.
is_closed boolean Whether the expense has been approved or not.
is_locked boolean Whether the expense has been been invoiced, approved, or the project or person related to the expense is archived.
is_billed boolean Whether or not the expense has been marked as invoiced.
locked_reason string An explanation of why the expense has been locked.
spent_date date Date the expense occurred.
created_at datetime Date and time the expense was created.
updated_at datetime Date and time the expense was last updated.
List all expenses⚭
Returns a list of your expenses. If accessing this endpoint as an Administrator, all expenses in the account will be returned. If accessing this endpoint as a Manager, all expenses for assigned teammates and managed projects will be returned. The expenses are returned sorted by the spent_at date, with the most recent expenses appearing first.
The response contains an object with a expenses property that contains an array of up to per_page expenses. Each entry in the array is a separate expense object. If no more expenses are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your expenses.
GET /v2/expenses
Parameter Type Description
user_id integer Only return expenses belonging to the user with the given ID.
client_id integer Only return expenses belonging to the client with the given ID.
project_id integer Only return expenses belonging to the project with the given ID.
is_billed boolean Pass true to only return expenses that have been invoiced and false to return expenses that have not been invoiced.
updated_since datetime Only return expenses that have been updated since the given date and time.
from date Only return expenses with a spent_date on or after the given date.
to date Only return expenses with a spent_date on or before the given date.
page integer The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
Example Request:
curl "https://api.harvestapp.com/v2/expenses" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"expenses":[
{
"id":15296442,
"notes":"Lunch with client",
"total_cost":33.35,
"units":1.0,
"is_closed":false,
"is_locked":true,
"is_billed":true,
"locked_reason":"Expense is invoiced.",
"spent_date":"2017-03-03",
"created_at":"2017-06-27T15:09:54Z",
"updated_at":"2017-06-27T16:47:14Z",
"billable":true,
"receipt":{
"url":"https://{ACCOUNT_SUBDOMAIN}.harvestapp.com/expenses/15296442/receipt",
"file_name":"lunch_receipt.gif",
"file_size":39410,
"content_type":"image/gif"
},
"user":{
"id":1782959,
"name":"Kim Allen"
},
"user_assignment":{
"id":125068553,
"is_project_manager":true,
"is_active":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0
},
"project":{
"id":14307913,
"name":"Marketing Website",
"code":"MW"
},
"expense_category":{
"id":4195926,
"name":"Meals",
"unit_price":null,
"unit_name":null
},
"client":{
"id":5735774,
"name":"ABC Corp",
"currency":"USD"
},
"invoice":{
"id":13150403,
"number":"1001"
}
},
{
"id":15296423,
"notes":"Hotel stay for meeting",
"total_cost":100.0,
"units":1.0,
"is_closed":true,
"is_locked":true,
"is_billed":false,
"locked_reason":"The project is locked for this time period.",
"spent_date":"2017-03-01",
"created_at":"2017-06-27T15:09:17Z",
"updated_at":"2017-06-27T16:47:14Z",
"billable":true,
"receipt":null,
"user":{
"id":1782959,
"name":"Kim Allen"
},
"user_assignment":{
"id":125068554,
"is_project_manager":true,
"is_active":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0
},
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"expense_category":{
"id":4197501,
"name":"Lodging",
"unit_price":null,
"unit_name":null
},
"client":{
"id":5735776,
"name":"123 Industries",
"currency":"EUR"
},
"invoice":null
}
],
"per_page":2000,
"total_pages":1,
"total_entries":2,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/expenses?page=1&per_page=2000",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/expenses?page=1&per_page=2000"
}
}
Retrieve an expense⚭
Retrieves the expense with the given ID. Returns an expense object and a 200 OK response code if a valid identifier was provided.
GET /v2/expenses/{EXPENSE_ID}
Example Request:
curl "https://api.harvestapp.com/v2/expenses/15296442" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"id":15296442,
"notes":"Lunch with client",
"total_cost":33.35,
"units":1.0,
"is_closed":false,
"is_locked":true,
"is_billed":true,
"locked_reason":"Expense is invoiced.",
"spent_date":"2017-03-03",
"created_at":"2017-06-27T15:09:54Z",
"updated_at":"2017-06-27T16:47:14Z",
"billable":true,
"receipt":{
"url":"https://{ACCOUNT_SUBDOMAIN}.harvestapp.com/expenses/15296442/receipt",
"file_name":"lunch_receipt.gif",
"file_size":39410,
"content_type":"image/gif"
},
"user":{
"id":1782959,
"name":"Kim Allen"
},
"user_assignment":{
"id":125068553,
"is_project_manager":true,
"is_active":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0
},
"project":{
"id":14307913,
"name":"Marketing Website",
"code":"MW"
},
"expense_category":{
"id":4195926,
"name":"Meals",
"unit_price":null,
"unit_name":null
},
"client":{
"id":5735774,
"name":"ABC Corp",
"currency":"USD"
},
"invoice":{
"id":13150403,
"number":"1001"
}
}
Create an expense⚭
Creates a new expense object. Returns an expense object and a 201 Created response code if the call succeeded.
POST /v2/expenses
Parameter Type Required Description
user_id integer optional The ID of the user associated with this expense. Defaults to the ID of the currently authenticated user.
project_id integer required The ID of the project associated with this expense.
expense_category_id integer required The ID of the expense category this expense is being tracked against.
spent_date date required Date the expense occurred.
units integer *optional The quantity of units to use in calculating the total_cost of the expense.
total_cost decimal *optional The total amount of the expense.
notes string optional Textual notes used to describe the expense.
billable boolean optional Whether this expense is billable or not. Defaults to true.
receipt file optional A receipt file to attach to the expense. If including a receipt, you must submit a multipart/form-data request.
* Either units or total_cost is required. units is required if using a unit-based expense category. total_cost is required if not using a unit-based expense category.
Example Request:
curl "https://api.harvestapp.com/v2/expenses" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X POST \
-H "Content-Type: application/json" \
-d '{"user_id":1782959,"project_id":14308069,"expense_category_id":4195926,"spent_date":"2017-03-01","total_cost":13.59}'
Example Response:
{
"id":15297032,
"notes":null,
"total_cost":13.59,
"units":1.0,
"is_closed":false,
"is_locked":false,
"is_billed":false,
"locked_reason":null,
"spent_date":"2017-03-01",
"created_at":"2017-06-27T15:42:27Z",
"updated_at":"2017-06-27T15:42:27Z",
"billable":true,
"receipt":null,
"user":{
"id":1782959,
"name":"Kim Allen"
},
"user_assignment":{
"id":125068553,
"is_project_manager":true,
"is_active":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0
},
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"expense_category":{
"id":4195926,
"name":"Meals",
"unit_price":null,
"unit_name":null
},
"client":{
"id":5735776,
"name":"123 Industries",
"currency":"EUR"
},
"invoice":null
}
Update an expense⚭
Updates the specific expense by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns an expense object and a 200 OK response code if the call succeeded.
PATCH /v2/expenses/{EXPENSE_ID}
Parameter Type Description
project_id integer The ID of the project associated with this expense.
expense_category_id integer The ID of the expense category this expense is being tracked against.
spent_date date Date the expense occurred.
units integer The quantity of units to use in calculating the total_cost of the expense.
total_cost decimal The total amount of the expense.
notes string Textual notes used to describe the expense.
billable boolean Whether this expense is billable or not. Defaults to true.
receipt file A receipt file to attach to the expense. If including a receipt, you must submit a multipart/form-data request.
delete_receipt boolean Whether an attached expense receipt should be deleted. Pass true to delete the expense receipt.
Example Request:
curl "https://api.harvestapp.com/v2/expenses/15297032" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X PATCH \
-F notes="Dinner" \
-F [email protected]
Example Response:
{
"id":15297032,
"notes":"Dinner",
"total_cost":13.59,
"units":1.0,
"is_closed":false,
"is_locked":false,
"is_billed":false,
"locked_reason":null,
"spent_date":"2017-03-01",
"created_at":"2017-06-27T15:42:27Z",
"updated_at":"2017-06-27T15:45:51Z",
"billable":true,
"receipt":{
"url":"https://{ACCOUNT_SUBDOMAIN}.harvestapp.com/expenses/15297032/receipt",
"file_name":"dinner_receipt.gif",
"file_size":39410,
"content_type":"image/gif"
},
"user":{
"id":1782959,
"name":"Kim Allen"
},
"user_assignment":{
"id":125068553,
"is_project_manager":true,
"is_active":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0
},
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"expense_category":{
"id":4195926,
"name":"Meals",
"unit_price":null,
"unit_name":null
},
"client":{
"id":5735776,
"name":"123 Industries",
"currency":"EUR"
},
"invoice":null
}
Delete an expense⚭
Delete an expense. Returns a 200 OK response code if the call succeeded.
DELETE /v2/expenses/{EXPENSE_ID}
Example Request:
curl "https://api.harvestapp.com/v2/expenses/15297032" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X DELETE
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/10_projects/projects.md:
--------------------------------------------------------------------------------
```markdown
Projects
The project object⚭
Attribute Type Description
id integer Unique ID for the project.
client object An object containing the project’s client id, name, and currency.
name string Unique name for the project.
code string The code associated with the project.
is_active boolean Whether the project is active or archived.
is_billable boolean Whether the project is billable or not.
is_fixed_fee boolean Whether the project is a fixed-fee project or not.
bill_by string The method by which the project is invoiced.
hourly_rate decimal Rate for projects billed by Project Hourly Rate.
budget decimal The budget in hours for the project when budgeting by time.
budget_by string The method by which the project is budgeted.
budget_is_monthly boolean Option to have the budget reset every month.
notify_when_over_budget boolean Whether Project Managers should be notified when the project goes over budget.
over_budget_notification_percentage decimal Percentage value used to trigger over budget email alerts.
over_budget_notification_date date Date of last over budget notification. If none have been sent, this will be null.
show_budget_to_all boolean Option to show project budget to all employees. Does not apply to Total Project Fee projects.
cost_budget decimal The monetary budget for the project when budgeting by money.
cost_budget_include_expenses boolean Option for budget of Total Project Fees projects to include tracked expenses.
fee decimal The amount you plan to invoice for the project. Only used by fixed-fee projects.
notes string Project notes.
starts_on date Date the project was started.
ends_on date Date the project will end.
created_at datetime Date and time the project was created.
updated_at datetime Date and time the project was last updated.
Required permissions⚭
You must be an Administrator or Manager with managed projects in order to interact with the /v2/projects endpoint. Insufficient permissions will result in a 403 Forbidden status code.
List all projects⚭
Returns a list of your projects. The projects are returned sorted by creation date, with the most recently created projects appearing first.
The response contains an object with a projects property that contains an array of up to per_page projects. Each entry in the array is a separate project object. If no more projects are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your projects.
GET /v2/projects
Parameter Type Description
is_active boolean Pass true to only return active projects and false to return inactive projects.
client_id integer Only return projects belonging to the client with the given ID.
updated_since datetime Only return projects that have been updated since the given date and time.
page integer DEPRECATED The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
This endpoint supports cursor-based pagination and therefore deprecates the page parameter. For more information, visit the pagination guide.
Example Request:
curl "https://api.harvestapp.com/v2/projects" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"projects":[
{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1",
"is_active":true,
"bill_by":"Project",
"budget":200.0,
"budget_by":"project",
"budget_is_monthly":false,
"notify_when_over_budget":true,
"over_budget_notification_percentage":80.0,
"over_budget_notification_date":null,
"show_budget_to_all":false,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:54:06Z",
"starts_on":"2017-06-01",
"ends_on":null,
"is_billable":true,
"is_fixed_fee":false,
"notes":"",
"client":{
"id":5735776,
"name":"123 Industries",
"currency":"EUR"
},
"cost_budget":null,
"cost_budget_include_expenses":false,
"hourly_rate":100.0,
"fee":null
},
{
"id":14307913,
"name":"Marketing Website",
"code":"MW",
"is_active":true,
"bill_by":"Project",
"budget":50.0,
"budget_by":"project",
"budget_is_monthly":false,
"notify_when_over_budget":true,
"over_budget_notification_percentage":80.0,
"over_budget_notification_date":null,
"show_budget_to_all":false,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:54:46Z",
"starts_on":"2017-01-01",
"ends_on":"2017-03-31",
"is_billable":true,
"is_fixed_fee":false,
"notes":"",
"client":{
"id":5735774,
"name":"ABC Corp",
"currency":"USD"
},
"cost_budget":null,
"cost_budget_include_expenses":false,
"hourly_rate":100.0,
"fee":null
}
],
"per_page":2000,
"total_pages":1,
"total_entries":2,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/projects?page=1&per_page=2000",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/projects?page=1&per_page=2000"
}
}
Retrieve a project⚭
Retrieves the project with the given ID. Returns a project object and a 200 OK response code if a valid identifier was provided.
GET /v2/projects/{PROJECT_ID}
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308069" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1",
"is_active":true,
"bill_by":"Project",
"budget":200.0,
"budget_by":"project",
"budget_is_monthly":false,
"notify_when_over_budget":true,
"over_budget_notification_percentage":80.0,
"over_budget_notification_date":null,
"show_budget_to_all":false,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:54:06Z",
"starts_on":"2017-06-01",
"ends_on":null,
"is_billable":true,
"is_fixed_fee":false,
"notes":"",
"client":{
"id":5735776,
"name":"123 Industries",
"currency":"EUR"
},
"cost_budget":null,
"cost_budget_include_expenses":false,
"hourly_rate":100.0,
"fee":null
}
Create a project⚭
Creates a new project object. Returns a project object and a 201 Created response code if the call succeeded.
POST /v2/projects
Parameter Type Required Description
client_id integer required The ID of the client to associate this project with.
name string required The name of the project.
code string optional The code associated with the project.
is_active boolean optional Whether the project is active or archived. Defaults to true.
is_billable boolean required Whether the project is billable or not.
is_fixed_fee boolean optional Whether the project is a fixed-fee project or not.
bill_by string required The method by which the project is invoiced. Options: Project, Tasks, People, or none.
hourly_rate decimal optional Rate for projects billed by Project Hourly Rate.
budget decimal optional The budget in hours for the project when budgeting by time.
budget_by string required The method by which the project is budgeted. Options: project (Hours Per Project), project_cost (Total Project Fees), task (Hours Per Task), task_fees (Fees Per Task), person (Hours Per Person), none (No Budget).
budget_is_monthly boolean optional Option to have the budget reset every month. Defaults to false.
notify_when_over_budget boolean optional Whether Project Managers should be notified when the project goes over budget. Defaults to false.
over_budget_notification_percentage decimal optional Percentage value used to trigger over budget email alerts. Example: use 10.0 for 10.0%.
show_budget_to_all boolean optional Option to show project budget to all employees. Does not apply to Total Project Fee projects. Defaults to false.
cost_budget decimal optional The monetary budget for the project when budgeting by money.
cost_budget_include_expenses boolean optional Option for budget of Total Project Fees projects to include tracked expenses. Defaults to false.
fee decimal optional The amount you plan to invoice for the project. Only used by fixed-fee projects.
notes string optional Project notes.
starts_on date optional Date the project was started.
ends_on date optional Date the project will end.
Example Request:
curl "https://api.harvestapp.com/v2/projects" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X POST \
-H "Content-Type: application/json" \
-d '{"client_id":5735776,"name":"Your New Project","is_billable":true,"bill_by":"Project","hourly_rate":100.0,"budget_by":"project","budget":10000}'
Example Response:
{
"id":14308112,
"name":"Your New Project",
"code":null,
"is_active":true,
"bill_by":"Project",
"budget":10000.0,
"budget_by":"project",
"budget_is_monthly":false,
"notify_when_over_budget":false,
"over_budget_notification_percentage":80.0,
"over_budget_notification_date":null,
"show_budget_to_all":false,
"created_at":"2017-06-26T21:56:52Z",
"updated_at":"2017-06-26T21:56:52Z",
"starts_on":null,
"ends_on":null,
"is_billable":true,
"is_fixed_fee":false,
"notes":"",
"client":{
"id":5735776,
"name":"123 Industries",
"currency":"EUR"
},
"cost_budget":null,
"cost_budget_include_expenses":false,
"hourly_rate":100.0,
"fee":null
}
Update a project⚭
Updates the specific project by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a project object and a 200 OK response code if the call succeeded.
PATCH /v2/projects/{PROJECT_ID}
Parameter Type Description
client_id integer The ID of the client to associate this project with.
name string The name of the project.
code string The code associated with the project.
is_active boolean Whether the project is active or archived. Defaults to true.
is_billable boolean Whether the project is billable or not.
is_fixed_fee boolean Whether the project is a fixed-fee project or not.
bill_by string The method by which the project is invoiced. Options: Project, Tasks, People, or none.
hourly_rate decimal Rate for projects billed by Project Hourly Rate.
budget decimal The budget in hours for the project when budgeting by time.
budget_by string The method by which the project is budgeted. Options: project (Hours Per Project), project_cost (Total Project Fees), task (Hours Per Task), task_fees (Fees Per Task), person (Hours Per Person), none (No Budget).
budget_is_monthly boolean Option to have the budget reset every month. Defaults to false.
notify_when_over_budget boolean Whether Project Managers should be notified when the project goes over budget. Defaults to false.
over_budget_notification_percentage decimal Percentage value used to trigger over budget email alerts. Example: use 10.0 for 10.0%.
show_budget_to_all boolean Option to show project budget to all employees. Does not apply to Total Project Fee projects. Defaults to false.
cost_budget decimal The monetary budget for the project when budgeting by money.
cost_budget_include_expenses boolean Option for budget of Total Project Fees projects to include tracked expenses. Defaults to false.
fee decimal The amount you plan to invoice for the project. Only used by fixed-fee projects.
notes string Project notes.
starts_on date Date the project was started.
ends_on date Date the project will end.
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308112" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"name":"New project name"}'
Example Response:
{
"id":14308112,
"name":"New project name",
"code":null,
"is_active":true,
"bill_by":"Project",
"budget":10000.0,
"budget_by":"project",
"budget_is_monthly":false,
"notify_when_over_budget":false,
"over_budget_notification_percentage":80.0,
"over_budget_notification_date":null,
"show_budget_to_all":false,
"created_at":"2017-06-26T21:56:52Z",
"updated_at":"2017-06-26T21:57:20Z",
"starts_on":null,
"ends_on":null,
"is_billable":true,
"is_fixed_fee":false,
"notes":"",
"client":{
"id":5735776,
"name":"123 Industries",
"currency":"EUR"
},
"cost_budget":null,
"cost_budget_include_expenses":false,
"hourly_rate":100.0,
"fee":null
}
Delete a project⚭
Deletes a project and any time entries or expenses tracked to it. However, invoices associated with the project will not be deleted. If you don’t want the project’s time entries and expenses to be deleted, you should archive the project instead.
DELETE /v2/projects/{PROJECT_ID}
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308112" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X DELETE
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/10_projects/project_user_assignments.md:
--------------------------------------------------------------------------------
```markdown
Project User Assignments
The user assignment object⚭
Attribute Type Description
id integer Unique ID for the user assignment.
project object An object containing the id, name, and code of the associated project.
user object An object containing the id and name of the associated user.
is_active boolean Whether the user assignment is active or archived.
is_project_manager boolean Determines if the user has Project Manager permissions for the project.
use_default_rates boolean Determines which billable rate(s) will be used on the project for this user when bill_by is People. When true, the project will use the user’s default billable rates. When false, the project will use the custom rate defined on this user assignment.
hourly_rate decimal Custom rate used when the project’s bill_by is People and use_default_rates is false.
budget decimal Budget used when the project’s budget_by is person.
created_at datetime Date and time the user assignment was created.
updated_at datetime Date and time the user assignment was last updated.
Required permissions⚭
You must be an Administrator or Manager with assigned teammates or managed projects in order to interact with the /v2/user_assignments endpoint. Insufficient permissions will result in a 403 Forbidden status code.
List all user assignments⚭
Returns a list of your projects user assignments, active and archived. The user assignments are returned sorted by creation date, with the most recently created user assignments appearing first.
The response contains an object with a user_assignments property that contains an array of up to per_page user assignments. Each entry in the array is a separate user assignment object. If no more user assignments are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your user assignments.
GET /v2/user_assignments
Parameter Type Description
user_id integer Only return user assignments belonging to the user with the given ID.
is_active boolean Pass true to only return active user assignments and false to return inactive user assignments.
updated_since datetime Only return user assignments that have been updated since the given date and time.
page integer DEPRECATED The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
This endpoint supports cursor-based pagination and therefore deprecates the page parameter. For more information, visit the pagination guide.
Example Request:
curl "https://api.harvestapp.com/v2/user_assignments" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"user_assignments":[
{
"id":130403297,
"is_project_manager":true,
"is_active":true,
"use_default_rates":false,
"budget":null,
"created_at":"2017-08-22T17:36:54Z",
"updated_at":"2017-08-22T17:36:54Z",
"hourly_rate":100.0,
"project":{
"id":14808188,
"name":"Task Force",
"code":"TF"
},
"user":{
"id":1782959,
"name":"Kim Allen"
}
},
{
"id":130403296,
"is_project_manager":true,
"is_active":true,
"use_default_rates":true,
"budget":null,
"created_at":"2017-08-22T17:36:54Z",
"updated_at":"2017-08-22T17:36:54Z",
"hourly_rate":100.0,
"project":{
"id":14808188,
"name":"Task Force",
"code":"TF"
},
"user":{
"id":1795925,
"name":"Jason Dew"
}
},
{
"id":125068554,
"is_project_manager":true,
"is_active":true,
"use_default_rates":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"user":{
"id":1782959,
"name":"Kim Allen"
}
},
{
"id":125068553,
"is_project_manager":true,
"is_active":true,
"use_default_rates":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0,
"project":{
"id":14307913,
"name":"Marketing Website",
"code":"MW"
},
"user":{
"id":1782959,
"name":"Kim Allen"
}
},
{
"id":125066109,
"is_project_manager":true,
"is_active":true,
"use_default_rates":false,
"budget":null,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"user":{
"id":1782884,
"name":"Jeremy Israelsen"
}
},
{
"id":125063975,
"is_project_manager":true,
"is_active":true,
"use_default_rates":true,
"budget":null,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"project":{
"id":14307913,
"name":"Marketing Website",
"code":"MW"
},
"user":{
"id":1782884,
"name":"Jeremy Israelsen"
}
}
],
"per_page":2000,
"total_pages":1,
"total_entries":6,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/user_assignments?page=1&per_page=2000",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/user_assignments?page=1&per_page=2000"
}
}
List all user assignments for a specific project⚭
Returns a list of user assignments for the project identified by PROJECT_ID. The user assignments are returned sorted by creation date, with the most recently created user assignments appearing first.
The response contains an object with a user_assignments property that contains an array of up to per_page user assignments. Each entry in the array is a separate user assignment object. If no more user assignments are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your user assignments.
GET /v2/projects/{PROJECT_ID}/user_assignments
Parameter Type Description
user_id integer Only return user assignments belonging to the user with the given ID.
is_active boolean Pass true to only return active user assignments and false to return inactive user assignments.
updated_since datetime Only return user assignments that have been updated since the given date and time.
page integer The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308069/user_assignments" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"user_assignments":[
{
"id":125068554,
"is_project_manager":true,
"is_active":true,
"use_default_rates":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"user":{
"id":1782959,
"name":"Kim Allen"
}
},
{
"id":125066109,
"is_project_manager":true,
"is_active":true,
"use_default_rates":false,
"budget":null,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"user":{
"id":1782884,
"name":"Jeremy Israelsen"
}
}
],
"per_page":2000,
"total_pages":1,
"total_entries":2,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/projects/14308069/user_assignments?page=1&per_page=2000",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/projects/14308069/user_assignments?page=1&per_page=2000"
}
}
Retrieve a user assignment⚭
Retrieves the user assignment with the given ID. Returns a user assignment object and a 200 OK response code if a valid identifier was provided.
GET /v2/projects/{PROJECT_ID}/user_assignments/{USER_ASSIGNMENT_ID}
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308069/user_assignments/125068554" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"id":125068554,
"is_project_manager":true,
"is_active":true,
"use_default_rates":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"user":{
"id":1782959,
"name":"Kim Allen"
}
}
Create a user assignment⚭
Creates a new user assignment object. Returns a user assignment object and a 201 Created response code if the call succeeded.
POST /v2/projects/{PROJECT_ID}/user_assignments
Parameter Type Required Description
user_id integer required The ID of the user to associate with the project.
is_active boolean optional Whether the user assignment is active or archived. Defaults to true.
is_project_manager boolean optional Determines if the user has Project Manager permissions for the project. Defaults to false for users with Regular User permissions and true for those with Project Managers or Administrator permissions.
use_default_rates boolean optional Determines which billable rate(s) will be used on the project for this user when bill_by is People. When true, the project will use the user’s default billable rates. When false, the project will use the custom rate defined on this user assignment. Defaults to true.
hourly_rate decimal optional Custom rate used when the project’s bill_by is People and use_default_rates is false. Defaults to 0.
budget decimal optional Budget used when the project’s budget_by is person.
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308069/user_assignments" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X POST \
-H "Content-Type: application/json" \
-d '{"user_id":1782974,"use_default_rates":false,"hourly_rate":75.50}'
Example Response:
{
"id":125068758,
"is_project_manager":false,
"is_active":true,
"use_default_rates":false,
"budget":null,
"created_at":"2017-06-26T22:36:01Z",
"updated_at":"2017-06-26T22:36:01Z",
"hourly_rate":75.5,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"user":{
"id":1782974,
"name":"Jim Allen"
}
}
Update a user assignment⚭
Updates the specific user assignment by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a user assignment object and a 200 OK response code if the call succeeded.
PATCH /v2/projects/{PROJECT_ID}/user_assignments/{USER_ASSIGNMENT_ID}
Parameter Type Description
is_active boolean Whether the user assignment is active or archived.
is_project_manager boolean Determines if the user has Project Manager permissions for the project.
use_default_rates boolean Determines which billable rate(s) will be used on the project for this user when bill_by is People. When true, the project will use the user’s default billable rates. When false, the project will use the custom rate defined on this user assignment.
hourly_rate decimal Custom rate used when the project’s bill_by is People and use_default_rates is false.
budget decimal Budget used when the project’s budget_by is person.
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308069/user_assignments/125068758" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"budget":120}'
Example Response:
{
"id":125068758,
"is_project_manager":false,
"is_active":true,
"use_default_rates":false,
"budget":120.0,
"created_at":"2017-06-26T22:36:01Z",
"updated_at":"2017-06-26T22:36:35Z",
"hourly_rate":75.5,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"user":{
"id":1782974,
"name":"Jim Allen"
}
}
Delete a user assignment⚭
Delete a user assignment. Deleting a user assignment is only possible if it has no time entries or expenses associated with it. Returns a 200 OK response code if the call succeeded.
DELETE /v2/projects/{PROJECT_ID}/user_assignments/{USER_ASSIGNMENT_ID}
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308069/user_assignments/125068758" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X DELETE
```