Getting Started with BigTime's API
Print this Article
Email this Article
BigTime is supported by a robust API, and the documentation for it can be found at iq.bigtime.net/bigtimedata.
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."
The API is a REST-ful Service
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.
Connecting to the API
In order to access your data, you'll need to create a "session." That API session allows us to authenticate you as a user, and it tells BigTime what company data you'd like to access. Once you establish a session, you can use it to read/write data with other calls to the api.
- 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.
- Retrieve 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.
- 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."
Most of the data you are used to seeing in BigTime is available in the api, and you can view the api help pages in order to get a complete understanding of the end-points and fields that are supported for each data type.
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.
User-Rights and API Calls
Ultimately, every call you make to the API will only return the data that the user-login you've provided has rights to see. Even firm-level sessions are tied back to a specific user (typically your admin user). So, you'll want to be aware of the user rights associated with your session while making calls to the api.
If you are worried that a user may not have rights to access specific data, then you can use the /session/isPermitted end-point to check user permissions before making other calls. Take a look at the Getting Connected help page for more information on this call.