The BBS API enables read only access for external applications to access data within BBS Accounting via HTTPS (secure) web requests.

The API is a limited REST style API, allowing access to collection and singleton resources, accepts parameters on the URI, and returns responses in JSON format.

Please refer to the sections below, and the BBS API Reference for further details.

Each company file in BBS Accounting has a unique base API endpoint. This endpoint is visible for a company in the API User/Permission Maintenance screen.

https://abctra.users.bbserp.com.au:9001/api/

A version number should then follow the base URI. Currently, the latest version is v1.

https://abctra.users.bbserp.com.au:9001/api/v1/

The resource name should then follow the version on the base URI.

https://abctra.users.bbserp.com.au:9001/api/v1/customers/

If a singleton resource is required, the 'Code' of this resource should follow the resource name. If a singleton resource is not specified, a collection will be returned.

https://abctra.users.bbserp.com.au:9001/api/v1/customers/ABC001

Parameters can be added after the resource name to filter the data being returned. The parameters available for each resource can be found in the BBS API Reference topic.  

https://abctra.users.bbserp.com.au:9001/api/v1/customers?includeprospects=false

If a collection resource name or singleton resource name provided is invalid, or the parameters provided return no results, a HTTP error 404 Not Found response will be returned.

Authentication is required to access the BBS API.

API Users can be created, and their access managed, through API User/Permission Maintenance in BBS Accounting.

When an API User is created in API User/Permission Maintenance, an API Key in the format username:secret will be displayed to be provided to the party consuming the API. If this API Key is lost, it cannot be retrieved and a new API Key will need to be generated in API User/Permission Maintenance.

Please refer to Creating BBS API Users and API User/Permission Maintenance for further information regarding creating API Users and regenerating API Keys.

The API Key must be provided in the HTTP request header X-BBSAPIKey (eg. X-BBSAPIKey: apiusername:apisecret).

If an API Key is not provided, or the API Key provided is invalid, a HTTP error 401 Unauthorized response will be returned.

Permissions and settings for each API resource can be set for each API user in API User/Permission Maintenance.

Permissions and settings for each resource vary.

Please refer to API User/Permission Maintenance for further information regarding managing API permissions and settings.

Each collection resource supports the following standard parameters.

All API responses are returned in JSON format.

Each resource allows for four different response formats controlled by the format parameter which can be specified on the URI

https://abctra.users.bbserp.com.au:9001/api/v1/customers?includeprospects=false&format=detail
 

•Basic - A response showing the most common fields for the resource.

•Standard (default if format= is not specified) - A response showing all available fields for the resource, but no sub-resources (eg all fields for a customer, but not their delivery addresses, alerts, document destinations etc).

•Detail - A response showing all available fields for the resource, and all available fields for all sub-resources (eg all fields for a customer, plus their delivery addresses, alerts, document destinations etc).

•Expanded - The same as the Detail format, but with all key/value pair elements (eg Sales Rep) broken out into objects containing the elements 'Code' and 'DisplayAs' separately (eg)

For each API resource, each API user can be set to a maximum format level in API User/Permission Maintenance, or to No Access if the user shouldn't have access to the collection. Where a user is granted access to a format level, they will have access to any lower format levels as well (eg where an API User set to Standard level access to a resource, they will have access to both the Basic and Standard formats, but not the Detail or Expanded formats).

API requests for collection resources are limited to a maximum of 1000 results in a response. This can be lowered if required using the limit parameter on the URI.

https://abctra.users.bbserp.com.au:9001/api/v1/customers?includeprospects=false&format=detail&limit=200

The offset parameter can be used to retrieve the next set of records after the initial request. This parameter specifies the number of records to skip before starting to return results. For example, to get the next 200 records after the first set, set offset=200 along with limit=200.

https://abctra.users.bbserp.com.au:9001/api/v1/customers?includeprospects=false&format=detail&limit=200&offset=200

Pagination links are included in responses where additional pages of data are available. When applicable, each response contains a "links" array with URIs for the next and previous pages of results.

BBS API Users can be created in API User/Permission Maintenance.

1.Enter a username for the API user. This must be unique for each API user and is not case sensitive.

 

2.Enter a description for the API user and set the user's permissions for the API

 

3.Once complete, click Save and the users API Key will be generated and displayed. This, along with the API Endpoint displayed at the bottom of the screen, must be provided to the API user for them to be able to access the API.