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).
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.
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)
Parameter | Type | Description |
---|---|---|
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. |
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.
Parameter | Type | Description |
---|---|---|
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. |
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)
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.)
Field | Type | Description |
---|---|---|
EntityType | Integer | The entity type enum, should be 4 for time |
EntityType_Nm | String | Label for entity type, this should say time. |
UDFSid | Integer | The unique identifier for a custom field. |
UDFNm | String | The name of the the custom field. |
UDFLabel | String | The label of the custom field visible in the UI. |
UDFLen | Integer | The max length of the user defined field. This defaults as 0 if there is no max length or if max length does not apply. |
UDFDefault | String | The default value of the user defined field. |
UDFLookup | String | A string of values that represent the picklist for the UDF. Each value is seperated by a new line. |
IsSystem | true/false | This is true if this is a bigtime created value, false if the UDF was created by the user. |
IsRequired | true/false | Marks if the custom field is required to be filled in when a user creates a timesheet entry. |
SortOrd | Integer | The order in which the custom fields are displayed in a timesheet, lowest to greatest being the last custom field. |
ImportId | Integer | This identifies if the field was created by an import. |
UDFHtmlInput | String | This is not used. |
Types | List | This is not used. |
ErrorList | List | This will the display the most recent error if any while saving the udf. |
Field | Type | Description |
---|---|---|
StrVal | String | The value of the user defined field. |
EntityId | Integer | This should match the unique identifer of the time entry queried. |
EntityType | Integer | The number representation of the ENum, this should match back to the type in UDFList. |
Label | String | The label the user sees this field as in the UI. |
UDFNm | String | The name of the user defined field stored in bigtime. |
UDFSid | Integer | The unique identifier of the user defined field, this can be found in UDFList to match. |
ValueType | String | This is the type of the user defined field. |
ErrorList | List | This is a list of any errors caused during the save. |
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.
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)
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)
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.
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)
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)
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.
Field | Type | Description | View(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 |
if you are pulling an listing of expense report objects, then that list will contain an array of objects with the fields listed below.
Field | Type | Description | View(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. |
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.
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.
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.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId} HTTP DELETE: /expense/receipt/{sid} HTTP RESPONSE: {result: true }