BigTime API (v2)
api login

The BigTime API Transactions and the Async Controller

For actions that can be complicated or time consuming, BigTime provides an ansychronous controller that operates on a "ticketing" system. You submit a request, and the server gives you back a "ticket." Then, your service can come back and check on the status of that ticket as often as you'd like. When BigTime is finished with the process, your ticket will return the results.

For simple read/write functions, that type of anynchronous processing is not needed. But, for things like integration requests (eg - "post this time to QuickBooks") or more complicated requests ("update the billing rates on all of my unbilled time"), they are the ONLY way to accomplish your goal.

This page will walk you through the basics of submitting a request and tracking a processing ticket. Then, we'll list the set of async requests that the API currently supports.

Keeping track of your tickets.

You'll kick off an async process by calling one of the pre-defined functions below. That function will return a TICKET (a unique guid which identifies the process and lets you track it's progress).

Most of these processes take a couple of seconds to complete, so your system can make calls to /Async/Ticket/{id} in order to check on their progress. You shouldn't call that end point very often, and most applications find a 5-10 second delay between calls sufficient.

Both your calls to specific async functions as well as your call to /async/ticket will return a transaction object (details on that object are listed below). To figure out whether or not a transaction has been completed, you can refer to the ticket's resultCode property.

Transaction Object: Field Details

For most of the operations listed above, your post/get will return a single transaction object The field list below is a complete list of fields available through the api.

FieldTypeDescription
txnId String This is your ticket. You can now use that id to check on the status of the async process you requested (by calling /async/Ticket/{txnId}).
resultCode Integer current status of this ticket. This is originally 0 (in process) and will change to 1 (success) if the transaction is completed successfully. If the status return 3 (error), then check the errors object for an explanation.
description String Text description of the transaction (this can be used in any UI you present once a transaction status moves to completed -- so you won't need to retain the original context).
submitDt Date Date/Time that the transaction was submitted.
completedDt Date Date/Time that the transaction was completed.
errors ModelError This is a structure, not a text field. An array of model error objects. Since there are not fields to which transaction errors should be attached, the model error structure has an empty FieldName (see below for an example of errors returned from a typical posting. 
{"": ["You're attempting to submit timesheet data for a closed period.",
      "ABC Company is closed, so new time cannot be submitted on it."]
}
Note, in this example, that there are 2 errors logged for this transaction. and that the label is "" (an empty field name).

Submitting a timesheet.
try it

Use the call format below to request a ticket for timesheet submission. 
HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /Async/submitTimesheet/{staffSid}?startDt={YYYYMMDD}&endDt={YYYYMMDD}
HTTP RESPONSE:  a single Ticket object (see bellow)
ParameterTypeDescription
StaffSid Numeric Specifies an staffsid for whom you would like to submit time. USE "0" to denote the logged in user as this parameter is required.
StartDt Numeric Starting date for the timesheet data that you'd like to submit (in YYYYMMDD format). This MUST be specified or the request will return an error.
EndDt Numeric Ending date for the timesheet data that you'd like to submit (in YYYYMMDD format). This MUST be specified or the request will return an error.

Submitting a signed timesheet.
try it

If your firm has an active transaction audit log that requires a user to to sign their timesheet, then any requests for submission must accompany an e-signature. To do so, the use must submit their BigTime user name and BigTime password along with the timesheet submission request. 
HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST:  /Async/submitTimesheetSigned/{StafferId}
HTTP RESPONSE:  a single Ticket object (see bellow)
POST DATA: {StartDt:"yyyy-MM-dd", EndDt:"yyyy-MM-dd", Signature: "Joe Schmoe", UserPasscode:"password123"}
ParameterTypeDescription
StaffSid Numeric Specifies an staffsid for whom you would like to submit time. USE "0" to denote the logged in user as this parameter is required.
StartDt Numeric Starting date for the timesheet data that you'd like to submit (in YYYYMMDD format). This MUST be specified or the request will return an error.
EndDt Numeric Ending date for the timesheet data that you'd like to submit (in YYYYMMDD format). This MUST be specified or the request will return an error.

Submitting expenses.
try it

Use the call format below to request a ticket for expense report submission. Note that this request will submit ALL of the user's unsubmitted expenses and will create a new report with the title specified. 
HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /Async/submitExpenses/{staffSid}?title={title}
HTTP RESPONSE:  a single Ticket object (see bellow)
ParameterTypeDescription
StaffSid Numeric Specifies an staffsid for whom you would like to submit expenses. USE "0" to denote the logged in user as this parameter is required.
title string The title of the newly created report. Note that BigTime will strip out all "html" characters. If this parameter isn't supplied, the system will use the current date as the expense report name.