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
vendor_name string
[100]
Search expenses by vendor name.
Variants: vendor_name_startswith and vendor_name_contains
customer_id string Search expenses by customer id.
vendor_id string Search expenses by vendor 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 category name or description or customer name or vendor name.
sort_column string Sort expenses.
Allowed Values: date, account_name, paid_through_account_name, total, bcy_total, reference_number, customer_name, vendor_name and created_time

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "expenses": [
    {
      "expense_id": "460000000049023",
      "date": "2012-01-14",
      "account_name": "Advertising And Marketing",
      "paid_through_account_name": "Corp Card Account",
      "description": "Electronics purchase",
      "currency_id": "460000000000097",
      "currency_code": "USD",
      "bcy_total": 7500.00,
      "total": 7500.00,
      "is_billable": false,
      "reference_number": "Ref-2134",
      "customer_id": "",
      "customer_name": "",
      "vendor_id": "",
      "vendor_name": "",
      "status": "nonbillable",
      "created_time": "2013-10-01T13:33:06+0530",
      "expense_receipt_name": ""
    },
    {
      "expense_id": "460000000043017",
      "date": "2013-09-17",
      "account_name": "Rent Expense",
      "paid_through_account_name": "Undeposited Funds",
      "description": "Monthly rental for Will Cooper.",
      "currency_id": "460000000000097",
      "currency_code": "USD",
      "bcy_total": 250.00,
      "total": 250.00,
      "is_billable": true,
      "reference_number": "",
      "customer_id": "460000000038029",
      "customer_name": "Will Cooper",
      "vendor_id": "",
      "vendor_name": "",
      "status": "unbilled",
      "created_time": "2013-09-17T22:10:26+0530",
      "expense_receipt_name": ""
    },
    {
      "expense_id": "460000000042015",
      "date": "2013-09-11",
      "account_name": "Travel Expense",
      "paid_through_account_name": "Petty Cash",
      "description": "Total travel expenses.",
      "currency_id": "460000000000097",
      "currency_code": "USD",
      "bcy_total": 112.50,
      "total": 112.50,
      "is_billable": true,
      "reference_number": "#562SD23R4",
      "customer_id": "460000000026049",
      "customer_name": "Bowman and Co",
      "vendor_id": "460000000044001",
      "vendor_name": "Richards Electric Company",
      "status": "unbilled",
      "created_time": "2013-09-11T16:45:39+0530",
      "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": "460000000042015",
    "expense_item_id": "460000000042025",
    "account_id": "460000000000418",
    "account_name": "Travel Expense",
    "paid_through_account_id": "460000000000361",
    "paid_through_account_name": "Petty Cash",
    "vendor_id": "460000000044001",
    "vendor_name": "Richards Electric Company",
    "date": "2013-09-11",
    "tax_id": "460000000027005",
    "tax_name": "VAT",
    "tax_percentage": 12.5,
    "currency_id": "460000000000097",
    "currency_code": "USD",
    "exchange_rate": 1.00,
    "tax_amount": 12.50,
    "sub_total": 100.00,
    "total": 112.50,
    "bcy_total": 112.50,
    "amount": 100.00,
    "is_inclusive_tax": false,
    "reference_number": "#562SD23R4",
    "description": "Total travel expenses.",
    "is_billable": true,
    "customer_id": "460000000026049",
    "customer_name": "Bowman and Co",
    "expense_receipt_name": "",
    "created_time": "2013-09-11T16:45:39+0530",
    "last_modified_time": "2013-10-07T13:55:23+0530",
    "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.
tax_id
(Not applicable for the US Edition)
string ID of the tax or tax group applied to the expense.
is_inclusive_tax
(Not applicable for the US Edition)
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.
vendor_id string ID of the vendor the expense is made.
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": "460000000000418",
  "paid_through_account_id": "460000000000361",
  "date": "2013-09-11",
  "amount": 100.00,
  "tax_id": "460000000027005",
  "is_inclusive_tax": false,
  "is_billable": true,
  "reference_number": "#562SD23R4",
  "description": "Total travel expenses.",
  "customer_id": "460000000026049",
  "vendor_id": "460000000044001",
  "currency_id": "460000000000097",
  "exchange_rate": 1.00,
  "recurring_expense_id": "",
  "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": "460000000042015",
    "expense_item_id": "460000000042025",
    "account_id": "460000000000418",
    "account_name": "Travel Expense",
    "paid_through_account_id": "460000000000361",
    "paid_through_account_name": "Petty Cash",
    "vendor_id": "460000000044001",
    "vendor_name": "Richards Electric Company",
    "date": "2013-09-11",
    "tax_id": "460000000027005",
    "tax_name": "VAT",
    "tax_percentage": 12.5,
    "currency_id": "460000000000097",
    "currency_code": "USD",
    "exchange_rate": 1.00,
    "tax_amount": 12.50,
    "sub_total": 100.00,
    "total": 112.50,
    "bcy_total": 112.50,
    "amount": 100.00,
    "is_inclusive_tax": false,
    "reference_number": "#562SD23R4",
    "description": "Total travel expenses.",
    "is_billable": true,
    "customer_id": "460000000026049",
    "customer_name": "Bowman and Co",
    "expense_receipt_name": "",
    "created_time": "2013-09-11T16:45:39+0530",
    "last_modified_time": "2013-10-07T13:55:23+0530",
    "status": "unbilled",
    "invoice_id": "",
    "invoice_number": "",
    "project_id": "",
    "project_name": ""
  }
}

Update an expense

PUT  /expenses/:expense_id

Update an existing expense.

multipart/form-data

receipt file Expense receipt file to replace existing receipt.
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.
tax_id
(Not applicable for the US Edition)
string ID of the tax or tax group applied to the expense.
is_inclusive_tax_id
(Not applicable for the US Edition)
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.
vendor_id string ID of the vendor the expense is made.
currency_id string ID of the currency in which expense amount is specified.
exchange_rate double Exchange rate of the currency specified.

Sample Request

{
      "account_id": "460000000000418",
      "paid_through_account_id": "460000000000361",
      "date": "2013-09-12",
      "amount": 100.0,
      "tax_id": "460000000027005",
      "is_inclusive_tax": false,
      "is_billable": true,
      "reference_number": "#562SD23R40",
      "description": "Total travel expenses.",
      "customer_id": "460000000026049",
      "vendor_id": "460000000044001",
      "currency_id": "460000000000097",
      "exchange_rate": 1.0
    }

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "Expense information has been updated.",
      "expense": {
        "expense_id": "460000000042015",
        "expense_item_id": "460000000042025",
        "account_id": "460000000000418",
        "account_name": "Travel Expense",
        "paid_through_account_id": "460000000000361",
        "paid_through_account_name": "Petty Cash",
        "vendor_id": "460000000044001",
        "vendor_name": "Richards Electric Company",
        "date": "2013-09-12",
        "tax_id": "460000000027005",
        "tax_name": "VAT",
        "tax_percentage": 12.5,
        "currency_id": "460000000000097",
        "currency_code": "USD",
        "exchange_rate": 1.0,
        "tax_amount": 12.5,
        "sub_total": 100.0,
        "total": 112.5,
        "bcy_total": 112.5,
        "amount": 100.0,
        "is_inclusive_tax": false,
        "reference_number": "#562SD23R40",
        "description": "Total travel expenses.",
        "is_billable": true,
        "customer_id": "460000000026049",
        "customer_name": "Bowman and Co",
        "expense_receipt_name": "",
        "created_time": "2013-09-11T16:45:39+0530",
        "last_modified_time": "2013-10-07T13:55:23+0530",
        "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 comments & 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": "460000000053037",
      "expense_id": "460000000042015",
      "description": "Expense Updated",
      "commented_by_id": "460000000024003",
      "commented_by": "John David",
      "date": "2013-10-07",
      "date_description": "9 days ago",
      "time": "1:55 PM",
      "operation_type": "Updated",
      "transaction_id": "",
      "transaction_type": "expense"
    },
    {
      "comment_id": "460000000053015",
      "expense_id": "460000000042015",
      "description": "Expense Updated",
      "commented_by_id": "460000000024003",
      "commented_by": "John David",
      "date": "2013-10-07",
      "date_description": "9 days ago",
      "time": "1:54 PM",
      "operation_type": "Updated",
      "transaction_id": "",
      "transaction_type": "expense"
    },
    {
      "comment_id": "460000000042033",
      "expense_id": "460000000042015",
      "description": "Added by John David.",
      "commented_by_id": "460000000024003",
      "commented_by": "John David",
      "date": "2013-09-11",
      "date_description": "35 days ago",
      "time": "4:45 PM",
      "operation_type": "Added",
      "transaction_id": "",
      "transaction_type": ""
    }
  ]
}