Top

Expenses

List expenses
GET /expenses
List expenses with pagination.
Get an expense
GET /expenses/:expense_id
Get the details of an expense.
Create an expense
POST /expenses
Create a billable or non-billable expense.
Update an expense
PUT /expenses/:expense_id
Update an existing expense.
Delete an expense
DELETE /expenses/:expense_id
Delete an existing expense.
List expense comments & history
GET /expenses/:expense_id/comments
Get history and comments of an expense.

List expenses

GET  /expenses

List expenses with pagination.

Parameters

description string
[100]
Search expenses by description.
Variants: description_startswith and description_contains
reference_number string
[100]
Search expenses by reference number.
Variants: reference_number_startswith and reference_number_contains
date string
[yyyy-mm-dd]
Search expenses by expense date.
Variants: date_start, date_end, date_before and date_after
status string Search expenses by expense status.
Allowed Values: unbilled, invoiced, reimbursed, non-billable and billable
account_name string
[100]
Search expenses by expense account name.
Variants: account_name_startswith and account_name_contains
amount double Search expenses by amount.
Variants: amount_less_than, amount_less_equals, amount_greater_than and amount_greater_equals
customer_name string
[100]
Search expenses by customer name.
Variants: customer_name_startswith and customer_name_contains
customer_id string Search expenses by customer id.
recurring_expense_id string Search expenses by recurring expense id.
paid_through_account_id string Search expenses by paid through account id.
filter_by string Filter expenses by expense status.
Allowed Values: Status.All, Status.Billable, Status.Nonbillable, Status.Reimbursed, Status.Invoiced and Status.Unbilled
search_text string
[100]
Search expenses by account name or description or customer name or vendor name.
sort_column string Sort expenses.
Allowed Values: date, account_name, total, bcy_total, reference_number, customer_name, and created_time
project_id string Search expenses by project id.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "expenses": [
    {
      "expense_id": "982000000567250",
      "date": "2013-11-18",
      "account_name": "Rent",
      "description": "",
      "currency_id": "982000000000190",
      "currency_code": "USD",
      "bcy_total": 281.25,
      "total": 281.25,
      "is_billable": true,
      "reference_number": "",
      "customer_id": "982000000567001",
      "customer_name": "Bowman & Co",
      "status": "unbilled",
      "created_time": "2013-11-18T02:41:36-0800",
      "last_modified_time": "2013-11-18T02:41:36-0800",
      "expense_receipt_name": ""
    },
    {
      "expense_id": "982000000567226",
      "date": "2013-11-18",
      "account_name": "Rent",
      "description": "",
      "currency_id": "982000000000190",
      "currency_code": "USD",
      "bcy_total": 506.61,
      "total": 506.61,
      "is_billable": false,
      "reference_number": "",
      "customer_id": "",
      "customer_name": "",
      "status": "nonbillable",
      "created_time": "2013-11-18T02:39:40-0800",
      "last_modified_time": "2013-11-18T02:39:49-0800",
      "expense_receipt_name": ""
    },
    {
      "expense_id": "982000000567216",
      "date": "2013-11-18",
      "account_name": "Marketing",
      "description": "",
      "currency_id": "982000000000190",
      "currency_code": "USD",
      "bcy_total": 124.31,
      "total": 124.31,
      "is_billable": true,
      "reference_number": "#562SD23R4",
      "customer_id": "982000000567001",
      "customer_name": "Bowman & Co",
      "status": "unbilled",
      "created_time": "2013-11-18T02:39:14-0800",
      "last_modified_time": "2013-11-18T04:22:52-0800",
      "expense_receipt_name": ""
    }
  ],
  "page_context": {
    "page": 1,
    "per_page": 200,
    "has_more_page": false,
    "report_name": "Expenses",
    "applied_filter": "Status.All",
    "sort_column": "created_time",
    "sort_order": "D"
  }
}

Get an expense

GET  /expenses/:expense_id

Get the details of an expense.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "expense": {
    "expense_id": "982000000567216",
    "expense_item_id": "982000000567220",
    "account_id": "982000000561057",
    "account_name": "Marketing",
    "date": "2013-11-18",
    "tax_id": "982000000566007",
    "tax_name": "Sales Tax",
    "tax_percentage": 10.5,
    "currency_id": "982000000000190",
    "currency_code": "USD",
    "exchange_rate": 1.00,
    "tax_amount": 11.81,
    "sub_total": 112.50,
    "total": 124.31,
    "bcy_total": 124.31,
    "amount": 112.50,
    "is_inclusive_tax": false,
    "reference_number": "#562SD23R4",
    "description": "",
    "is_billable": true,
    "customer_id": "982000000567001",
    "customer_name": "Bowman & Co",
    "expense_receipt_name": "",
    "expense_receipt_type": "",
    "created_time": "2013-11-18T02:39:14-0800",
    "last_modified_time": "2013-11-18T04:22:52-0800",
    "status": "unbilled",
    "invoice_id": "",
    "invoice_number": "",
    "project_id": "",
    "project_name": ""
  }
}

Create an expense

POST  /expenses

Create a billable or non-billable expense.

multipart/form-data

receipt file Expense receipt file to attach.
Allowed Extensions: gif, png, jpeg, jpg, bmp and pdf

Request attributes

account_id string ID of the expense account.
paid_through_account_id string ID of the cash/ bank account the expense is paid.
date string
[yyyy-mm-dd]
Date the expense is created.
amount* double Expense amount.
vat_treatment
(UK Edition only)
string (Optional) VAT treatment for the expense. VAT treatment denotes the location of the vendor, if the vendor resides in UK then the VAT treatment is uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
product_type
(UK Edition only)
string Type of the expense. This denotes whether the expense is to be treated as a goods or service purchase.
Allowed Values: goods and service.
acquisition_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is an EU - goods expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is a non UK - service expense and reverse charge VAT needs to be reported.
tax_id string ID of the tax or tax group applied to the expense.(Not applicable for the US Edition).
is_inclusive_tax boolean To specify if the tax is inclusive of the expense amount.
is_billable boolean To specify if the expense is billable.
customer_id string ID of the customer, if the expense is billable.
currency_id string ID of the currency in which expense amount is specified.
exchange_rate double Exchange rate of the currency specified.
project_id string ID of the project associated with the customer.

Sample Request

{
  "account_id": "982000000561057",
  "date": "2013-11-18",
  "amount": 112.50,
  "tax_id": "982000000566007",
  "is_inclusive_tax": false,
  "is_billable": true,
  "reference_number": "#562SD23R4",
  "description": "",
  "customer_id": "982000000567001",
  "currency_id": "982000000000190",
  "exchange_rate": 1.00,
  "project_id": ""
}

Sample Response

Status: 201 Created
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The expense has been recorded.",
  "expense": {
    "expense_id": "982000000567216",
    "expense_item_id": "982000000567220",
    "account_id": "982000000561057",
    "account_name": "Marketing",
    "date": "2013-11-18",
    "tax_id": "982000000566007",
    "tax_name": "Sales Tax",
    "tax_percentage": 10.5,
    "currency_id": "982000000000190",
    "currency_code": "USD",
    "exchange_rate": 1.00,
    "tax_amount": 11.81,
    "sub_total": 112.50,
    "total": 124.31,
    "bcy_total": 124.31,
    "amount": 112.50,
    "is_inclusive_tax": false,
    "reference_number": "#562SD23R4",
    "description": "",
    "is_billable": true,
    "customer_id": "982000000567001",
    "customer_name": "Bowman & Co",
    "expense_receipt_name": "",
    "expense_receipt_type": "",
    "created_time": "2013-11-18T02:39:14-0800",
    "last_modified_time": "2013-11-18T04:22:52-0800",
    "status": "unbilled",
    "invoice_id": "",
    "invoice_number": "",
    "project_id": "",
    "project_name": ""
  }
}

Update an expense

PUT  /expenses/:expense_id

Update an existing expense.

Parameters

receipt file Expense receipt file to replace existing receipt.
Allowed Extensions: gif, png, jpeg, jpg, bmp and pdf
delete_receipt boolean Param Description.

Request attributes

account_id string ID of the expense account.
paid_through_account_id string ID of the cash/ bank account the expense is paid.
date string
[yyyy-mm-dd]
Date the expense is created.
amount* double Expense amount.
vat_treatment
(UK Edition only)
string (Optional) VAT treatment for the expense. VAT treatment denotes the location of the vendor, if the vendor resides in UK then the VAT treatment is uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
product_type
(UK Edition only)
string Type of the expense. This denotes whether the expense is to be treated as a goods or service purchase.
Allowed Values: goods and service.
acquisition_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is an EU - goods expense and acquisition VAT needs to be reported.
reverse_charge_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is a non UK - service expense and reverse charge VAT needs to be reported.
tax_id string ID of the tax or tax group applied to the expense.(Not applicable for the US Edition).
is_inclusive_tax boolean To specify if the tax is inclusive of the expense amount.
is_billable boolean To specify if the expense is billable.
customer_id string ID of the customer, if the expense is billable.
currency_id string ID of the currency in which expense amount is specified.
exchange_rate double Exchange rate of the currency specified.
project_id string ID of the project associated with the customer.

Sample Request

{
  "account_id": "982000000561057",
  "date": "2013-11-18",
  "amount": 112.50,
  "tax_id": "982000000566007",
  "is_inclusive_tax": false,
  "is_billable": true,
  "reference_number": "#562SD23R4",
  "description": "",
  "customer_id": "982000000567001",
  "currency_id": "982000000000190",
  "exchange_rate": 1.00,
  "project_id": ""
}

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "Expense information has been updated.",
  "expense": {
    "expense_id": "982000000567216",
    "expense_item_id": "982000000567220",
    "account_id": "982000000561057",
    "account_name": "Marketing",
    "date": "2013-11-18",
    "tax_id": "982000000566007",
    "tax_name": "Sales Tax",
    "tax_percentage": 10.5,
    "currency_id": "982000000000190",
    "currency_code": "USD",
    "exchange_rate": 1.00,
    "tax_amount": 11.81,
    "sub_total": 112.50,
    "total": 124.31,
    "bcy_total": 124.31,
    "amount": 112.50,
    "is_inclusive_tax": false,
    "reference_number": "#562SD23R4",
    "description": "",
    "is_billable": true,
    "customer_id": "982000000567001",
    "customer_name": "Bowman & Co",
    "expense_receipt_name": "",
    "expense_receipt_type": "",
    "created_time": "2013-11-18T02:39:14-0800",
    "last_modified_time": "2013-11-18T04:22:52-0800",
    "status": "unbilled",
    "invoice_id": "",
    "invoice_number": "",
    "project_id": "",
    "project_name": ""
  }
}

Delete an expense

DELETE  /expenses/:expense_id

Delete an existing expense.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The expense has been deleted."
}

List expense history

GET  /expenses/:expense_id/comments

Get history and comments of an expense.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "comments": [
    {
      "comment_id": "982000000567272",
      "expense_id": "982000000567216",
      "description": "Expense Updated",
      "commented_by_id": "982000000554041",
      "commented_by": "John David",
      "date": "2013-11-18",
      "date_description": "16 hours ago",
      "time": "4:22 AM",
      "operation_type": "Updated",
      "transaction_id": "",
      "transaction_type": "expense"
    },
    {
      "comment_id": "982000000567224",
      "expense_id": "982000000567216",
      "description": "Expense Created",
      "commented_by_id": "982000000554041",
      "commented_by": "John David",
      "date": "2013-11-18",
      "date_description": "18 hours ago",
      "time": "2:39 AM",
      "operation_type": "Added",
      "transaction_id": "",
      "transaction_type": "expense"
    }
  ]
}