REST API for Expenses

Base URL for all REST calls for searching is /intranet/rest/expenses/

Get list of expense sheets

GET /intranet/rest/expenses/sheet

Include one of the required CGI-style parameters:

user=:user_id - Filter/search sheets by user
supervisor=:supervisor_id - Filter/search sheets by supervisor

Optional CGI-style parameters:

date_from=:from_date - Filter/search sheets by modification date
date_to=:to_date - Filter/search sheets by modification date
dept=:dept_id - Filter/search sheets by department
location=:location_id - Filter/search sheets by location
status=:status - Filter/search sheets by status
name=:name - Filter/search sheets by the sheet name

Date/time types must use the metadata date/time format

:status can have one of these values:

draft
rejected
submitted
approved
processed

Returns JSON-formatted array of expenses sheets. Each sheet has the following format:

{
    "id": 3344,
    "name":"Oct 2013 Claims",
    "receipts_quantity": 5,
    "dept": {
        "id" : 6,
        "name" : "AFM"
    },
    "status": "submitted",
    "total_amout": 434.34,
    "last_modified": {
        "date_str" : "13-05-2011 18:13 ICT",
        "timezone" : "Asia/Novosibirsk",
        "date" : "20110513111311"
    },
    "last_modified_by": {
        "id": 1234,
        "name": "Michael Christian"
    },
    "user": {
        "id" : 5678,
        "name" : "John Smith"
    }
}

entry	type	description
id	number	The unique sheet id
name	string	The name of the sheet
receipts_quantity	number	Total receipts attached to the expenses sheet
dept	mixed array	ID and name of the department the sheet belongs to
status	string	Status of the sheet. See status values above
total_amount	number	The total expense amount on the sheet
last_modified	mixed array	Date the sheet was last modified
last_modified_by	mixed array	ID and full name of user who last modified the sheet
user	mixed_array	ID and full name of the user the expense sheet belongs to

Expense sheet

Create expense sheet

POST /intranet/rest/expenses/sheet

Create new expense sheet.

The request body should contain JSON-formatted data with information about new sheet:

{
    "name": "Oct 2013 Claims",
    "location_id": 5,
    "dept_id":3,
    "status": "submitted",
    "total_amout": 434.34,
    "items": [{
        "type" : "operational",
        "receipt_date" : {
            "date_str" : "13-05-2011 18:13 ICT",
            "timezone" : "Asia/Novosibirsk",
            "date" : "20110513111311"
        },
        "vendor" : "AT&T",
        "dept_id": 4,
        "expense_type_id": 5,
        "description": "International Call",
        "amount": 200.00
    },{
        "type":"project",
        "receipt_date" : {
            "date_str" : "13-05-2011 18:13 ICT",
            "timezone" : "Asia/Novosibirsk",
            "date" : "20110513111311"
        },
        "vendor" : "City Cab",
        "client" : "Bill & Melinda Gates Found.",
        "project_id" : 7,
        "billable" : true,
        "expense_type_id" : 3,
        "description" : "Travel to client",
        "amount" : 40.00
    }]
}

entry	type	description
name	string	Name of the expenses sheet
location_id	number	Unique ID of the expense sheet location
dept_id	number	Unique ID of the expense sheet department
status	string	The status of the expense sheet. See status values for valid entries
total_amount	number	The total expense amount of the sheet
items	array	List of expense items. See below for format

The format for expense items is as follows:

entry	type	description
type	string	The item type - 'operational' or 'project'
receipt_date	mixed array	Date on the item's receipt
vendor	string	Name of the vendor
dept_id	number	Unique ID of the department the expense belongs to
expense_type_id	number	The ID of the expense type as defined in the expenses admin area
description	string	A description of the expense
amount	number	The expense cost

Get expense sheet info

GET /intranet/rest/expenses/sheet/:id

Returns a JSON-formatted array of sheet's details with following format:

{
    "id": 3344,
    "name": "Oct 2013 Claims",
    "receipts_quantity": 5,
    "dept": {
        "id" : 3,
        "name" : "AFM"
    },
    "status": "submitted",
    "total_amout": 434.34,
    "last_modified": {
        "date_str" : "13-05-2011 18:13 ICT",
        "timezone" : "Asia/Novosibirsk",
        "date" : "20110513111311"
    },
    "last_modified_by": {
        "id": 1234,
        "name": "Michael Christian"
    },
    "user": {
        "id":5678,
        "name": "John Smith"
    },
    "supervisor": {
        "id": 1234,
        "name": "Michael Christian"
    },
    "approved_by": {
        "id": 1234,
        "name": "Michael Christian"
    },
    "processed_by": {
        "id": 1234,
        "name": "Michael Christian"
    },
    "notes": "Sorry I forgot, thanks (JC)",
    "items": [{
        "id":145,
        "type":"operational",
        "receipt_date":{
            "date_str" : "13-05-2011 18:13 ICT",
            "timezone" : "Asia/Novosibirsk",
            "date" : "20110513111311"
        },
        "vendor": "AT&T",
        "dept": {
            "id" : 3,
            "name" : "AFM"
        },
        "expense_type": {
            "id" : 3,
            "name": "Cell Phone",
        },
        "description": "International Call",
        "amount": 40.00
    },{
        "id": 154,
        "type":"project",
        "receipt_date":{
            "date_str" : "13-05-2011 18:13 ICT",
            "timezone" : "Asia/Novosibirsk",
            "date" : "20110513111311"
        },
        "vendor": "City Cab",
        "client": "Bill & Melinda Gates Found.",
        "project": {
            "id" : 7,
            "name" : "Project A"
        },
        "billable": true,
        "expense_type": {
            "id" : 5,
            "name" : "Travel and Entertainment"
        },
        "description": "Travel to client",
        "amount": 40.00
    }],
    "receipts":[]
}

The format of the returned JSON is the same as when creating a new expense sheet above but with the addition of a numeric id.

Update expense sheet

PUT /intranet/rest/expenses/sheet/:id

Update an expense sheet. :id in the request URI is the unique id of the sheet to be updated.

Request body should contain JSON-formatted data with information about changed data in the sheet and any attached expense items:

{
    "name": "Oct 2013 Claims",
    "location_id": 5,
    "dept_id": 3,
    "status": "submitted",
    "total_amout": 434.34,
    "items": [{
        "id" : 145,
        "type" : "operational",
        "receipt_date" : {
            "date_str" : "13-05-2011 18:13 ICT",
            "timezone" : "Asia/Novosibirsk",
            "date" : "20110513111311"
        },
        "vendor" : "AT&T",
        "dept_id": 4
        "expense_type_id": 8,
        "description": "International Call",
        "amount": 200.00
    },{
        "type":"project",
        "receipt_date" : {
            "date_str" : "13-05-2011 18:13 ICT",
            "timezone" : "Asia/Novosibirsk",
            "date" : "20110513111311"
        },
        "vendor" : "City Cab",
        "client" : "Bill & Melinda Gates Found.",
        "project_id" : 7,
        "billable" : true,
        "expense_type_id" : 4,
        "description" : "Travel to client",
        "amount" : 40.00
    }]
}

The format of the request body follows that used to create a new sheet. Missing values are assumed to be unchanged.

Delete expense sheet

DELETE /intranet/rest/expenses/sheet/:id

On successful deletion, request returns http code 204 without any data in body. If the sheet dosen't exist status code 404 is returned.

Get list of items

GET /intranet/rest/expenses/items

Has optional CGI-style parameters:

user=:user_id - Filter/search items by user
dept=:dept_id - Filter/search items by dept
location=:location_id - Filter/search items by location
date_from=:date/time - Filter/search items by modification date
date_to=:date/time - Filter/search items by modification date
vendor=:vendor - Filter/search items by vendor name
project=:project - Filter/search items by project name
client=:client - Filter/search items by client name
expense_type=:expense_type - Filter/search items by expense type
status=:status - Filter/search items by status
is_billable=:boolean - Filter/search billable items
is_non_billable=:boolean - Filter/search non billable items
operational_cost=:boolean - Filter/search operational cost items
project_cost=:boolean - Filter/search project cost items

The date/time parameters in the URL must use the metadata data/time format.

status can have one of these values:

draft
rejected
submitted
approved
processed

Returns a JSON-formatted list of items with following format:

For operational items:

{
    "id" : 145,
    "type" : "operational",
    "receipt_date" : {
            "date_str" : "13-05-2011 18:13 ICT",
            "timezone" : "Asia/Novosibirsk",
            "date" : "20110513111311"
        },
    "vendor" : "AT&T",
    "dept": {
        "id" : 4,
        "name" : "AFM"
    },
    "expense_type": {
        "id" : 3,
        "name" : "Cell Phone"
    },
    "description": "International Call",
    "amount": 200.00
}

For project items:

{
    "id" : 9,
    "type":"project",
    "receipt_date" : {
        "date_str" : "13-05-2011 18:13 ICT",
        "timezone" : "Asia/Novosibirsk",
        "date" : "20110513111311"
    },
    "vendor" : "City Cab",
    "client" : "Bill & Melinda Gates Found.",
    "project" : {
        "id" : 7,
        "name" : "Project A"
    },
    "billable" : true,
    "expense_type" : {
        "id" : 5,
        "name" : "Travel and Entertainment"
    },
    "description" : "Travel to client",
    "amount" : 40.00
}

These have the same format as the expense item format defined above.

Get list of clients

GET /intranet/rest/expenses/client

Returns a JSON-formatted array of clients with following format:

[{
    "id": 43,
    "name": "Client A"
},{
   "id": 45,
   "name": "Client B"
}]

entry	type	description
id	number	Unique id of the client
name	string	The name of the client

Get list of departments

GET /intranet/rest/expenses/dept

Returns a JSON-formatted array of departments with following format:

[{
    "id": 97,
    "name": "AFM"
},{
   "id": 103,
   "name": "BD"
}]

entry	type	description
id	number	Unique id of the department
name	string	Name of the department

Get list of locations

GET /intranet/rest/expenses/location

Returns a JSON-formatted array of locations with following format:

[{
    "id": 3,
    "name": "DC"
},{
   "id": 9,
   "name": "CH"
}]

entry	type	description
id	number	Unique id of the location
name	string	Name of the location

Get list of projects

GET /intranet/rest/expenses/project

Returns a JSON-formatted array of projects with following format:

[{
    "id": 78,
    "name": "Project A"
},{
   "id": 79,
   "name": "Project B"
}]

entry	type	description
id	number	Unique id of the project
name	string	Name of the project