API Reference - Expense Entries

Expenses, entered in the form of expense entries, capture time and reimbursable charges for employees.  Expenses can also be connected to invoices for quick and convenient billing.

Listing Expense Entries

Returns a collection of expense entry records, optionally filtered by the available request parameters.

GET /api/v1/expense/entries

 

Available Request Parameters:

Name	Type	Required	Description
id	integer	no	ID of the expense entry.
expense_slip	integer	no	ID of the connected expense payment slip (if available).
user	integer	no	ID of the user who the entry is for.
status	string	no	Choices: "pending", "approved", "declined", "committed", "voided" (see explanation of statuses below)
case	integer	no	ID of the case connected to this expense entry.
tracking_category	integer	no	ID of the tracking category associated with this expense entry (if available).
entry_number	integer	no	The unique numerical number associated with this expense entry.
date_from	date	no	Entry date on or after the date (Alias: From).
date_to	date	no	Entry date on or before the date (Alias: To).
created_from	timestamp	no	Created on or after the date, as determined by the system.
created_to	timestamp	no	Created on or before the date, as determined by the system.
updated_from	timestamp	no	Updated on or after the date, as determined by the system.
updated_to	timestamp	no	Updated on or before the date, as determined by the system.

Note: All timestamp parameters are queried and returned in UTC.

Explanation of Statuses

• pending - The entry has been submitted, but has not yet been approved.
• approved - The entry has been approved and is ready for invoicing and/or payment slips.
• declined - The entry has been declined, and the user must make adjustments to it.
• committed - The entry has been pushed to a payment slip, and is awaiting payment.
• voided - The entry was previously approved, but was subsequently voided, and is no longer valid.

Getting an Expense Entry

Returns a single expense entry record, based on the numeric ID.

GET /api/v1/expense/entries/{entry_id}

Creating an Expense Entry

Creates a new expense entry. Upon success, returns an expense entry object. See the example request at the bottom of this section for a better idea of how a fully formed request should look.

POST /api/v1/expense/entries

Available Parameters

Name	Type	Required	Description
user_id	integer	yes	ID of the staff member submitting the expense. API Reference - Staff
entry_date	date	yes	The entry date in ISO format (YYYY-MM-DD).
casefile_id	integer	yes	ID of the associated case. API Reference - Cases
tracking_category_id	integer	no	ID of the tracking category to associate with the expense entry (optional).
event_id	integer	no	ID of the associated task or event (optional). API Reference - Events
expense_details	collection	yes	Expense detail objects to create along with this entry (see below).

 

Adding Expense Details to the Expense Entry

Expense details are the actual line items that are added to each entry. You can add as many expense details as you want to into the expense_details array (see example below). An expense entry must include at least one expense detail. Here are the available fields when creating an expense detail object:

Name	Type	Required	Description
finance_item_id	integer	yes	ID of the expense item.
item_code_id	integer	no	ID of the connected item code (optional).
rate	decimal	yes	The rate of the service (e.g. 30.00, 0.55, etc...)
quantity	decimal	yes	The quantity of the service (e.g. 1.0, 0.5, etc...)
notes	text	no	Supporting text for this service.

See the example below for an idea of how this looks when attached to an expense entry request.

 

Example New Expense Entry Request 

A new expense entry is created by POSTing a JSON object to the specified end point using the above criteria.  The JSON object must contain the required fields (as shown above) and must be nested under an expense_entry object.  See the following example request:

{
  "expense_entry": {
    "user_id": 1,
    "tracking_category_id": 1, // optional
    "entry_date": "2022-11-01",
    "casefile_id": 123,
    "event_id": 456, // optional
    "notes": "This entry was submitted by the API.",
    "expense_details": [
        {
            "finance_item_id": 1,
            "item_code_id": 5, // optional
            "rate": 0.55,
            "quantity": 75,
            "notes": "Mileage - From the API"
        },    
        {
            "finance_item_id": 2,
            "item_code_id": 6, // optional
            "rate": 20,
            "quantity": 5,
            "notes": "Surveillance Hours - From the API"
        }        
    ]
  }
}

Note: The above request is for demonstration purposes only, your implementation will require unique data provided by your account.

Updating an Expense Entry

Updates an existing expense entry. Upon success, returns an expense entry object. 

PUT /api/v1/expense/entries/:id

Updating an expense entry requires a fully formed json object, as shown in the example under Creating an Expense Entry above.  Partial updates are not supported.

Note: Expense entries can only be updated if they are in the Pending or Declined state.  Entries that have already been approved cannot be updated.