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.
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.
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
(Not applicable for the US Edition)
boolean To specify if the tax is inclusive of the 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.
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": ""
    }
  ]
}