api login

BigTime supports session-based name/password authentication, and you'll use your own BigTime login to validate your user session.

This page will walk you through establishing a new BigTime user session and using the values retured to help validate any subsequent calls you make to BigTime.

API Session Expiration.

Note that you will only need to make the call to SESSION once. After you do, you can simply use the token(s) returned by that call to prove that you have been validated by the BigTime system. API tokens expire after 24 hours. If your session is expired, then any calls you make to the BigTime api will recieve an HTTP 401 error. Just re-establish your session (with a new post to Session to get a new set of tokens) in order to overcome that error.

Creating a basic BigTime Session.

POST /session to establish a new session. Your post will need to contain the following information.
	{UserId: 'jsmith@example.com', Pwd: 'mother'}

Once that post is validated, you'll get a valid response back from the BigTime server.

	{firm: 'abc3-4567-fgr4', staffsid: 21, userid: 999, token: 'asdf-werq-3asdf-ase5-qfaw5e' ... }

You can use the firm/token for each of your subsequent calls to the BigTime api (note that the response contains more than the fields shown here and a complete list can be found at the bottom of this page). For example, to pull a list of projects that are valid for this firm (name/id only), you can use the following http call:

	headers X-Auth-Token:asdf-werq-3asdf-ase5-qfaw5e ; X-Auth-Realm: abc3-4567-fgr4
	HTTP GET /picklist/projects

Creating a Firm-Specific Session.

Note that the standard BigTime session will connect a user to the firm that they were (most-recently) logged into. Since the vast majority of BigTime users are members of only one firm, that behavior is (typically) enough. Some power users, however, have more than one BigTime subscription (eg - they belong to more than one BigTime firm).

For these users, you can include a firm in your session post. As long as the user is, in-fact, a valid member of that firm -- your session will be pre-set with access to the firm you specified in your post.

HTTP POST:  /session
POST CONTENT:  {UserId: 'jsmith@example.com', Pwd: 'mother', firm: 'abc-4547-gggg'}
HTTP RESPONSE:  {firm: 'abc-4547-gggg', staffsid: 21, userid: 999, token: 'asdf-werq-3asdf-ase5-xxx' ... (see below) }

Getting a list of Firms for a specific user.
try it
  • This is a get request. No posting data required.

  • GET

If you aren't sure which firms a user has rights to view, you can get a list of that user's firm using the Session's Firms action. Note that this action requires you to establish a valid session token before you call it.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourCurrentActiveFirmId}
HTTP GET:  /session/firms
HTTP RESPONSE:  [{id: 'abc-4547-gggg', name:'ABC Company'}, {id: 'abc-xxx', name:'XYZ Company'} ...]

Note that the response from this call is an array of valid firm id's. Now, you can use the api to CHANGE the firm to which the user's current session is attached.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourCurrentActiveFirmId}
HTTP GET:  /session/firm/abc-4547-gggg
HTTP RESPONSE:  {firm: 'abc-4547-gggg', staffsid: 21, userid: 999, token: 'asdf-werq-3asdf-ase5-xxx' ... (see below) }

Keep in mind that everything on this new response has changed. Your original session token should be replaced with this new (firm-specific) token. Your staffsid is different, and (obviously) so is your firm.

User Session: Field Details

When you create a new user session (or link an existing session to a new firm), the response will contain the fields listed below. While you will need to use firm and token to access any of the other functions in the BigTime api, each session also returns some useful "user-specific" information.

token string The unique session token used to access the rest of the api (you will use this parameter as the X-Auth-Token parameter for any future api calls. Session tokens expire after several hours of inactivity, and they can ONLY be used for the firm to which they are attached (switching firms will generate a new session token).
firm string The unique id of the firm to which this session is attached. Note that firm id's do not change, so you can remember the firmId a user selects and store it locally. Also note that a user's "initial" login session comes pre-attached to their default firm (eg - the firm to which they were last logged in).
staffsid integer Within the API, objects are attached to "staff members" (eg - time entries, expenses, et al). This value corresponds to the user's "staffSid" within the firm to which the are attached. A user is given a permanant UserId when they subscribe to BigTime, and they are given a firm-specific StaffSid each time they add a new firm to their list. A user's staffSid (within a firm) a never the same from firm-to-firm (eg - my StaffSid in "ABC Company" may be 1234, but it will not be 1234 in "XYZ Company." This really only matters if you are allowing users to move from firm to firm in your application.
userid integer Unlike the StaffSid, the UserId will not change as a user moves from firm to firm. The userId is assigned globally to this user login, and it never changes. We do not, however, use the UserId anywhere in the API (except for login).
fname string User's first (given) name.
sname string User's last (family) name.
IsFirmAdmin Boolean Returns TRUE if this user has ADMIN rights in the firm to which they are connected. Please rememeber that a user's rights can vary from firm-to-firm -- so you shouldn't assume that a user is an "admin" in every firm they belong to just because they happen to be an admin in any given firm (eg - I could be an admin user for ABC Company, but just a staff user for XYZ Company).
IsFirmOwner Boolean TRUE if this user is the individual responsible for the BigTime subscription for this firm. Again, this value is firm-specific (not user-specific). So, I could be a firm owner for ABC Company, but just a standard user for XYX Company. Always re-check this value after you switch firms in the api.
FirmCount Integer Most of BigTime's users belong to only one firm. For a small miniority of users, BigTime is used for multiple firms (eg - a contractor that does work for several customers and ALL of those customers ask the contractor to log their time using BigTime or an accountant who manages the BigTime instance for a number of their clients).
SubscriptionType Integer 1 = Express, 2 = premier, 4=enterprise

Setting a user's timezone.

If you are using the API to create/maintain timers, then you may want to set the user's timezone once a new session is established. If you do, then all of the server's timer data will be passed to you in the user's timezone. Otherwise, the server timezone will be used.

If you'd like, you can pass in the GMT offset in minutes instead of an hourly fraction. Given that fact, /session/timezone/-3 and /session/timezone/-180 are equivalent calls.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST:  /session/timezone/2.25
HTTP RESPONSE:  200 (blank)

Validating staffer rights.

Some parts of the API are protected by a staffer's system rights. While the API will not allow access to sections of BigTime that the staffer does not have rights to see, you may want to check a staffer's rights before attempting to call protected areas of the API to improve your user experience.

Calling the /session/IsPermitted end point will return a simple true/false value to let you know if your current staffer has access to any of the specific rights listed below.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST:  /session/IsPermitted/FinancialAdmin
HTTP RESPONSE:  200 if the user is permitted or 405 if the user is not permitted that user right.
EditFirmSettings Edit Firm Settings
EditUserSecurity Edit Security Rights/Settings
FinancialAdmin The user is a "financial" admin for this firm
MenuAllowProjectList User is allowed to view project data (for any projects they have rights to see)
MenuAllowStaffList User is allowed to view staff data (for any staffers they have rights to see)
CanAddProjects User is allowed to ADD projects to the system
LogTimeAgainstAnyProject User is allowed to log time against any project in the system
LogExpensesAgainstAnyProjects User is allowed to log expenses against any project in the system
ViewStaffHRData User has access to view staffer billing rate/cost information
AllReportsAccess User has access to the entire reporting engine interface

Provisioning a New Subscription.

If you have a valid productId/code from BigTime, then you can use the Provision end-point to create and provision new users and firms. Note that this end-point is typically used by BigTime partners, not customers.

HTTP POST:  /session/provision
HTTP RESPONSE:  [{id: 'abc-4547-gggg', name:'ABC Company'}, {id: 'abc-xxx', name:'XYZ Company'} ...]

The response from this call is a 500 if the provisoning fails, and a valid user session if the provisioning is successful.

FName* String New user's first (given) name
SName* String New user's last (family) name
FirmNm* String Name of the firm that will be created during this provisioning request.
EMail* String The new user's email address (note that this value must be unique). Your attempt to provision a new firm with a non-unique email address will result in an error.
Password* String The password to use when provisioning the new user's login.
IndustryType String The code for the industry type that this new subscription should use.
ProductId* String provided by BigTime Support if your firm is authorized to provision new subscriptions.
ProductCode* String provided by BigTime Support if your firm is authorized to provision new subscriptions.

Making Api Calls.

You can use the other pages in this document to try various calls to the api, and see the results live. Just click the LOGIN button at the top of this page, and we'll take care of adding headers to your request on-the-fly.

In addition, if you'd like to Make a GET/POST call manually, simply enter the relative URL in the form below and click the GET/POST buttons. We'll show the results of your call in the space below as well.