;
api login

BigTime's expense entry api provides access to user's expense report data -- allowing you to create programs and web services that query, create or edit a user's data without relying on the BigTime web pages. Note that vendor expenses can be viewed from this api, but they cannot be created here (vendor expenses are created exclusively in your accounting package).

Just like timesheets: "Submitted" Entries can no longer be edited/deleted.

As long as entries have not yet been submitted by the user, they can be deleted or adjusted. Once an entry has been submitted, however, it can no longer be edited by a non-admin user. While you can "view" those entries, they are locked by the system (unless the logged in user has special administrative rights). So, as you are reviewing a user's information, it's important to remember that only unsubmitted entries can be edited.

Retrieving Entries by Expense Report.
try it

All of a user's expense entries are organized by expense report. Any "unsubmitted" expenses have a report id of "0." When a user submits their expenses, unsubmitted items are packaged up and attached to the report. So, you can pull all unsubmitted expense entries using this url. Just specify a rptSid of "0."

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /expense/report/{rptSid}?staffsid={staffsid}&{view}=Basic
HTTP RESPONSE:  (array of ExpenseEntry objects -- see below for details)
ParameterTypeDescription
RptSid Numeric Specifies the expense report for which you would like to return details. Note that you can get a list of all UNSUBMITTED expenses by passing a reportsid of "0."
StaffSid Numeric Specifies an alternate staffsid for whom you would like to pull expense details. Note that the logged in user will need to have admin rights in order to pull data for another user (if they don't -- then the url will return their own personal data and disregard this parameter).
View Basic; Detailed Take a look at the time entry object details below. For each field, the "views" within which that field appears are flagged. The Detailed view requires more server resources and, as a result, will return more slowly.

Retrieving Entries by filter.
try it
  • Post

You can use a POST request to pull expense entries filtered by criteria. Note that the BASIC view fields will be returned by default.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post:  /expense/reportbyfilter
POST CONTENT:  {mindate: "1/1/2019",
		maxdate: "1/1/2020",
		staffsids: [101, 102],
		projectsids: [202, 203],
		view: "basic",
		showapproval: false}
		
HTTP RESPONSE:  (array of ExpenseEntry objects sorted by Dt descending -- see below for details)

All of the fields below are optional. Filter criteria are "ANDed" together (ie - more criteria produces a smaller set of result). Results are capped at a maximum of 1,000 items.

ParameterTypeDescription
MinDate DateTime Specifies the minimum Expense entry INPUT date (eg - the date against which the entry is logged, not the date the user physically entered it).
MaxDate DateTime Specifies the maximum Expense entry INPUT date (eg - the date against which the entry is logged, not the date the user physically entered it).
StaffSids List of Numeric Specifies the SID of the staff member who entered the expense (limited to 1,000 SIDs). Note that the logged in user will need to have admin rights in order to pull data for another user (if they don't -- the expense entry will be excluded from the results).
ProjectSids List of Numeric Specifies the SID of the project associated with the expense entry (limited to 1,000 SIDs).
View Basic; Detailed Take a look at the time entry object details below. For each field, the "views" within which that field appears are flagged. The Detailed view requires more server resources and, as a result, will return more slowly.
ShowApproval True/False Include a property on each ExpenseEntry in the results indicating if the logged in user is permitted to approve the expense.

Pulling the detail for a specific expense entry.

You can use a simple GET request to pull the details associated with a single entry. Note that the DETAIL view fields will be returned by default.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /expense/detail/{sid}
HTTP RESPONSE:  (ExpenseEntry object -- see below for details)

Creating a NEW expense entry.
try it
  • Post

Note that only the fields listed in the AddUpdate view (below) should be included in your post to this url. Any other data will be ignored. BigTime doesn't care about the order in which field data is posted, and none of the fields are case sensitive. Note that any validation errors will return a 400 error, and an invalid permission will return a 405 (eg - attempting to log expenses against a project you don't have rights to log expenses against).

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post:  /expense/detail
POST CONTENT:  {staffsid: 123, 
		projectsid: 123, 
		catsid: 123, 
		dt: "2013-01-01", 
		CostIN: 1.25, 
		notes: "These are my expense entry notes..."}
		
You can include ANY of the AddUpdate fields below, 
		but you MUST include the required (*) fields.

HTTP RESPONSE:  (updated ExpenseEntry object -- see below for details)

Updating Existing Expense Entries.

Note that only the fields listed in the AddUpdate and Update views (below) should be included in your post to this url. Any other data will be ignored. Note again, validation errors will return a 400 error, and an invalid permission will return a 405 (eg - attempting to update submitted expenses without that system permission).

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post:  /expense/detail/{sid}
POST CONTENT:  {CostIN: 99.95, 
		notes: "this is an updated note..."}
		
** You can include ANY of the AddUpdate/Update fields below.  
		However - you cannot "zero-out" or remove any of the 
		required (*) fields.

HTTP RESPONSE:  (updated ExpenseEntry object -- see below for details)

Deleting an Expense.

As long as the user hasn't submitted an entry, BigTime will allow you to delete it through the api.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP DELETE:  /expense/detail/{sid}
HTTP RESPONSE:  200 is a successful delete.

Pulling a list of active expense reports.
try it
  • Click the GET button below to view the information returned by this url.

  • Get
get ALL
  • Click the GET button below to view the information returned by this url.

  • Get

Since a user's expense entries are organized by expense report, you may need to pull a list of expense reports for a specific user. By default, the /expense/reports (note the plural) endpoint will pull ONLY reports that are active (eg - reports that may require the users attention). If you would like to pull ALL reports (even expense reports that do not require action), you can use the ShowAll flag. In every case, reports are returned in descending date order.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /expense/reports?{showAll=true}
HTTP RESPONSE:  (array of ExpenseReport objects -- see below for details)

Submitting a user's expenses.

Once a user has completed an expense report and is ready to submit it. You can make a call to the expense/submit endpoint to submit those expenses. Note that the api requires a "name" for an expense report (to create a new one from the user's unsubmitted expenses) and an Id for resubmitting an existing report.

Resubmitting Expenses. If a submitted report requires additional action (eg - a manager has rejected that report and requires additional notes before the report is resubmitted), then you will need to include the report's SID code in order to submit it.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /expense/submit/{id}
HTTP RESPONSE:  The updated/newly created expense report object (see below for details)

Expense Entry Object: Field Details

For each of the operations listed above, you will post or "get" one or more expense entry objects. The field list below is a complete list of fields available through the api (including the views within which those fields are found). Take special note of the AddUpdate and Update views. Required fields are flagged with an "*" character.

FieldTypeDescriptionView(s)
SID Integer Unique SID code for this record. Basic, Detailed, Update*
IsSubmitted True/False If this value is TRUE, the entry we are examining has been submitted by the user. Basic, Detailed
RptSID Integer Unique SID code for the expense report to which this specific expense item is linked. Basic, Detailed
StaffSID Integer Unique SystemId for the staffer who submitted the expense. Basic, Detailed, AddUpdate*
Dt Date Expense entry INPUT date (eg - the date against which the entry is logged, not the date the user physically entered it). Basic, Detailed, AddUpdate*
ProjectSID Integer The unique "system id" for the project against which this entry is logged. Note that this value is required. Basic, Detailed, AddUpdate*
ProjectNm String The "display" name for the project against which the entry is logged. Detailed
ClientID Integer Each project in the system can be attached to a client record, and this convenience property displays the clientID for the project to which an entry is attached. Basic, Detailed
ClientNm String Name of the client to which the entry is attached. Detailed
CatSID Integer ExpenseCode value for this entry (note that the description of this field is governed by a firm's vocabulary). Basic, Detailed, AddUpdate*
CatNm String Name of the expense category to which this expense is linked. Basic, Detailed
TaskSID Integer The SystemId for the Task to which the entry is attached (note that the description of this field is governed by a firm's vocabulary. May also be called an engagement or a phase). Basic, Detailed, AddUpdate
TaskNm String The name of the Task to which the entry is attached (note that the description of this field is governed by a firm's vocabulary. May also be called an engagement or a phase).

Specifying Task Name for Add/Update Requests
If you know the NAME of the task you would like to link an entry to, but not the BigTime TaskSID code, then you can specify a TaskNm value in your addUpdate request and BigTime will attempt to match your task to the string value you specify. Note that task names should, in that case, be unique (the system will not do a partial/wildcard match). If Both TaskSid and TaskNm are specified, then the system will use the TaskSid value.
Detailed, Addupdate,Timer
VendorSID Integer The SystemId for the vendor to which the entry is attached. Basic, Detailed, AddUpdate
VendorNm String The name for the vendor to which the entry is attached. Basic, Detailed
CCardSID Integer If this expense is a credit card expense, then BigTime will have attached a card id to it. That value is shown in this field. Basic, Detailed
BillSID Integer If this is a vendor expense, this is SystemId of the bill to which this expense is attached. Basic, Detailed, AddUpdate
NoCharge True/False TRUE if this entry should be considered NoCharge for billing purposes. Basic, Detailed, AddUpdate
PaidByCo True/False TRUE if this entry is not a reimbursable expense (eg - a credit card charge or another company-paid expense that the user is simply logging). Basic, Detailed, AddUpdate
Nt String User entered notes for the entry (up to 1000 characters). Basic, Detailed, AddUpdate
CostIN Numeric Every expense entry must have a value for either the COST or the PRICE (eg - CostIN or CostBill). These numbers are currency values, and will be rounded to the nearest penny. Note that you should only specify ONE of the following fields when creating/modifying an expense: CostIN, CostBill or Units. Basic, Detailed, AddUpdate**
CostPayable Numeric If your users track pre-paid expenses (eg - corporate vehicle mileage or corporate credit card charges) that are not-reimbursale, then the this field will be zero for those non-reimbursable expenses. If PaidByCo=true, then CostPayable=0. Otherwise, CostPayable=CostIN. Basic, Detailed, AddUpdate**
CostBill Numeric Every expense entry must have a value for either the COST or the PRICE (eg - CostIN or CostBill). These numbers are currency values, and will be rounded to the nearest penny. Note that you should only specify ONE of the following fields when creating/modifying an expense: CostIN, CostBill or Units. Basic, Detailed, AddUpdate**
IsUnit True/False If the expense category against which an expense is being logged is a PER UNIT category (eg - mileage), then this value will return TRUE. Basic, Detailed
UnitPrice Numeric If the expense category against which an expense is being logged is a PER UNIT category (eg - mileage), then this value returns the PER UNIT sale price for that item (eg - mileage is billed to a customer at .555/mile). Basic, Detailed
UnitRate Numeric If the expense category against which an expense is being logged is a PER UNIT category (eg - mileage), then this value returns the PER UNIT reimbursable rate for that item (eg - mileage is reimbursed to an employee at .495/mile). Basic, Detailed
Units Numeric If the expense category against which an expense is being logged is a PER UNIT category (eg - mileage), then this value is used to indicate the NUMBER of units this expense represents (eg - for a mileage expense, this number represents the number of miles being logged). We use this value to compute the CostIN and CostBill values. Note that you should only specify ONE of the following fields when creating/modifying an expense: CostIN, CostBill or Units. You cannot enter Units against an expense category which has not been setup as a "per unit" category. Basic, Detailed, AddUpdate**
UOM String If the expense category against which an expense is being logged is a PER UNIT category (eg - mileage), then this value is the "unit" of measure (eg - "miles" for a mileage expense). This value will be empty if a category is not setup as a "per-unit" category. Basic, Detailed
DueDate Date If this is a vendor expense, this is the due date for the bill. Basic, Detailed, AddUpdate
RefNbr String If this is a vendor expense, this is the reference number for the bill. Basic, Detailed, AddUpdate
HasReceipt True/False If the expense has a receipt attached, then this item returns TRUE. Note the URL's (above) used to query/pull receipts attached to expenses. Basic, Detailed
IsApproved True/False TRUE if this entry has been approved by the user's manager(s). Note that many firms don't have a formal review process for expenses -- so this value will always be "false" for those firms. Detailed
ApprovalStatus Number Number indicating the status of the entry (unsubmitted=0, readyToReview=1, approved=2, rejected=4). Detailed
ApprovalStatusNm String If the firm uses a formal manager approval process for expenses, then you can use this field to track the current status of the entry. This is the text version of ApprovalStatus -- so it will display "Unsubmitted", "Under Review", "Approved" or "Rejected". Detailed
InvoiceSID Integer If the firm is using BigTime to invoice, then this field indicates the invoice against which the entry was logged. Detailed
IsInvoiced True/False If the firm is using BigTime to invoice, then this field will be TRUE if the entry has already been invoiced. Detailed
IsVendorExpense True/False TRUE if this is a vendor expense. Basic, Detailed

Expense Report Object: Field Details

if you are pulling an listing of expense report objects, then that list will contain an array of objects with the fields listed below.

FieldTypeDescriptionView(s)
SID Integer Unique SID code for this report. Note that a valid expense report SID is required in order to re-submit a report (see "submitting an expense report" above). Basic,Update*
RptNm String The name of the report in question. Note that a new report submission will require this field in order to be accepted by the system (see "submitting an expense report" above). Basic,Update,Add*
CreatedDt Date The date the report was created (eg - the report's "submission date"). Basic
StatusId Enum if this report requires action, then the action required will be listed in this field. Values include NoAction, Unsubmitted, UpdatesRequestedForApproval, NewExpensesAdded.

Working with Expense Receipts

Every expense item this is uploaded to the system can have a receipt attached to it. When you are working with the api, pulling/posting receipt data is controller through a supplemental set of URL's. We review those url's below.

Pulling the Receipt attached to a specific expense.
Receipt files are stored/encrypted within a document repository on a separate suite of servers in BigTime's domain. In order to access those files, you first need to pull an "access url" from the BigTime server. This will (a) unlock that object so that you can download it and (b) expose a "temporary" access url you can use to access the file. The call shown below can be used to get an access url for the receipt attached to a specific expense entry.
HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /expense/receipt/{sid}
HTTP RESPONSE:  {url: "http://docs.bigtime.net/abc/234689-896fd-890as7d" }

You can use the URL returned from this function to dowload 
	the receipt attached to this expense.

Uploading a New receipt for a specific expense.
try it
  • Choose a file to upload...
  • Upload
When you upload a receipt file, that file replaces any existing receipt attached to the expense you specify. Note that you'll need to make sure that any files you attempt to upload conform to the file type restrictions which govern the BigTime application.
HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST:  /expense/receipt/{sid}
POST CONTENT:  <FileUpload>
HTTP RESPONSE:  {url: "http://docs.bigtime.net/abc/234689-896fd-890as7d" }

You can use the URL returned from this function to dowload 
	the receipt attached to this expense.

Deleting a receipt file.
Finally, it is possible to remove an existing expense receipt file using the DELETE verb on the expense/receipt url.
HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP DELETE:  /expense/receipt/{sid}
HTTP RESPONSE:  {result: true }