× FreshBooks App Logo
FreshBooks
Official App
Free - Google Play
Get it
You're currently on our US site. Select your regional site here:

Tasks

General Info

Tasks in Freshbooks represent services that your business offers to clients. Tasks are used to keep track of invoicing details of the service such as name and hourly rate. Tasks are automatically created for each project service and updates to tasks are reflected in the corresponding service and vice versa.

In general, when working with a project, use the services endpoint. When working with an invoice, use tasks.

Access Requirements

AccessRequires Authorization
Scopesuser:billable_items:read
user:billable_items:write

Includes

Include NameDescription
projectsList of Projects that contain the task

Filters

Filter TypeNameFieldDescription
Equalstaskidtaskidunique id related to a task
Intaskidstaskidmatches list of taskids, one specified per query arg
Equalsbillablebillabletrue if task is billable
Betweenrate_minratelist tasks with rates equal or greater
Betweenrate_maxratelist tasks with rates equal or less
Betweenupdated_minupdatedlist of tasks that have been updated since the given date
Betweenupdated_maxupdatedlist of tasks that have been updated before the given date
Inprojectidsprojectidmatches list of projectids, one specified per query arg

Field Descriptions

underlined fields are required on creation

FieldTypeDescription
idintthe unique id for the task
taskidintduplicate of id
namestringthe name of the task
descriptionstringthe description of the task
rateobjectsubfields: amount, code
– amountstringthe hourly amount charged for the task
– codestringthe currency of the rate
billablebooleantrue if the task is billable
tax1intid of tax on task
tax2intid of tax on task
updatedDateTimethe Date/Time the task was last updated
vis_stateint0 marks the task as active, 1 if inactive

Get a Single Task

Request: GET 

https://api.freshbooks.com/accounting/account/<account_id>/projects/tasks/<task_id>

Response:


{
 "response": {
   "result": {
     "task": {
       "billable": true,
       "description": "Piloting based on expectations of the executive",
       "id": 159361,
       "name": "Piloting",
       "rate": {
         "amount": "100.00",
         "code": "CAD"
       },
       "taskid": 159361,
       "tax1": 0,
       "tax2": 0,
       "tdesc": "Piloting based on expectations of the executive",
       "tname": "Piloting",
       "updated": "2017-07-24 09:39:21",
       "vis_state": 0
       }
     }
   }
 }

Create a Task

Request: POST 

https://api.freshbooks.com/accounting/account/<account_id>/projects/tasks


  {
  "task": {
   "name": "Consulting"
  }


Update a Task



Request: PUT 

https://api.freshbooks.com/accounting/account/<account_id>/projects/tasks/<task_id>


{
 "task": {
  "name": "Walking Dogs",
  "rate": {
    "amount": "25.47",
    "code": "CAD"
   }
  }
}


Response:


{
 "response": {
   "result": {
     "task": {
       "billable": true,
       "description": "",
       "id": 159365,
       "name": "Walking Dogs",
       "rate": {
         "amount": "25.47",
         "code": "CAD"
        },
       "taskid": 159365,
       "tax1": 0,
       "tax2": 0,
       "tname": "Walking Dogs",
       "tdesc": "",
       "updated": "2017-07-24 10:09:18",
       "vis_state": 0
       }
     }
   }
 }

Delete a Task

Request: PUT 

https://api.freshbooks.com/accounting/account/<account_id>/projects/tasks/<task_id>


{
 "task": {
    "vis_state": 1
   }
}


Response:


{
 "response": {
   "result": {
     "task": {
       "billable": true,
       "description": "",
       "id": 159365,
       "name": "Walking Dogs",
       "rate": {
        "amount": "25.47",
        "code": "CAD"
       },
       "taskid": 159365,
       "tax1": 0,
       "tax2": 0,
       "tname": "Walking Dogs",
       "tdesc": "",
       "updated": "2017-07-24 10:13:38",
       "vis_state": 1
       }
     }
   }
 }

Listing Tasks

Request: GET 

https://api.freshbooks.com/accounting/account/<account_id>/projects/tasks

Response:


  {
    "response": {
       "result": {
         "total": 3,
          "per_page": 15,
          "tasks": [
            {
                //same as single task
            },
            {
                //same as single task
            },
            {
                //same as single task
            }
          ],
          "page": 1,
          "pages": 1
          }
        }
      }

Search examples

Some Task Search Examples:

 

https://api.freshbooks.com/accounting/account//projects/tasks?search[billable]=false 


Returns all the tasks that are not billable

 

https://api.freshbooks.com/accounting/account/;/projects/tasks?search[rate_min]=25&search[rate_max]=75


Returns all the tasks with a rate between $25 and $100