The API
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.
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.
Download our Postman Collection to speed your development. We’ve also provided a Postman guide to help you get started.
API Categories
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.
Administration 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.
Accounting API
Please visit our Accounting API documentation to learn more about accounting data including guides and tutorials. You may also visit our Accounting API page to learn more about integrations.
Banking API
Please visit our Banking API documentation to learn more about banking data including guides and tutorials. You may also visit our Banking API page to learn more about integrations.
Commerce API
Please visit our Commerce API documentation to learn more about commerce data including guides and tutorials. You may also visit our Commerce API page to learn more about integrations.
Payroll API
Please visit our Payroll API documentation to learn more about payroll data including guides and tutorials. You may also visit our Payroll API page to learn more about integrations.
Definitions and Conventions
Tenancy
The terms account, tenant and 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.
Accounts are managed with a separate Administration API.
Domain
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 .ca or .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.
Dates
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.
Client-side
To embed client-side widgets within your own app or service see Link Page Element Widget under The Widgets.
Server-side
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.
Sandbox
Please visit our Sandbox section to learn more.
Authentication
The API is accessed via Basic Authentication over HTTPS, by using an API user and API key as the Auth user and password. You access your api at https://mycompany.myintranetapps.com/api/
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.
Connected accounts
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.
Errors
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.
Rate Limit
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.
Getting Started
The steps involved in successfully testing the API include:
Create a test company account and store its
Account IDConnect 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:
Support
To see a list of our API endpoints, you may visit our API reference. We also offer a Postman Collection to help you get started quickly.
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!
Pages Related To The API:
To view our API reference and endpoints, see api.bossinsights.com
Stuck or need more information? Reach out via our help center at bossinsights.com/support