BigTime's time entry api provides access to user's timesheet data -- allowing you to create programs and web services that query, create or edit a user's time entry data without relying on the BigTime web pages.

Retrieving time entry data for a specific date range.

try it

• BasicDetailed
• Submit

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /time/Sheet/{staffsid}?StartDt={YYYY-MM-DD}&EndDt={YYYY-MM-DD}&View={Detailed}
HTTP RESPONSE:  (array of TimeEntry objects -- see below for details)

Retrieving time entry data for a specific project.

try it

• BasicDetailed
• Submit

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /time/ByProject/{Id}?StartDt={YYYY-MM-DD}&EndDt={YYYY-MM-DD}&View={Detailed}&[IsApproved=TRUE/FALSE]
HTTP RESPONSE:  (array of TimeEntry objects -- see below for details)

Pulling the detail for a specific time entry.

try it

• Get

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

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

Creating a NEW time entry.

try it

• {"staffsid": 0, "projectsid":0, "dt":"2013-01-01", "hours_in": 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 create time against a project you don't have rights to log time against).

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post:  /time [?MarkSubmitted=true/false]
POST CONTENT:  {"staffsid": 123, 
		"projectsid": 123, 
		"dt": "2013-01-01", 
		"hours_in"": 1.25, 
		"notes": "These are my time entry notes..."}
		
You can include ANY of the AddUpdate fields below, 
		but you MUST include the required (*) fields.

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

Updating Existing Time Entries.

try it

•  Mark SubmittedSubmit

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 create time against a project you don't have rights to log time against).

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post:  /time/{sid} [?MarkSubmitted=true/false]
POST CONTENT:  {hours_in: 2.25, 
		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 TimeEntry object -- see below for details)

Deleting a Time Entry.

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:  /time/{sid}
HTTP RESPONSE:  200 is a successful delete.

Getting the Weekly Start Date.

try it

• Submit

Pass a date and the system will return the weekly start date that CONTAINS that date (based on the user's firm settings).

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /time/periodContainingDate/{yyyyMMdd}
HTTP RESPONSE:  date in yyyy-MM-dd format.

Getting custom fields list and values for time entry. Parameters are the SID from the time 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 time entry item.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /time/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 time entry.

try it

• POST

You can use a simple POST request to push a custom field detail associated with a single time 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 time 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. NOTE: The time id should be negative if unsubmitted and postive if querying for submitted time. However, the EntityID field should ALWAYS be a positive number.

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

Getting a summary of timesheet data (by date).

try it

• Submit

Pass a date range and the system will return a single object for each date during that period that the user has time entry data.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /time/TotalByDay/{staffsid}?StartDt={YYYY-MM-DD}&EndDt={YYYY-MM-DD}
HTTP RESPONSE:  array of DailyTotal objects (see below).

Updating an Audit Log entry/comment.

try it

• {"EntrySid":1, "Nt":"User comments/updates entered here."}
• Submit

If your firm uses the system's audit logging to track user comments on changes that are made which don't conform to your audit standards, then you can use this end-point to update log entries with user comments.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST:  /time/AuditLogDetail
HTTP RESPONSE:  empty HTTP 200 means that the audit log comment was updated correctly.

When a user needs to track activity that starts/stops throughout the day, they use BigTime's timer functionality to track that work. Then, once that work is completed (or once the day ends), those timers can be converted into time entries. The timer end-points in the api allow you to manage those activities.

Timer don't have dates. A timer is a work in progress. It's a stopwatch that hasn't been turned into an actual time entry yet. So, timer objects don't have a "date" Once those objects are converted into time entries -- then they will have dates assigned.

Timer information isn't included in your summary of timesheet data. Since timers are works in progress, their numbers aren't included in your daily summaries. For a complete picture of time entry "totals" for today's date, you should call /timer/total to get a total number of elapsed hours to add to the current date's total.

Getting a list of active timers.

try it

• Get List

Call this simple end-point and the system will return all of the user's active timers.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /timer/sheet/{staffsid}
HTTP RESPONSE:  List of Timer objects (see detail below).

Timer objects are very similar to TimeEntry objects. In fact, the list of fields for a TimeEntry contains the "Timer" tag (above) for the set of fields that are returned for a timer object.

In addition to the basic time-entry related fields, every Timer object returns the following information.

Getting the total number of "timer" hours.

try it

• Get Value

Call this simple end-point and the system will return the total hours in the user's timer list as well as the id/start time/elapsed time of the current "active" timer.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /timer/total/{staffsid}
HTTP RESPONSE:  {totalHours:2.256645, 
      activeTimerSid:1, 
		activeTimerStartDt:1234876595689, 
		activeTimerProjectNm: "ABC Company",
		activeTimerHours:1.006645}.

Getting a single timer's detail.

try it

• Get

You can use a simple GET request to pull the details associated with a single timer. Note that the TIMER view (see field list above) will be returned by default.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /timer/item/{sid}
HTTP RESPONSE:  (Timer object -- see above for details)

Getting the current "active" timer.

try it

• Get

As mentioned, only one timer can be actively accumulating time at any given moment. You don't need to know which one -- just call this end point to get a copy of the user's currently running timer. If no timer is found, the system will return an empty 200 response. Note that you can also pass an alternative staffSid to get the active timer for a specific staffer. By default, the current user's active timer is returned.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /timer/activeItem/{staffSid}
HTTP RESPONSE:  (Timer object -- see above for details)

Creating a NEW timer.

try it

• {staffsid: 0, projectsid:0 }
• Post

Note that only the fields listed in the AddUpdate view (above) should be included in your post to this url. This works just like a time entry -- so 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 create time against a project you don't have rights to log time against).

Use the /Add endpoint to create a new (blank) timer that is automatically started.

You can save a new timer that was "already started" by passing a value for StartTime when you create a new timer. This will (a) automatically stop any running timer(s) and (b) create a new timer with a "starttime" of the value passed in your json.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post:  /timer/item
POST CONTENT:  {staffsid: 123, 
		projectsid: 123, 
		hours_in: 1.25, 
		notes: "These are my timer notes..."}
		
You can include ANY of the AddUpdate fields below, 
		but you MUST include the required (*) fields.

HTTP RESPONSE:  (new Timer object -- see above for details)

Creating a new BLANK timer.

try it

• Get

Creates a new timer (linked to the user but nothing else) and starts it automatically.

BigTime will pause any running timers and start the new one you create automatically.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /timer/add
HTTP RESPONSE:  (new Timer object -- see above for details)

Updating Existing Timers.

try it

• Submit

Only the fields listed in the AddUpdate views (above) should be included in your post to this url.

There are several ways to start a new timer, but the best approach it to call the /start/ endpoint. If you setting the IsActive value to TRUE has the same effect. If you want to start a timer "as of" a specific date, then pass the UTC timestamp to StartTime.

You should also note that setting IsActive to FALSE has the same effect as cancelling a timer. So, if you're passing IsActive=FALSE to an active timer, then you should also pass a "final" number in Hours_IN for that timer's total hours. If, however, you are using the server to track and control timers, it's best to use the start/stop endpoints to activate and de-activate timers.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post:  /timer/Item{sid}
POST CONTENT:  {projectSid: 1234, 
		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 Timer object -- see above for details)

Deleting a Timer.

try it

• delete

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

Starting/Pausing existing timers.

try start

• Go

try pause

• Go

Starting a timer will automatically pause any other running timers, so you should not need to call pause explicitly if you are just switching the "active" status from one timer to another.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
STARTING:  /timer/start/{sid}
PAUSING:  /timer/pause/{sid}
HTTP RESPONSE:  (updated Timer object -- see above for details)

Converting a timer into a time entry.

try it

• Go

As a final step in a timer's life-cycle, a user will convert it into a time entry. Calling this function will (a) create that entry and (b) delete the timer. The call will return a server error if it fails, and the timer will not be removed.

If the user has made updates to the timer they want to convert, you can post those updates as well.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
POST:  /timer/SaveAsTime/{sid}
HTTP RESPONSE:  (new TIME ENTRY OBJECT -- see above for details)

Closing out ALL of a user's timers.

try it

• Go

Instead of closing out timers one at a time, your user may want to close out all of thier open timers at once. BigTime makes this endpoint abailable to accomplish exactly that task.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
POST:  /timer/CloseAllTimers/{staffsid}
HTTP RESPONSE:  A list of time entry Id's added:
      {-1234,-123456,-3333,...}