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