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).

Retrieving Entries by Expense Report.

try it

• BasicDetailed
• Submit

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)

Retrieving Entries by filter.

try it

• {mindate: "1/1/2019", maxdate: "1/1/2020", staffsids: [101, 102], projectsids: [202, 203], view: "basic", showapproval: false}
• 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.

Pulling the detail for a specific expense entry.

try it

• Get

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)

Getting custom fields list and values for expense entry. Parameters are the SID from the expense entry (long) and getValues (true/false).

try it

• Get

You can use a simple GET request to pull the custom field details associated with a single expense entry item.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /expense/customFields/{sid}&{getValues}
HTTP RESPONSE:  (A JSON list of all custom fields related to the time entry. Also if a flagged to return values it will return a second list with the value and mapping.)

UDFList

UDFValues

Posting a custom field detail to a specific expense entry.

try it

• POST

You can use a simple POST request to push a custom field detail associated with a single expense entry item. The JSON should contain a JSON array of custom fields you would like to post, this array should have three properties inside of it, EntityID, UDFSid, and StrVal. The EntityID should be the expense id, UDFSid should be the custom fields id you would like to post to, and StrVal should be the string value you would like the custom field to be set to.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST:  /expense/customFieldsPost/{sid}
HTTP RESPONSE:  Results: true if successfully saved.

Creating a NEW expense entry.

try it

• {"staffsid": 0, "projectsid":0, "catsid":0, "dt":"2023-01-01", "costIN": 1.25}
• 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": "2023-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.

try it

• Submit

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.

try it

• delete

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.

try it

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

• Get

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.

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.

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.

try it

• Get

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

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.

try it

• Delete

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP DELETE:  /expense/receipt/{sid}
HTTP RESPONSE:  {result: true }