Boss Insights is a provider of a single API that provides a holistic view of your business customers.
This documentation is intended for software developers and covers the Boss Insights API. This API provides a single view to various types of business data from accounting and banking through to commerce, marketing and more.
If you want to know all the software apps that Boss Insights can connect with please look at our integrations page.
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 standardised, 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 is split into a server-side REST based API used to pull business data, and an optional branded client-side web based library that is embedded within your service that your customers use to authorize, link, map and reconcile their apps data.
The API is the same foundational component used within our own portal product and can be used in conjunction with this portal or standalone embedded within your service.
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.
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:
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.
Your sandbox account is a separate environment completely isolated from your production account. The sandbox account is commonly used by developers when initially learning the API and also as a User Acceptance Testing (UAT) environment to try new changes before promoting them to production. Functionally the sandbox account is identical to the production account with one notable exception which is that external API communication with your customers 3rd party applications (e.g. Quickbooks, Salesforce) use sandbox API credentials instead of production.
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.
To embed client-side widgets within your own app or service see Embedded documentation.
Access to the API is granted via API users and associated tokens. If a token is compromised a new token may be generated and the old token will be made inactive. All communication with the API is encrypted via HTTPS TLS connections.