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."
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.
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.
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.
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.X-auth-token
and X-auth-realm
with your session token and firm id in order to pull data.
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.
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.
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.X-auth-ApiToken
and X-auth-realm
headers to hold the firm session token and firm id respectively.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.
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.