Overview

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.

For a complete list of API endpoints see our API Reference

Download our Postman Collection to speed your development

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.

Getting Started

The steps involved in successfully testing the API include:

  1. Create a test company account and store its Account ID

  2. Connect an app in the newly created company account

  3. 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:

Sample Integration Flow

Stuck or need more information? reach out via our help center at bossinsights.com/support

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

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.

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.

Client-side

To embed client-side widgets within your own app or service see Embedded documentation.

Security

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.

Support

If you get stuck or need more information reach out via our help center to create a support ticket. We also have Portal Documentation available.