Boss Insights offers a single API which gives you a complete picture of your business customers' financial data. It’s a tool used by financial service providers to create user-friendly digital platforms that connect with the software apps used by small to medium business owners.
The Boss Insights API provides a common data model to access various business objects in a uniform way. Data from various apps businesses use is mapped and standardized, so you can query it consistently while providing full traceability to the original source data. By default, the API operates as read-only which means you can access business data with full confidence that source data won't be modified inadvertently.
The API consists of two components. The first is the server-side REST-based API for retrieving business data. The second is an optional client-side web-based library that can be embedded within your service. This library allows a financial institutions' clients to authorize, link, map, and reconcile their app data seamlessly.
By default, the API operates as read-only, so you can confidently access business data without worrying about unintentional modification to the source data.
The API is the same foundational component used behind the Portal, our ready-to-go user interface. You have the flexibility to use it either alongside the Portal or independently, embedded directly into your own service.
Boss Insights' API offers a variety of different data sources, please click on one of the links below to learn more about the data found within our API.
To manage and provision accounts that store your customers' data, as well as handle app connection information, the Administration API is available for your use. It provides the necessary functionalities to efficiently handle these tasks.
Definitions and Conventions
company are often used interchangeably within this document. Each company that wishes to share data with you is created on the server-side and all data is stored in a secure isolated Account.
Your tenant account and any company accounts that share data with you are created and accessible under their own internet domain name. A domain name is composed of two parts, the
root domain and the
sub domain. Depending on your data residency your root domain may end in
.com based on whether your data is stored in Canada or the USA (it may also be something else if your tenancy is set up with a custom root domain). Typically, your account will be accessed as https://`mycompany`.myintranetapps.com and for the purpose of this documentation we will use the root domain myintranetapps.com.
All dates used by the API are in ISO 8601 format (e.g. 2021-05-13T05:03:23Z). The default timezone is UTC. Where start or end dates are used as parameters to object endpoints the shorthand form of YYYY-MM-DD can be used, where if the date is a start date it becomes YYYY-MM-DDT00:00:00Z and an end date becomes YYYY-MM-DDT23:59:59Z.
Our API endpoints are documented at http://api.bossinsights.com and are available as a Postman collection. The fastest way to get started with our server-side API is using Postman (a 3rd party API development tool), if you've not used it before then we recommend checking https://learning.postman.com/ . The Postman collection provides sample API calls in commonly used programming languages including Ruby, Java, C#, PHP, Python, Node.js and more.
Your sandbox and production accounts also include a web interface at https://
mycompany-sandbox.myintranetapps.com/api/ and https://
mycompany.myintranetapps.com/api/ respectively that allow you to interactively query the API.
Please visit our Sandboxsection to learn more.
When accessing the API via your web browser the basic authentication credentials will be cached and you can perform more than one query without being prompted for credentials, but when you use Postman or in your own code you will need to send the authorization headers with each request.
Because your account has been granted access to the data of your customer companies you can use the API https://
mycompany.myintranetapps.com/api/ and the various endpoints like https://
mycompany.myintranetapps.com/api/accounts and https://
mycompany.myintranetapps.com/api/trial_balances and to switch between the various company accounts you need to specify an additional parameter in your GET and POST requests you make called
X_ACCOUNT_KEY which should be set to the value of the unique account key of a particular company account you are interested in querying. You can only access accounts which are connected to your account and have sharing enabled.
Querying and Pagination
Each object type in the common data model generally provides an endpoint to get a specific object as well as an endpoint to retrieve a collection of objects. Most objects support pagination and will generally return up to 30 results at a time. The
page parameter is used to access a specific page of results, if you wish to obtain all results then you would loop until the result set is empty, increasing the page number at each loop. Some object endpoints may support additional querying parameters such as categories or date ranges to further focus the result set.
You should assume when using the API that eventually an error may be generated. When an error occurs the HTTP status code returned will be in the 500-599 range, while a successful response will be in the 200-299 range. 400 range codes will also be returned when invalid input is provided to the API, i.e. if an authentication failure occurs the 401 code will be returned. Generally the 400 series codes represent errors that should not be retried without changing the input parameters while the 500 series are temporary retryable errors. It is recommended to implement a form of exponential backoff and/or a retry limit to avoid unnecessary resource consumption.
Our systems rate limit requests to ensure high availability of resources for all customers. We limit the rate you may perform server-side API requests to 100 rps per company - this is designed as a safe guard, contact us to raise your limit if your use case demands a higher level of usage.
Versioning and Deprecation
We send periodic update notices when our platform will be changed. This includes, but is not limited to, changes to endpoints, data types, the Boss Insights common data model, and infrastructure.
We favor making changes backward-compatible, for example:
Adding new API endpoints.
Adding new optional parameters to existing endpoints.
Adding new data elements to existing response schemas.
Adding new error types and error codes.
Adding new webhook types.
It is your responsibility to modify your code within the update notice period.
The steps involved in successfully testing the API include:
Create a test company account and store its
Connect an app in the newly created company account
Access your API and request data from the newly created company account
To access Boss Insights API you use both a server-side, and a client-side component. The end-user flow looks like this:
You may also check the common data model provided by Boss Insights to access various business objects in a uniform way.
If you would prefer a prebuilt solution, we also offer The Portal. This user interface uses the same API behind the scenes.
If you have more questions about our product, please reach out to the support team!