Harvest

The Harvest connector allows the chatbot to manage time tracking, projects, invoices, and expenses through the Harvest API using Agentgateway.

Connector Settings

Usage Examples

Once connected, users can interact with Harvest through natural language:

• "How many hours did I log this week?"
• "Show me all active projects"
• "Create a time entry for 2 hours on the marketing project"

Tools

Create Client

createClient

Creates a new client object. Returns a client object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • name - A textual description of the client.
  • address - A textual representation of the client's physical address. May include new line characters.
  • currency - The currency used by the client. If not provided, the company's currency will be used. See a list of supported currencies
  • is_active - Whether the client is active, or archived. Defaults to true.

Retrieve Company

retrieveCompany

Retrieves the company for the currently authenticated user. Returns a company object and a 200 OK response code.

Delete Project

deleteProject

Deletes a project and any time entries or expenses tracked to it. However, invoices associated with the project will not be deleted. If you don't want the project's time entries and expenses to be deleted, you should archive the project instead.

Parameters:

• path -
  • projectId -

Update Project

updateProject

Updates the specific project by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a project object and a 200 OK response code if the call succeeded.

Parameters:

• body -
  • fee - The amount you plan to invoice for the project. Only used by fixed-fee projects.
  • code - The code associated with the project.
  • name - The name of the project.
  • notes - Project notes.
  • budget - The budget in hours for the project when budgeting by time.
  • bill_by - The method by which the project is invoiced. Options: Project, Tasks, People, or none.
  • ends_on - Date the project will end.
  • budget_by - 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).
  • client_id - The ID of the client to associate this project with.
  • is_active - Whether the project is active or archived. Defaults to true.
  • starts_on - Date the project was started.
  • cost_budget - The monetary budget for the project when budgeting by money.
  • hourly_rate - Rate for projects billed by Project Hourly Rate.
  • is_billable - Whether the project is billable or not.
  • is_fixed_fee - Whether the project is a fixed-fee project or not.
  • budget_is_monthly - Option to have the budget reset every month. Defaults to false.
  • show_budget_to_all - Option to show project budget to all employees. Does not apply to Total Project Fee projects. Defaults to false.
  • notify_when_over_budget - Whether Project Managers should be notified when the project goes over budget. Defaults to false.
  • cost_budget_include_expenses - Option for budget of Total Project Fees projects to include tracked expenses. Defaults to false.
  • over_budget_notification_percentage - Percentage value used to trigger over budget email alerts. Example: use 10.0 for 10.0%.
• path -
  • projectId -

List Task Assignments For Specific Project

listTaskAssignmentsForSpecificProject

Returns a list of your task assignments for the project identified by PROJECT_ID. The task assignments are returned sorted by creation date, with the most recently created task assignments appearing first.

The response contains an object with a task_assignments property that contains an array of up to per_page task assignments. Each entry in the array is a separate task assignment object. If no more task assignments are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your task assignments.

Parameters:

• path -
  • projectId -
• query -
  • page - The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • is_active - Pass true to only return active task assignments and false to return inactive task assignments.
  • updated_since - Only return task assignments that have been updated since the given date and time.

Retrieve Contact

retrieveContact

Retrieves the contact with the given ID. Returns a contact object and a 200 OK response code if a valid identifier was provided.

Parameters:

• path -
  • contactId -

List Estimate Item Categories

listEstimateItemCategories

Returns a list of your estimate item categories. The estimate item categories are returned sorted by creation date, with the most recently created estimate item categories appearing first.

The response contains an object with a estimate_item_categories property that contains an array of up to per_page estimate item categories. Each entry in the array is a separate estimate item category object. If no more estimate item categories are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your estimate item categories.

Parameters:

• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • updated_since - Only return estimate item categories that have been updated since the given date and time.

Team Time Report

teamTimeReport

Parameters:

• query -
  • to - Only report on time entries with a spent_date on or before the given date.
  • from - Only report on time entries with a spent_date on or after the given date.
  • page - The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • include_fixed_fee - When true, billable amounts will be calculated and included for fixed fee projects.

Retrieve Time Entry

retrieveTimeEntry

Retrieves the time entry with the given ID. Returns a time entry object and a 200 OK response code if a valid identifier was provided.

Parameters:

• path -
  • timeEntryId -

Delete Estimate Message

deleteEstimateMessage

Delete an estimate message. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • messageId -
  • estimateId -

Retrieve Expense Category

retrieveExpenseCategory

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.

Parameters:

• path -
  • expenseCategoryId -

Delete Expense

deleteExpense

Delete an expense. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • expenseId -

Retrieve Invoice

retrieveInvoice

Retrieves the invoice with the given ID. Returns an invoice object and a 200 OK response code if a valid identifier was provided.

Parameters:

• path -
  • invoiceId -

Delete Invoice Message

deleteInvoiceMessage

Delete an invoice message. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • invoiceId -
  • messageId -

List Payments For Invoice

listPaymentsForInvoice

Returns a list of payments associate with a given invoice. The payments are returned sorted by creation date, with the most recently created payments appearing first.

The response contains an object with an invoice_payments property that contains an array of up to per_page payments. Each entry in the array is a separate payment object. If no more payments are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your payments.

Parameters:

• path -
  • invoiceId -
• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • updated_since - Only return invoice payments that have been updated since the given date and time.

Delete Invoice Payment

deleteInvoicePayment

Delete an invoice payment. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • invoiceId -
  • paymentId -

Delete Time Entry

deleteTimeEntry

Delete a time entry. Deleting a time entry is only possible if it's not closed and the associated project and task haven't been archived. However, Admins can delete closed entries. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • timeEntryId -

List Active Project Assignments For The Currently Authenticated User

listActiveProjectAssignmentsForTheCurrentlyAuthenticatedUser

Returns a list of your active project assignments for the currently authenticated user. The project assignments are returned sorted by creation date, with the most recently created project assignments appearing first.

The response contains an object with a project_assignments property that contains an array of up to per_page project assignments. Each entry in the array is a separate project assignment object. If no more project assignments are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your project assignments.

Parameters:

• query -
  • page - The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)

Delete User

deleteUser

Delete a user. Deleting a user is only possible if they have no time entries or expenses associated with them. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • userId -

Retrieve User Assignment

retrieveUserAssignment

Retrieves the user assignment with the given ID. Returns a user assignment object and a 200 OK response code if a valid identifier was provided.

Parameters:

• path -
  • projectId -
  • userAssignmentId -

Retrieve Role

retrieveRole

Retrieves the role with the given ID. Returns a role object and a 200 OK response code if a valid identifier was provided.

Parameters:

• path -
  • roleId -

Delete Role

deleteRole

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.

Parameters:

• path -
  • roleId -

Create Task

createTask

Creates a new task object. Returns a task object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • name - The name of the task.
  • is_active - Whether this task is active or archived. Defaults to true.
  • is_default - Whether this task should be automatically added to future projects. Defaults to false.
  • billable_by_default - Used in determining whether default tasks should be marked billable when creating a new project. Defaults to true.
  • default_hourly_rate - The default hourly rate to use for this task when it is added to a project. Defaults to 0.

Retrieve Client

retrieveClient

Retrieves the client with the given ID. Returns a client object and a 200 OK response code if a valid identifier was provided.

Parameters:

• path -
  • clientId -

Delete Client

deleteClient

Delete a client. Deleting a client is only possible if it has no projects, invoices, or estimates associated with it. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • clientId -

Update Client

updateClient

Updates the specific client by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a client object and a 200 OK response code if the call succeeded.

Parameters:

• body -
  • name - A textual description of the client.
  • address - A textual representation of the client's physical address. May include new line characters.
  • currency - The currency used by the client. See a list of supported currencies
  • is_active - Whether the client is active, or archived.
• path -
  • clientId -

Update Company

updateCompany

Updates the company setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a company object and a 200 OK response code if the call succeeded.

Parameters:

• body -
  • weekly_capacity - The weekly capacity in seconds.
  • wants_timestamp_timers - Whether time is tracked via duration or start and end times.

Uninvoiced Report

uninvoicedReport

The response contains an object with a results property that contains an array of up to per_page results. Each entry in the array is a separate result object. If no more results are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your results.

Note: Each request requires both the from and to parameters to be supplied in the URL's query string. The timeframe supplied cannot exceed 1 year (365 days).

Parameters:

• query -
  • to - Only report on time entries and expenses with a spent_date on or before the given date.
  • from - Only report on time entries and expenses with a spent_date on or after the given date.
  • page - The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • include_fixed_fee - Whether or not to include fixed-fee projects in the response. Fixed-fee uninvoiced fee amount will show as long as the selected date range is on or after the project start date (If project start date is not specified, it is project creation date). Otherwise, it will be 0. (Default: true)

Delete Time Entry External Reference

deleteTimeEntryExternalReference

Delete a time entry's external reference. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • timeEntryId -

Restart Stopped Time Entry

restartStoppedTimeEntry

Restarting a time entry is only possible if it isn't currently running. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • timeEntryId -

Retrieve The Currently Authenticated User

retrieveTheCurrentlyAuthenticatedUser

Retrieves the currently authenticated user. Returns a user object and a 200 OK response code.

Retrieve User

retrieveUser

Retrieves the user with the given ID. Returns a user object and a 200 OK response code if a valid identifier was provided.

Parameters:

• path -
  • userId -

Retrieve Billable Rate

retrieveBillableRate

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.

Parameters:

• path -
  • userId -
  • billableRateId -

Retrieve Cost Rate

retrieveCostRate

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.

Parameters:

• path -
  • userId -
  • costRateId -

List Roles

listRoles

Returns a list of roles in the account. The roles are returned sorted by creation date, with the most recently created roles appearing first.

The response contains an object with a roles property that contains an array of up to per_page roles. Each entry in the array is a separate role object. If no more roles are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your roles.

Parameters:

• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)

Create Role

createRole

Creates a new role object. Returns a role object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • name - The name of the role.
  • user_ids - The IDs of the users assigned to this role.

Delete Contact

deleteContact

Delete a contact. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • contactId -

Create Expense Category

createExpenseCategory

Creates a new expense category object. Returns an expense category object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • name - The name of the expense category.
  • is_active - Whether the expense category is active or archived. Defaults to true.
  • unit_name - The unit name of the expense category.
  • unit_price - The unit price of the expense category.

Delete Expense Category

deleteExpenseCategory

Delete an expense category. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • expenseCategoryId -

Retrieve Expense

retrieveExpense

Retrieves the expense with the given ID. Returns an expense object and a 200 OK response code if a valid identifier was provided.

Parameters:

• path -
  • expenseId -

Create Invoice

createInvoice

Creates a new invoice object. Returns an invoice object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • tax - This percentage is applied to the subtotal, including line items and discounts. Example: use 10.0 for 10.0%.
  • tax2 - This percentage is applied to the subtotal, including line items and discounts. Example: use 10.0 for 10.0%.
  • notes - Any additional notes to include on the invoice.
  • number - If no value is set, the number will be automatically generated.
  • subject - The invoice subject.
  • currency - The currency used by the invoice. If not provided, the client's currency will be used. See a list of supported currencies
  • discount - This percentage is subtracted from the subtotal. Example: use 10.0 for 10.0%.
  • due_date - Date the invoice is due. Defaults to the issue_date if no payment_term is specified. To set a custom due_date the payment_term must also be set to custom, otherwise the value supplied in the request for due_date will be ignored and the due_date will be calculated using the issue_date and the payment_term.
  • client_id - The ID of the client this invoice belongs to.
  • issue_date - Date the invoice was issued. Defaults to today's date.
  • line_items - Array of line item parameters
  • estimate_id - The ID of the estimate associated with this invoice.
  • retainer_id - The ID of the retainer you want to add funds to with this invoice. Note: retainers cannot be fully used (created, drawn against, closed, etc.) via the API at this time. The only available action is to add funds.
  • payment_term - The timeframe in which the invoice should be paid. Defaults to custom. Options: upon receipt, net 15, net 30, net 45, net 60, or custom.
  • purchase_order - The purchase order number.
  • payment_options - The payment options available to pay the invoice. Your account must be configured with the appropriate options under Settings > Integrations > Online payment to assign them. Options: [ach, credit_card, paypal]
  • line_items_import - An line items import object

Retrieve Project

retrieveProject

Retrieves the project with the given ID. Returns a project object and a 200 OK response code if a valid identifier was provided.

Parameters:

• path -
  • projectId -

Retrieve Task Assignment

retrieveTaskAssignment

Retrieves the task assignment with the given ID. Returns a task assignment object and a 200 OK response code if a valid identifier was provided.

Parameters:

• path -
  • projectId -
  • taskAssignmentId -

Delete Task Assignment

deleteTaskAssignment

Delete a task assignment. Deleting a task assignment is only possible if it has no time entries associated with it. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • projectId -
  • taskAssignmentId -

Projects Time Report

projectsTimeReport

Parameters:

• query -
  • to - Only report on time entries with a spent_date on or before the given date.
  • from - Only report on time entries with a spent_date on or after the given date.
  • page - The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • include_fixed_fee - When true, billable amounts will be calculated and included for fixed fee projects.

Stop Running Time Entry

stopRunningTimeEntry

Stopping a time entry is only possible if it's currently running. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • timeEntryId -

Create Time Entry

createTimeEntry

Creates a new time entry object. Returns a time entry object and a 201 Created response code if the call succeeded.

You should only use this method to create time entries when your account is configured to track time via duration. You can verify this by visiting the Settings page in your Harvest account or by checking if wants_timestamp_timers is false in the Company API.

Parameters:

• body -
  • hours - The current amount of time tracked. If provided, the time entry will be created with the specified hours and is_running will be set to false. If not provided, hours will be set to 0.0 and is_running will be set to true.
  • notes - Any notes to be associated with the time entry.
  • task_id - The ID of the task to associate with the time entry.
  • user_id - The ID of the user to associate with the time entry. Defaults to the currently authenticated user's ID.
  • ended_time - The time the entry ended. If provided, is_running will be set to false. If not provided, is_running will be set to true.
  • project_id - The ID of the project to associate with the time entry.
  • spent_date - The ISO 8601 formatted date the time entry was spent.
  • started_time - The time the entry started. Defaults to the current time. Example: "8:00am".
  • external_reference - An object containing the id, group_id, account_id, and permalink of the external reference.

Update Role

updateRole

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.

Parameters:

• body -
  • name - The name of the role.
  • user_ids - The IDs of the users assigned to this role.
• path -
  • roleId -

List Clients

listClients

Returns a list of your clients. The clients are returned sorted by creation date, with the most recently created clients appearing first.

The response contains an object with a clients property that contains an array of up to per_page clients. Each entry in the array is a separate client object. If no more clients are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your clients.

Parameters:

• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • is_active - Pass true to only return active clients and false to return inactive clients.
  • updated_since - Only return clients that have been updated since the given date and time.

List Contacts

listContacts

Returns a list of your contacts. The contacts are returned sorted by creation date, with the most recently created contacts appearing first.

The response contains an object with a contacts property that contains an array of up to per_page contacts. Each entry in the array is a separate contact object. If no more contacts are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your contacts.

Parameters:

• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • client_id - Only return contacts belonging to the client with the given ID.
  • updated_since - Only return contacts that have been updated since the given date and time.

Create Contact

createContact

Creates a new contact object. Returns a contact object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • fax - The contact's fax number.
  • email - The contact's email address.
  • title - The title of the contact.
  • client_id - The ID of the client associated with this contact.
  • last_name - The last name of the contact.
  • first_name - The first name of the contact.
  • phone_mobile - The contact's mobile phone number.
  • phone_office - The contact's office phone number.

Update Contact

updateContact

Updates the specific contact by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a contact object and a 200 OK response code if the call succeeded.

Parameters:

• body -
  • fax - The contact's fax number.
  • email - The contact's email address.
  • title - The title of the contact.
  • client_id - The ID of the client associated with this contact.
  • last_name - The last name of the contact.
  • first_name - The first name of the contact.
  • phone_mobile - The contact's mobile phone number.
  • phone_office - The contact's office phone number.
• path -
  • contactId -

Create Estimate Item Category

createEstimateItemCategory

Creates a new estimate item category object. Returns an estimate item category object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • name - The name of the estimate item category.

Retrieve Estimate Item Category

retrieveEstimateItemCategory

Retrieves the estimate item category with the given ID. Returns an estimate item category object and a 200 OK response code if a valid identifier was provided.

Parameters:

• path -
  • estimateItemCategoryId -

Delete Estimate Item Category

deleteEstimateItemCategory

Delete an estimate item category. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • estimateItemCategoryId -

Update Estimate Item Category

updateEstimateItemCategory

Updates the specific estimate item category by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns an estimate item category object and a 200 OK response code if the call succeeded.

Parameters:

• body -
  • name - The name of the estimate item category.
• path -
  • estimateItemCategoryId -

Create Estimate Message

createEstimateMessage

Creates a new estimate message object. Returns an estimate message object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • body - The message body.
  • subject - The message subject.
  • event_type - If provided, runs an event against the estimate. Options: "accept", "decline", "re-open", or "send".
  • recipients - Array of recipient parameters. See below for details.
  • send_me_a_copy - If set to true, a copy of the message email will be sent to the current user. Defaults to false.
• path -
  • estimateId -

List Estimates

listEstimates

Returns a list of your estimates. The estimates are returned sorted by issue date, with the most recently issued estimates appearing first.

The response contains an object with a estimates property that contains an array of up to per_page estimates. Each entry in the array is a separate estimate object. If no more estimates are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your estimates.

Parameters:

• query -
  • to - Only return estimates with an issue_date on or before the given date.
  • from - Only return estimates with an issue_date on or after the given date.
  • page - 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)
  • state - Only return estimates with a state matching the value provided. Options: draft, sent, accepted, or declined.
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • client_id - Only return estimates belonging to the client with the given ID.
  • updated_since - Only return estimates that have been updated since the given date and time.

Create Estimate

createEstimate

Creates a new estimate object. Returns an estimate object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • tax - This percentage is applied to the subtotal, including line items and discounts. Example: use 10.0 for 10.0%.
  • tax2 - This percentage is applied to the subtotal, including line items and discounts. Example: use 10.0 for 10.0%.
  • notes - Any additional notes to include on the estimate.
  • number - If no value is set, the number will be automatically generated.
  • subject - The estimate subject.
  • currency - The currency used by the estimate. If not provided, the client's currency will be used. See a list of supported currencies
  • discount - This percentage is subtracted from the subtotal. Example: use 10.0 for 10.0%.
  • client_id - The ID of the client this estimate belongs to.
  • issue_date - Date the estimate was issued. Defaults to today's date.
  • line_items - Array of line item parameters
  • purchase_order - The purchase order number.

Retrieve Estimate

retrieveEstimate

Retrieves the estimate with the given ID. Returns an estimate object and a 200 OK response code if a valid identifier was provided.

Parameters:

• path -
  • estimateId -

Delete Estimate

deleteEstimate

Delete an estimate. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • estimateId -

Update Estimate

updateEstimate

Updates the specific estimate by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns an estimate object and a 200 OK response code if the call succeeded.

Parameters:

• body -
  • tax - This percentage is applied to the subtotal, including line items and discounts. Example: use 10.0 for 10.0%.
  • tax2 - This percentage is applied to the subtotal, including line items and discounts. Example: use 10.0 for 10.0%.
  • notes - Any additional notes to include on the estimate.
  • number - If no value is set, the number will be automatically generated.
  • subject - The estimate subject.
  • currency - The currency used by the estimate. If not provided, the client's currency will be used. See a list of supported currencies
  • discount - This percentage is subtracted from the subtotal. Example: use 10.0 for 10.0%.
  • client_id - The ID of the client this estimate belongs to.
  • issue_date - Date the estimate was issued.
  • line_items - Array of line item parameters
  • purchase_order - The purchase order number.
• path -
  • estimateId -

List Messages For Estimate

listMessagesForEstimate

Returns a list of messages associated with a given estimate. The estimate messages are returned sorted by creation date, with the most recently created messages appearing first.

The response contains an object with an estimate_messages property that contains an array of up to per_page messages. Each entry in the array is a separate message object. If no more messages are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your messages.

Parameters:

• path -
  • estimateId -
• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • updated_since - Only return estimate messages that have been updated since the given date and time.

List Expense Categories

listExpenseCategories

Returns a list of your expense categories. The expense categories are returned sorted by creation date, with the most recently created expense categories appearing first.

The response contains an object with a expense_categories property that contains an array of up to per_page expense categories. Each entry in the array is a separate expense category object. If no more expense categories are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your expense categories.

Parameters:

• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • is_active - Pass true to only return active expense categories and false to return inactive expense categories.
  • updated_since - Only return expense categories that have been updated since the given date and time.

Update Expense Category

updateExpenseCategory

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.

Parameters:

• body -
  • name - The name of the expense category.
  • is_active - Whether the expense category is active or archived.
  • unit_name - The unit name of the expense category.
  • unit_price - The unit price of the expense category.
• path -
  • expenseCategoryId -

List Expenses

listExpenses

Returns a list of your expenses. If accessing this endpoint as an Administrator, all expenses in the account will be returned. If accessing this endpoint as a Manager, all expenses for assigned teammates and managed projects will be returned. The expenses are returned sorted by the spent_at date, with the most recent expenses appearing first.

The response contains an object with a expenses property that contains an array of up to per_page expenses. Each entry in the array is a separate expense object. If no more expenses are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your expenses.

Parameters:

• query -
  • to - Only return expenses with a spent_date on or before the given date.
  • from - Only return expenses with a spent_date on or after the given date.
  • page - 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)
  • user_id - Only return expenses belonging to the user with the given ID.
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • client_id - Only return expenses belonging to the client with the given ID.
  • is_billed - Pass true to only return expenses that have been invoiced and false to return expenses that have not been invoiced.
  • project_id - Only return expenses belonging to the project with the given ID.
  • updated_since - Only return expenses that have been updated since the given date and time.
  • approval_status - Only return expenses with the given approval status. Possible values: "unsubmitted", "submitted", or "approved".

Create Expense

createExpense

Creates a new expense object. Returns an expense object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • notes - Textual notes used to describe the expense.
  • units - The quantity of units to use in calculating the total_cost of the expense.
  • receipt - A receipt file to attach to the expense. If including a receipt, you must submit a multipart/form-data request.
  • user_id - The ID of the user associated with this expense. Defaults to the ID of the currently authenticated user.
  • billable - Whether this expense is billable or not. Defaults to true.
  • project_id - The ID of the project associated with this expense.
  • spent_date - Date the expense occurred.
  • total_cost - The total amount of the expense.
  • expense_category_id - The ID of the expense category this expense is being tracked against.

Update Expense

updateExpense

Updates the specific expense by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns an expense object and a 200 OK response code if the call succeeded.

Note that changes to project_id and expense_category_id will be silently dropped if the expense is locked. Users with sufficient permissions are able to update the rest of a locked expense's attributes.

Parameters:

• body -
  • notes - Textual notes used to describe the expense.
  • units - The quantity of units to use in calculating the total_cost of the expense.
  • receipt - A receipt file to attach to the expense. If including a receipt, you must submit a multipart/form-data request.
  • billable - Whether this expense is billable or not. Defaults to true.
  • project_id - The ID of the project associated with this expense.
  • spent_date - Date the expense occurred.
  • total_cost - The total amount of the expense.
  • delete_receipt - Whether an attached expense receipt should be deleted. Pass true to delete the expense receipt.
  • expense_category_id - The ID of the expense category this expense is being tracked against.
• path -
  • expenseId -

List Invoice Item Categories

listInvoiceItemCategories

Returns a list of your invoice item categories. The invoice item categories are returned sorted by creation date, with the most recently created invoice item categories appearing first.

The response contains an object with a invoice_item_categories property that contains an array of up to per_page invoice item categories. Each entry in the array is a separate invoice item category object. If no more invoice item categories are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your invoice item categories.

Parameters:

• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • updated_since - Only return invoice item categories that have been updated since the given date and time.

Create Invoice Item Category

createInvoiceItemCategory

Creates a new invoice item category object. Returns an invoice item category object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • name - The name of the invoice item category.

Retrieve Invoice Item Category

retrieveInvoiceItemCategory

Retrieves the invoice item category with the given ID. Returns an invoice item category object and a 200 OK response code if a valid identifier was provided.

Parameters:

• path -
  • invoiceItemCategoryId -

Delete Invoice Item Category

deleteInvoiceItemCategory

Delete an invoice item category. Deleting an invoice item category is only possible if use_as_service and use_as_expense are both false. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • invoiceItemCategoryId -

Update Invoice Item Category

updateInvoiceItemCategory

Updates the specific invoice item category by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns an invoice item category object and a 200 OK response code if the call succeeded.

Parameters:

• body -
  • name - The name of the invoice item category.
• path -
  • invoiceItemCategoryId -

List Invoices

listInvoices

Returns a list of your invoices. The invoices are returned sorted by issue date, with the most recently issued invoices appearing first.

The response contains an object with a invoices property that contains an array of up to per_page invoices. Each entry in the array is a separate invoice object. If no more invoices are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your invoices.

Parameters:

• query -
  • to - Only return invoices with an issue_date on or before the given date.
  • from - Only return invoices with an issue_date on or after the given date.
  • page - 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)
  • state - Only return invoices with a state matching the value provided. Options: draft, open, paid, or closed.
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 100)
  • client_id - Only return invoices belonging to the client with the given ID.
  • project_id - Only return invoices associated with the project with the given ID.
  • updated_since - Only return invoices that have been updated since the given date and time.

Delete Invoice

deleteInvoice

Delete an invoice. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • invoiceId -

Create Project

createProject

Creates a new project object. Returns a project object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • fee - The amount you plan to invoice for the project. Only used by fixed-fee projects.
  • code - The code associated with the project.
  • name - The name of the project.
  • notes - Project notes.
  • budget - The budget in hours for the project when budgeting by time.
  • bill_by - The method by which the project is invoiced. Options: Project, Tasks, People, or none.
  • ends_on - Date the project will end.
  • budget_by - 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).
  • client_id - The ID of the client to associate this project with.
  • is_active - Whether the project is active or archived. Defaults to true.
  • starts_on - Date the project was started.
  • cost_budget - The monetary budget for the project when budgeting by money.
  • hourly_rate - Rate for projects billed by Project Hourly Rate.
  • is_billable - Whether the project is billable or not.
  • is_fixed_fee - Whether the project is a fixed-fee project or not.
  • budget_is_monthly - Option to have the budget reset every month. Defaults to false.
  • show_budget_to_all - Option to show project budget to all employees. Does not apply to Total Project Fee projects. Defaults to false.
  • notify_when_over_budget - Whether Project Managers should be notified when the project goes over budget. Defaults to false.
  • cost_budget_include_expenses - Option for budget of Total Project Fees projects to include tracked expenses. Defaults to false.
  • over_budget_notification_percentage - Percentage value used to trigger over budget email alerts. Example: use 10.0 for 10.0%.

Update Invoice

updateInvoice

Updates the specific invoice by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns an invoice object and a 200 OK response code if the call succeeded.

Parameters:

• body -
  • tax - This percentage is applied to the subtotal, including line items and discounts. Example: use 10.0 for 10.0%.
  • tax2 - This percentage is applied to the subtotal, including line items and discounts. Example: use 10.0 for 10.0%.
  • notes - Any additional notes to include on the invoice.
  • number - If no value is set, the number will be automatically generated.
  • subject - The invoice subject.
  • currency - The currency used by the invoice. If not provided, the client's currency will be used. See a list of supported currencies
  • discount - This percentage is subtracted from the subtotal. Example: use 10.0 for 10.0%.
  • due_date - Date the invoice is due.
  • client_id - The ID of the client this invoice belongs to.
  • issue_date - Date the invoice was issued.
  • line_items - Array of line item parameters
  • estimate_id - The ID of the estimate associated with this invoice.
  • retainer_id - The ID of the retainer associated with this invoice.
  • payment_term - The timeframe in which the invoice should be paid. Options: upon receipt, net 15, net 30, net 45, or net 60.
  • purchase_order - The purchase order number.
  • payment_options - The payment options available to pay the invoice. Your account must be configured with the appropriate options under Settings > Integrations > Online payment to assign them. Options: [ach, credit_card, paypal]
• path -
  • invoiceId -

List Messages For Invoice

listMessagesForInvoice

Returns a list of messages associated with a given invoice. The invoice messages are returned sorted by creation date, with the most recently created messages appearing first.

The response contains an object with an invoice_messages property that contains an array of up to per_page messages. Each entry in the array is a separate message object. If no more messages are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your messages.

Parameters:

• path -
  • invoiceId -
• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • updated_since - Only return invoice messages that have been updated since the given date and time.

Create Invoice Message

createInvoiceMessage

Creates a new invoice message object and sends it. Returns an invoice message object and a 201 Created response code if the call succeeded.

A note about the optional event_type parameter: If event_type is omitted in a request, its default value of null means the message will be sent. In such a request, if the recipients array is omitted or empty and send_me_a_copy is also omitted or set to false, the request will fail because the message has no recipients. When omitting event_type to create and send a message, be sure to include a recipients array as a parameter or ensure the send_me_a_copy parameter is included and set to true.

Parameters:

• body -
  • body - The message body.
  • subject - The message subject.
  • thank_you - If set to true, a thank you message email will be sent. Defaults to false.
  • attach_pdf - If set to true, a PDF of the invoice will be attached to the message email. Defaults to false.
  • event_type - Omit when intending to create and send a message. If omitted, the default value is null and the message will be sent. See other sections below for including this parameter with the following options: close, draft, re-open, or send (which marks a draft invoice as sent, it does not send the message).
  • recipients - Array of recipient parameters. See below for more details.
  • send_me_a_copy - If set to true, a copy of the message email will be sent to the current user. Defaults to false.
  • include_link_to_client_invoice - DEPRECATED A link to the client invoice URL will be automatically included in the message email if payment_options have been assigned to the invoice. Setting to true will be ignored. Setting to false will clear all payment_options on the invoice.
• path -
  • invoiceId -

Retrieve Invoice Message Subject And Body For Specific Invoice

retrieveInvoiceMessageSubjectAndBodyForSpecificInvoice

Returns the subject and body text as configured in Harvest of an invoice message for a specific invoice and a 200 OK response code if the call succeeded. Does not create the invoice message. If no parameters are passed, will return the subject and body of a general invoice message for the specific invoice.

Parameters:

• path -
  • invoiceId -
• query -
  • reminder - Set to true to return the subject and body of a reminder invoice message for the specific invoice.
  • thank_you - Set to true to return the subject and body of a thank-you invoice message for the specific invoice.

Create Invoice Payment

createInvoicePayment

Creates a new invoice payment object. Returns an invoice payment object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • notes - Any notes to be associated with the payment.
  • amount - The amount of the payment.
  • paid_at - Date and time the payment was made. Pass either paid_at or paid_date, but not both.
  • paid_date - Date the payment was made. Pass either paid_at or paid_date, but not both.
  • send_thank_you - Whether or not to send a thank you email (if enabled for your account in Invoices > Configure > Messages). Only sends an email if the invoice will be fully paid after creating this payment. Defaults to true.
• path -
  • invoiceId -

Create Task Assignment

createTaskAssignment

Creates a new task assignment object. Returns a task assignment object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • budget - Budget used when the project's budget_by is task or task_fees.
  • task_id - The ID of the task to associate with the project.
  • billable - Whether the task assignment is billable or not. Defaults to false.
  • is_active - Whether the task assignment is active or archived. Defaults to true.
  • hourly_rate - Rate used when the project's bill_by is Tasks. Defaults to null when billing by task hourly rate, otherwise 0.
• path -
  • projectId -

Update Task Assignment

updateTaskAssignment

Updates the specific task assignment by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a task assignment object and a 200 OK response code if the call succeeded.

Parameters:

• body -
  • budget - Budget used when the project's budget_by is task or task_fees.
  • billable - Whether the task assignment is billable or not.
  • is_active - Whether the task assignment is active or archived.
  • hourly_rate - Rate used when the project's bill_by is Tasks.
• path -
  • projectId -
  • taskAssignmentId -

List User Assignments For Specific Project

listUserAssignmentsForSpecificProject

Returns a list of user assignments for the project identified by PROJECT_ID. The user assignments are returned sorted by creation date, with the most recently created user assignments appearing first.

The response contains an object with a user_assignments property that contains an array of up to per_page user assignments. Each entry in the array is a separate user assignment object. If no more user assignments are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your user assignments.

Parameters:

• path -
  • projectId -
• query -
  • page - 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)
  • user_id - Only return user assignments belonging to the user with the given ID.
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • is_active - Pass true to only return active user assignments and false to return inactive user assignments.
  • updated_since - Only return user assignments that have been updated since the given date and time.

Create User Assignment

createUserAssignment

Creates a new user assignment object. Returns a user assignment object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • budget - Budget used when the project's budget_by is person.
  • user_id - The ID of the user to associate with the project.
  • is_active - Whether the user assignment is active or archived. Defaults to true.
  • hourly_rate - Custom rate used when the project's bill_by is People and use_default_rates is false. Defaults to 0.
  • use_default_rates - Determines which billable rate(s) will be used on the project for this user when bill_by is People. When true, the project will use the user's default billable rates. When false, the project will use the custom rate defined on this user assignment. Defaults to true.
  • is_project_manager - Determines if the user has Project Manager permissions for the project. Defaults to false for users with Regular User permissions and true for those with Project Managers or Administrator permissions.
• path -
  • projectId -

Delete User Assignment

deleteUserAssignment

Delete a user assignment. Deleting a user assignment is only possible if it has no time entries or expenses associated with it. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • projectId -
  • userAssignmentId -

Tasks Report

tasksReport

Parameters:

• query -
  • to - Only report on time entries with a spent_date on or before the given date.
  • from - Only report on time entries with a spent_date on or after the given date.
  • page - The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • include_fixed_fee - When true, billable amounts will be calculated and included for fixed fee projects.

Update User Assignment

updateUserAssignment

Updates the specific user assignment by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a user assignment object and a 200 OK response code if the call succeeded.

Parameters:

• body -
  • budget - Budget used when the project's budget_by is person.
  • is_active - Whether the user assignment is active or archived.
  • hourly_rate - Custom rate used when the project's bill_by is People and use_default_rates is false.
  • use_default_rates - 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.
  • is_project_manager - Determines if the user has Project Manager permissions for the project.
• path -
  • projectId -
  • userAssignmentId -

Expense Categories Report

expenseCategoriesReport

Parameters:

• query -
  • to - Only report on expenses with a spent_date on or before the given date.
  • from - Only report on expenses with a spent_date on or after the given date.
  • page - The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)

Clients Expenses Report

clientsExpensesReport

Parameters:

• query -
  • to - Only report on expenses with a spent_date on or before the given date.
  • from - Only report on expenses with a spent_date on or after the given date.
  • page - The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)

Projects Expenses Report

projectsExpensesReport

Parameters:

• query -
  • to - Only report on expenses with a spent_date on or before the given date.
  • from - Only report on expenses with a spent_date on or after the given date.
  • page - The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)

Team Expenses Report

teamExpensesReport

Parameters:

• query -
  • to - Only report on expenses with a spent_date on or before the given date.
  • from - Only report on expenses with a spent_date on or after the given date.
  • page - The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)

Project Budget Report

projectBudgetReport

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.

Parameters:

• query -
  • page - The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • is_active - Pass true to only return active projects and false to return inactive projects.

Clients Time Report

clientsTimeReport

Parameters:

• query -
  • to - Only report on time entries with a spent_date on or before the given date.
  • from - Only report on time entries with a spent_date on or after the given date.
  • page - The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • include_fixed_fee - When true, billable amounts will be calculated and included for fixed fee projects.

List Task Assignments

listTaskAssignments

Returns a list of your task assignments. The task assignments are returned sorted by creation date, with the most recently created task assignments appearing first.

The response contains an object with a task_assignments property that contains an array of up to per_page task assignments. Each entry in the array is a separate task assignment object. If no more task assignments are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your task assignments.

Parameters:

• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • is_active - Pass true to only return active task assignments and false to return inactive task assignments.
  • updated_since - Only return task assignments that have been updated since the given date and time.

List Tasks

listTasks

Returns a list of your tasks. The tasks are returned sorted by creation date, with the most recently created tasks appearing first.

The response contains an object with a tasks property that contains an array of up to per_page tasks. Each entry in the array is a separate task object. If no more tasks are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your tasks.

Parameters:

• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • is_active - Pass true to only return active tasks and false to return inactive tasks.
  • updated_since - Only return tasks that have been updated since the given date and time.

Retrieve Task

retrieveTask

Retrieves the task with the given ID. Returns a task object and a 200 OK response code if a valid identifier was provided.

Parameters:

• path -
  • taskId -

Delete Task

deleteTask

Delete a task. Deleting a task is only possible if it has no time entries associated with it. Returns a 200 OK response code if the call succeeded.

Parameters:

• path -
  • taskId -

Update Task

updateTask

Updates the specific task by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a task object and a 200 OK response code if the call succeeded.

Parameters:

• body -
  • name - The name of the task.
  • is_active - Whether this task is active or archived.
  • is_default - Whether this task should be automatically added to future projects.
  • billable_by_default - Used in determining whether default tasks should be marked billable when creating a new project.
  • default_hourly_rate - The default hourly rate to use for this task when it is added to a project.
• path -
  • taskId -

List Time Entries

listTimeEntries

Returns a list of time entries. The time entries are returned sorted by spent_date date. At this time, the sort option can't be customized.

The response contains an object with a time_entries property that contains an array of up to per_page time entries. Each entry in the array is a separate time entry object. If no more time entries are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your time entries.

Parameters:

• query -
  • to - Only return time entries with a spent_date on or before the given date.
  • from - Only return time entries with a spent_date on or after the given date.
  • page - 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)
  • task_id - Only return time entries belonging to the task with the given ID.
  • user_id - Only return time entries belonging to the user with the given ID.
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • client_id - Only return time entries belonging to the client with the given ID.
  • is_billed - Pass true to only return time entries that have been invoiced and false to return time entries that have not been invoiced.
  • is_running - Pass true to only return running time entries and false to return non-running time entries.
  • project_id - Only return time entries belonging to the project with the given ID.
  • updated_since - Only return time entries that have been updated since the given date and time. Use the ISO 8601 Format.
  • approval_status - Only return time entries with the given approval status. Possible values: "unsubmitted", "submitted", or "approved".
  • external_reference_id - Only return time entries with the given external_reference ID.

Update Time Entry

updateTimeEntry

Updates the specific time entry by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a time entry object and a 200 OK response code if the call succeeded.

Parameters:

• body -
  • hours - The current amount of time tracked.
  • notes - Any notes to be associated with the time entry.
  • task_id - The ID of the task to associate with the time entry.
  • ended_time - The time the entry ended.
  • project_id - The ID of the project to associate with the time entry.
  • spent_date - The ISO 8601 formatted date the time entry was spent.
  • started_time - The time the entry started. Defaults to the current time. Example: "8:00am".
  • external_reference - An object containing the id, group_id, account_id, and permalink of the external reference.
• path -
  • timeEntryId -

List User Assignments

listUserAssignments

Returns a list of your projects user assignments, active and archived. The user assignments are returned sorted by creation date, with the most recently created user assignments appearing first.

The response contains an object with a user_assignments property that contains an array of up to per_page user assignments. Each entry in the array is a separate user assignment object. If no more user assignments are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your user assignments.

Parameters:

• query -
  • page - 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)
  • cursor - Pagination cursor
  • user_id - Only return user assignments belonging to the user with the given ID.
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • is_active - Pass true to only return active user assignments and false to return inactive user assignments.
  • updated_since - Only return user assignments that have been updated since the given date and time.

List Users

listUsers

Returns a list of your users. The users are returned sorted by creation date, with the most recently created users appearing first.

The response contains an object with a users property that contains an array of up to per_page users. Each entry in the array is a separate user object. If no more users are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your users.

Parameters:

• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • is_active - Pass true to only return active users and false to return inactive users.
  • updated_since - Only return users that have been updated since the given date and time.

Create User

createUser

Creates a new user object and sends an invitation email to the address specified in the email parameter. Returns a user object and a 201 Created response code if the call succeeded.

Parameters:

• body -
  • email - The email address of the user.
  • roles - Descriptive names of the business roles assigned to this person. They can be used for filtering reports, and have no effect in their permissions in Harvest.
  • timezone - The user's timezone. Defaults to the company's timezone. See a list of supported time zones.
  • cost_rate - The cost rate to use for this user when calculating a project's costs vs billable amount. Defaults to 0.
  • is_active - Whether the user is active or archived. Defaults to true.
  • last_name - The last name of the user.
  • first_name - The first name of the user.
  • access_roles - Access role(s) that determine the user's permissions in Harvest. Possible values: administrator, manager or member. Users with the manager role can additionally be granted one or more of these roles: project_creator, billable_rates_manager, managed_projects_invoice_drafter, managed_projects_invoice_manager, client_and_task_manager, time_and_expenses_manager, estimates_manager.
  • is_contractor - Whether the user is a contractor or an employee. Defaults to false.
  • weekly_capacity - The number of hours per week this person is available to work in seconds. Defaults to 126000 seconds (35 hours).
  • default_hourly_rate - The billable rate to use for this user when they are added to a project. Defaults to 0.
  • has_access_to_all_future_projects - Whether the user should be automatically added to future projects. Defaults to false.

Update User

updateUser

Updates the specific user by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a user object and a 200 OK response code if the call succeeded.

Parameters:

• body -
  • email - The email address of the user. Can't be updated if the user is inactive.
  • roles - Descriptive names of the business roles assigned to this person. They can be used for filtering reports, and have no effect in their permissions in Harvest.
  • timezone - The user's timezone. Defaults to the company's timezone. See a list of supported time zones.
  • is_active - Whether the user is active or archived.
  • last_name - The last name of the user. Can't be updated if the user is inactive.
  • first_name - The first name of the user. Can't be updated if the user is inactive.
  • access_roles - Access role(s) that determine the user's permissions in Harvest. Possible values: administrator, manager or member. Users with the manager role can additionally be granted one or more of these roles: project_creator, billable_rates_manager, managed_projects_invoice_drafter, managed_projects_invoice_manager, client_and_task_manager, time_and_expenses_manager, estimates_manager.
  • is_contractor - Whether the user is a contractor or an employee.
  • weekly_capacity - The number of hours per week this person is available to work in seconds.
  • has_access_to_all_future_projects - Whether the user should be automatically added to future projects.
• path -
  • userId -

List Billable Rates For Specific User

listBillableRatesForSpecificUser

Returns a list of billable rates for the user identified by USER_ID. The billable rates are returned sorted by start_date, with the oldest starting billable rates appearing first.

The response contains an object with a billable_rates property that contains an array of up to per_page billable rates. Each entry in the array is a separate billable rate object. If no more billable rates are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your billable rates.

Parameters:

• path -
  • userId -
• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)

Create Billable Rate

createBillableRate

Creates a new billable rate object. Returns a billable rate object and a 201 Created response code if the call succeeded.

Creating a billable rate with no start_date will replace a user's existing rate(s). Creating a billable rate with a start_date that is before a user's existing rate(s) will replace those billable rates with the new one.

Parameters:

• body -
  • amount - The amount of the billable rate.
  • start_date - The date the billable rate is effective. Cannot be a date in the future.
• path -
  • userId -

List Cost Rates For Specific User

listCostRatesForSpecificUser

Returns a list of cost rates for the user identified by USER_ID. The cost rates are returned sorted by start_date, with the oldest starting cost rates appearing first.

The response contains an object with a cost_rates property that contains an array of up to per_page cost rates. Each entry in the array is a separate cost rate object. If no more cost rates are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your cost rates.

Parameters:

• path -
  • userId -
• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)

Create Cost Rate

createCostRate

Creates a new cost rate object. Returns a cost rate object and a 201 Created response code if the call succeeded.

Creating a cost rate with no start_date will replace a user's existing rate(s). Creating a cost rate with a start_date that is before a user's existing rate(s) will replace those cost rates with the new one.

Parameters:

• body -
  • amount - The amount of the cost rate.
  • start_date - The date the cost rate is effective. Cannot be a date in the future.
• path -
  • userId -

List Active Project Assignments

listActiveProjectAssignments

Returns a list of active project assignments for the user identified by USER_ID. The project assignments are returned sorted by creation date, with the most recently created project assignments appearing first.

The response contains an object with a project_assignments property that contains an array of up to per_page project assignments. Each entry in the array is a separate project assignment object. If no more project assignments are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your project assignments.

Parameters:

• path -
  • userId -
• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • updated_since - Only return project assignments that have been updated since the given date and time.

List Assigned Teammates For Specific User

listAssignedTeammatesForSpecificUser

Returns a list of assigned teammates for the user identified by USER_ID. The USER_ID must belong to a user that is a Manager, if not, a 422 Unprocessable Entity status code will be returned.

The response contains an object with a teammates property that contains an array of up to per_page teammates. Each entry in the array is a separate teammate object. If no more teammates are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your teammates.

Parameters:

• path -
  • userId -
• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)

Update User Assigned Teammates

updateUserAssignedTeammates

Updates the the assigned teammates for a specific user. Returns list of assigned teammates and a 200 OK response code if the call succeeded. The USER_ID must belong to a user that is a Manager, if not, a 422 Unprocessable Entity status code will be returned.

Adding teammates for the first time will add the people_manager access role to the Manager. Any IDs not included in the teammate_ids that are currently assigned will be unassigned from the Manager. Use an empty array to unassign all users. This will also remove the people_manager access role from the Manager.

Parameters:

• body -
  • teammate_ids - Full list of user IDs to be assigned to the Manager.
• path -
  • userId -

List Projects

listProjects

Returns a list of your projects. The projects are returned sorted by creation date, with the most recently created projects appearing first.

The response contains an object with a projects property that contains an array of up to per_page projects. Each entry in the array is a separate project object. If no more projects are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your projects.

Parameters:

• query -
  • page - 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)
  • cursor - Pagination cursor
  • per_page - The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
  • client_id - Only return projects belonging to the client with the given ID.
  • is_active - Pass true to only return active projects and false to return inactive projects.
  • updated_since - Only return projects that have been updated since the given date and time.