Categories

Staff have access to the get, list and create API calls listed below if the Expenses tab is enabled for staff. Staff cannot delete or update Categories.

The Categories API provides access to the Expense Categories in the application. They relate to the category_id field as used in the Expenses API.

category.create

Create a new category. If successful, returns the category_id of the newly created item.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="category.create">
  <category>
    <name>Gasoline</name>  <!-- (Required) Category name -->
  </category>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <category_id>00000000012</category_id>
</response>

category.update

Update an existing expense category with the given category_id. Any category fields left out of the request will remain unchanged.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="category.update">
  <category>
    <category_id>00000000012</category_id>  <!-- Category to update -->
    <name>Gasoline</name>  <!-- (Optional) Category name -->
  </category>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok"/>

category.get

Return the complete category details associated with the given category_id.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="category.get">
  <category_id>00000000012</category_id>
</request>

Response

<?xml version="1.0"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <category>
  <category_id>00000000012</category_id>
  <name>Gasoline</name>
  </category>
</response>

category.delete

Delete an existing expense category.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="category.delete">
  <category_id>00000000012</category_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok"/>

category.list

Returns a list of expense categories.

Note: This method uses pagination.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="category.list">
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <categories page="1" per_page="100" pages="1" total="20">
    <category>
      <category_id>00000000001</category_id>
      <name>Food</name>
      <parent_id>00000000001</parent_id>
    </category>
    <category>
      <category_id>00000000002</category_id>
      <name>Parking</name>
      <parent_id>00000000001</parent_id>
    </category>
  </categories>
</response>

A hierarchy of categories and subcategories can be requested using an
empty parent_id element.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="category.list">
  <parent_id></parent_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <categories page="1" per_page="25" pages="1" total="14">
    <category>
      <category_id>00000000001</category_id>
      <name>Fees</name>
      <parent_id></parent_id>
      <subcategories>
        <category>
          <category_id>4</category_id>
          <name>Bank Fees</name>
          <parent_id>00000000001</parent_id>
        </category>
        <category>
          <category_id>3</category_id>
          <name>Business Insurance</name>
          <parent_id>00000000001</parent_id>
        </category>
     </subcategories>
  </category>
</response>

Search