api login

The BigTime API is a REST-based service that allows you to get directly to your BigTime data. It gives you a simple way to integration all of your information with other tools/programs "behind-the-scenes."

RESTFul services are just data-centric http calls.

If you haven't worked with RESTful services before, there are several web-based resources you can use to get familiar with them. In general, the BigTime api is just a collection of specialized http pages that return data instead of a web page.

You can decide the type of data you'd like to download, and BigTime supports both XML and JSON data formats. Like most REST services, we figure out what type of data you'd like to download by reading the content-type header in your http call.

Getting to the BigTime API

Note that the Base Url for this version of the BigTime api is: https://iq.bigtime.net/BigtimeData/api/v2/

Throughout the api, you will see Restful URL's listed as "relative" urls. Each of those url's is beneath this base Url. So, a relative Url of /Staff is actually a call to https://iq.bigtime.net/BigtimeData/api/v2/Staff You should keep that in mind as you review the api documentation.

Pulling Data from the API.

In order to access your data, you need to create a "session." The API session gives us a chance to authenticate you as a user, and it tells BigTime what company data you'd like to access. Once you estabilish a session, you can use it to read/write data with other calls to the api.

  1. Establish a BigTime API session by POSTING your username/password to https://iq.bigtime.net/BigtimeData/api/v2/session. The system will return an object that contains both a firm and a token for you to use on all subsequent api calls.
  2. Retreive Information from BigTime by making a GET request. Use the URL's listed in the api to pull information from the system. In each case, you'll need to include the http headers X-auth-token and X-auth-realm with your session token and firm id in order to pull data.
  3. Update your BigTime data by POSTING a valid request. Again, use the URL's listed in the api to update data. When you post, you'll need to make sure that the data you post conforms to the field name(s) in the object definitions listed in the api. Note that, in most circumstances, you are posting for a specific ID to "update" and you are posting with no ID to "create."

Do I have to access the api with a user/password?

Most API consumers implement user-level authentication so that the data returned to your system is restricted based on the user's access level. In some situation, however, you may want access to data at the firm (eg - "admin") level. In that circumstance, you may find the Firm-Level session is more appropriate.

Setting up Firm-Level Session Access

In order to create a firm-level session, your system administrator needs to create a firm access token. Note that each firm-access token is like an administrator's passcode to ALL of your firm's data. So, you should treat that access token the same way you would treat a user's password. Never store it in plain text, replace/renew those tokens regularly, etc.

Accessing the API with a firm-level token.
  1. Establish a BigTime API session by POSTING your token/firmid to https://iq.bigtime.net/BigtimeData/api/v2/session/firm. The system will return an object that contains both a firm and a token for you to use on all subsequent api calls.
  2. Retreive Information from BigTime using firm token instead of the session ticket. Just like the session ticket, the firm ticket must be included in the http headers. Firm sessions use X-auth-ApiToken and X-auth-realm headers to hold the firm session token and firm id respectively.
  3. API Keys are permanent. You can use the URL's listed in the api to update data. The API ticket acts as a permanent session for accessing your firm's data, and it will mimic the security rights of the user who created it.

BigTime supports both json and xml data formats.

For an XML request, send application/xml in the Accept and Content-Type headers. If you'd like to download json data, send the value application/json instead.

In this documentation, most of our examples assume the JSON format, but your XML calls will follow similar structure.

API Limits and the 503 Error.

BigTime's api is used by thousands of firms around the world, so we need to make sure that the community treats it responsibly. Occasionally, programs under development will accidentally make hundreds of calls over the course of a minute or two which can seriously degrade performance for the API. To prevent that, we limit API calls to 30/minute (per session token). Note that this is not a per-firm throttle (each unique user session has it's own throttle).

If you hit that limit, you'll get an HTTP 503 status code (use the Retry-After HTTP header to figure out how many seconds are left until your throttle is lifted). The throttle is lifted automatically when your retry-after period expires.