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 claimants
GET /claimants
List all claimants. (Note: This API is only available for UK edition organizations.)
Get a claimant
GET /claimants/:claimant_id
Get the details of a claimant. (Note: This API is only available for UK edition organizations.)
Create a claimant
POST /claimants
Create a claimant for an expense. (Note: This API is only available for UK edition organizations.)
Delete a claimant
DELETE /claimants/:claimant_id
Delete a claimant. (Note: This API is only available for UK edition organizations.)

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.
mileage_type string To specify the whether the expense is of mileage type.
Allowed Values: non_mileage, manual and odometer.
start_reading double Start reading of odometer when creating a mileage expense where mileage_type is odometer.
end_reading double End reading of odometer when creating a mileage expense where mileage_type is odometer.
distance double Distance travelled for a particular mileage expense where mileage_type is manual.
mileage_unit string Unit of the distance travelled.
Allowed Values: km and mile
mileage_rate double Mileage rate for a particular mileage expense.
claimant_id
(UK Edition only)
string ID of the claimant who has submitted this mileage expense.
vehicle_type
(UK Edition only)
string Vehicle type for a particular mileage expense.
Allowed Values: car, van, motorcycle and bike
can_reclaim_vat_on_mileage
(UK Edition only)
boolean To specify if tax can be reclaimed for this mileage expense.
fuel_type
(UK Edition only)
string Fuel type for a particular mileage expense.
Allowed Values: petrol, lpg and diesel
engine_capacity_range
(UK Edition only)
string Engine capacity range for a particular mileage expense.
Allowed Values: less_than_1400cc, between_1400cc_and_1600cc, between_1600cc_and_2000cc and more_than_2000cc

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": "",
  "mileage_type":"non_mileage"
}

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": "",
    "mileage_type":"non_mileage"
  }
}

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.
mileage_type string To specify the whether the expense is of mileage type.
Allowed Values: non_mileage, manual and odometer.
start_reading double Start reading of odometer when creating a mileage expense where mileage_type is odometer.
end_reading double End reading of odometer when creating a mileage expense where mileage_type is odometer.
distance double Distance travelled for a particular mileage expense where mileage_type is manual.
mileage_unit string Unit of the distance travelled.
Allowed Values: km and mile
mileage_rate double Mileage rate for a particular mileage expense.
claimant_id
(UK Edition only)
string ID of the claimant who has submitted this mileage expense.
vehicle_type
(UK Edition only)
string Vehicle type for a particular mileage expense.
Allowed Values: car, van, motorcycle and bike
can_reclaim_vat_on_mileage
(UK Edition only)
boolean To specify if tax can be reclaimed for this mileage expense.
fuel_type
(UK Edition only)
string Fuel type for a particular mileage expense.
Allowed Values: petrol, lpg and diesel
engine_capacity_range
(UK Edition only)
string Engine capacity range for a particular mileage expense.
Allowed Values: less_than_1400cc, between_1400cc_and_1600cc, between_1600cc_and_2000cc and more_than_2000cc

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": "",
  "mileage_type":"non_mileage"
}

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": "",
    "mileage_type":"non_mileage"
  }
}

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"
    }
  ]
}

List claimants

GET  /claimants

List claimants with pagination.

Parameters

sort_column string Sort claimants.
Allowed Values: name and email
filter_by string Filter claimants by status.
Allowed Values: Status.All, Status.Active and Status.Deleted

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
    "code": 0,
    "message": "success",
    "claimants": [
      {
        "claimant_id": "982000000554041",
        "name": "John David",
        "email": "johndavid@zilliuminc.com"
      },
      {
        "claimant_id": "982000000014001",
        "name": "John Smith",
        "email": "johnsmith@zilliuminc.com"
      }
    ],
    "page_context": {
      "page": 1,
      "per_page": 200,
      "has_more_page": false,
      "report_name": "Claimants",
      "applied_filter": "Status.All",
      "sort_column": "name",
      "sort_order": "A"
    }
}

Get a claimant

GET  /claimants/:claimant_id

Get the details of a claimant.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
    "code": 0,
    "message": "success",
    "claimant": {
        "claimant_id": "982000000554041",
        "name": "John David",
        "email": "johndavid@zilliuminc.com"
    }
}

Create a claimant

POST  /claimants

Create a claimant for an expense.

Request attributes

name string Name of the claimant.
email string Email address of the claimant.

Sample Request

{
    "name": "John David",
    "email": "johndavid@zilliuminc.com"
}

Sample Response

Status: 201 Created
Content Type: application/json;charset=UTF-8
{
    "code": 0,
    "message": "success",
    "claimant": {
        "claimant_id": "982000000554041",
        "name": "John David",
        "email": "johndavid@zilliuminc.com"
    }
}

Delete a claimant

DELETE  /claimants/:claimant_id

Delete an existing claimant.

Sample Response

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