The IntelligenceBank API lets your own systems read from and write to your IntelligenceBank platform, so the assets, records and data you manage in IntelligenceBank can move automatically between IntelligenceBank and the other tools your organization runs.
Table of Contents
What the API Is
The IntelligenceBank API is a web service that sits alongside your platform. Anything you can see and do in the IntelligenceBank interface, you can also drive programmatically from your own code, subject to the same permissions and the same rules.
It is a standard HTTPS API that returns JSON, so it works with any language or integration platform that can make a web request. Our own connectors and add-ins are built on it, and it is the same API we make available to you.
The complete technical reference, covering every object, operation, parameter and example, is published at apidoc.intelligencebank.com. This article introduces the key ideas behind it so that the reference makes sense when you get there.
What You Can Do With It
Customers typically reach for the API to do one of four things:
- Get content out: search your platform and pull assets, metadata and download links into a website, an app, a content management system or a partner portal.
- Push content in: upload files and create or update records from another system, so IntelligenceBank stays the single source of truth without anyone rekeying data.
- Keep two systems in step: run a scheduled synchronisation so changes made in one place show up in the other.
- Automate a process: trigger work from your own business events, for example submitting content for a compliance review or provisioning users.
Exactly which parts of your platform are reachable depends on the modules and features enabled for your organization. The documentation always reflects what is currently available.
Key Concepts
Current and legacy calls
The Graph API (v3) is the current API and is where the functionality lives. Legacy API calls are still used for one thing: signing in, either with a username and password or via the browser. A typical integration authenticates with a legacy login call, then makes all of its authenticated calls against v3.
Both are covered in the same documentation, so you do not need to look in two places.
Signing in
There are three ways to authenticate, and the right one depends on how your integration runs:
- Standard login: a username and password are exchanged for a session. Simple, and the quickest way to start experimenting.
- Browser login: the same result, but the sign-in happens in a browser window. Use this if your organization has Single Sign-On or Two Factor Authentication turned on, because a username and password alone will not get you through.
- OAuth 2.0 client credentials: server-to-server authentication, for unattended integrations that run on a schedule with no person present.
The values you work with
Every call carries a few values that identify your platform and prove who is making the call. Which ones you need depends on how you authenticate.
| Value | Used with | What it is |
|---|---|---|
| Platform URL | Standard and browser login | The address your users already sign in to. Standard login uses it to look up your API v2 URL; browser login signs in against it directly. |
| API v2 URL | Standard login | The regional login service where a username and password are exchanged for a session. Not the same as your platform URL. See What is my API v2 URL? |
| API v3 URL | All methods | The root address for all Graph API calls. Signing in returns it, and server-to-server integrations get it from this unauthenticated call, so you never hard-code it. |
| Client ID | All methods | Identifies your platform and appears in the address of every Graph API call. It comes from signing in, or from the same unauthenticated call. This is not the OAuth client ID below. |
| Session ID | Standard and browser login | Returned by the login call and sent as a sid header on every call. It expires with the session, so a long-running integration has to sign in again. |
| Token endpoint | Server-to-server | Where you exchange your OAuth credentials for an access token. Issued to you with the credentials. |
| OAuth client ID and secret | Server-to-server | The credentials themselves, issued against the user you nominate. Keep the secret out of source control and out of your logs. |
| Access token | Server-to-server | What the token endpoint returns, sent as an Authorization: Bearer header in place of a session ID. Short-lived, so cache it and refresh it on expiry. |
The API respects your permissions
Calls run as the user account that signed in, not as an all-powerful administrator. If that user cannot see a folder or edit a record in the interface, the API will not let them do it either. This matters when you design an integration: create a dedicated user for it and give that user exactly the access it needs, no more.
You ask for exactly what you need
The Graph API is built around describing the shape of the answer you want. Rather than a fixed response, a request can say how many items to return, where to start in a longer list, which fields to include and how to sort them. Being specific keeps responses small and your integration fast, and it is the single biggest thing you can do to make an integration behave well at scale.
A generic JSON interface
Most calls are made the ordinary way, with the detail carried in the web address. There is also a generic JSON interface: a single entry point that takes the whole call as a JSON body instead. Any API call can be routed through it, and it is particularly suited to building more complex read queries, where nested conditions become awkward to express in an address.
Limits and errors
Two kinds of limit apply. A rate limit of 600 calls per minute applies to each user account, and a daily, monthly or yearly call allowance applies to your organization's account. Build your integration to pace itself and to retry politely rather than hammering the API when it is refused.
Errors come back as standard HTTP status codes with a machine-readable reason, so your code can tell the difference between an expired session, a permission problem, something that does not exist and a request that was simply wrong. You can also ask for verbose responses, which add a plain-language message alongside the machine-readable one and make logs far easier to read while you are building. The documentation lists the common ones with examples.
Getting Started
| 1Confirm your access | API access is an add-on, so check that it is enabled on your platform before you build anything. If you are not sure, ask us. |
| 2Open the documentation | Go to apidoc.intelligencebank.com and read the Authentication section first. Everything else assumes you have signed in. |
| 3Try it before you code | The documentation includes a ready-made collection you can run in Postman. It fills in most values for you after a single login call, which is by far the fastest way to see real responses from your own platform. |
| 4Build with a dedicated user | When you move from experimenting to building, give the integration its own user account with only the permissions it needs, rather than running it as a person. |
Access and Availability
API access is an optional add-on rather than a standard inclusion, and the call allowance that comes with it is agreed as part of your subscription. If your platform does not have it yet, or you are not sure whether it does, get in touch and we will confirm what is enabled and what your options are.
It is worth talking to us early. We can tell you whether an existing connector already covers what you are planning to build, which often saves the work entirely.
Need Help?
To request API access, to check what is enabled on your platform, or for any other API question that needs our team, you can submit a ticket.
Contact Us About API AccessWas this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article