Multi Business

Multi Business and Business GUIDs

During the creation and provisioning of a Sage Business Cloud Accounting Business, a unique identifier is given to the business. The business GUID must be passed in each API request and ensures the request is destined for the correct business. In addition to correctly channeling requests the business_id acts as the DNA or building blocks for all 3rd party applications and integrations which hold or maintain a localized representation of the Sage Accounting data. It is imperative that the architecture allows stored or cached data to be identified and related by business id.

Not every user will have access to multiple businesses (multi business) but for those who do, it is important to provide and support functionality which allows the selection of the required business. At present, it is not possible to determine during authentication if the authenticated user has access to more than a single business.

To identify the businesses available to a user, a GET request to the businesses endpoint will return all businesses accessible to the authenticated user.

Lead Business

GET /businesses/lead

The lead business is defined as the first business the user created. It is unlikely but possible, that the lead business may change. Below are two scenarios which cause the lead business to change:

• The users first created business is deleted.
• The user was previously invited to a business or businesses and subsequently creates their own business.

See the section about the X-Business response header below for a way to mitigate this risk.

Businesses endpoint response

GET /businesses

{
  "$total": 3,
  "$page": 1,
  "$next": null,
  "$back": null,
  "$items_per_page": 2147483647,
  "$items": [
    {
      "displayed_as": "Business One",
      "id": "0d40342d0287cd6b13555c54afca6c90",
      "$path": "/businesses/0d40342d0287cd6b13555c54afca6c90"
    },
    {
      "displayed_as": "Business Two",
      "id": "49c196153fb1524b7d888cece84e8b12",
      "$path": "/businesses/49c196153fb1524b7d888cece84e8b12"
    },
    {
      "displayed_as": "Business Three",
      "id": "b88ee3a4ebb47c0c515d7ae56dc0bccf",
      "$path": "/businesses/b88ee3a4ebb47c0c515d7ae56dc0bccf"
    }
  ]
}

The response returns all businesses the user is authorized to access.

In the event of the authorized user having access to multiple businesses, the id of the user selected business should be passed as an X-Business header parameter for all future API requests made for the business. Should the user wish to swap between businesses the X-Business id should be changed to that of the newly selected business.

If the X-Business header parameter is not passed in a request, the API will return or post data for the lead business X-Business id. The lead business is defined as the first business the user created and can be identified via a GET businesses/lead request.

X-Business response header

In each API response (except on /businesses and /user), there is a X-Business header. Its value is the id of the business in which’s context the request has been made. You can use this to identify a lead business change: On the first request, store the value and check the stored value against the X-Business header in all subsequent responses. Our recommendation is to always send the X-Business header in the request; using the lead business feature is great for trying things out while developing against the API, but defining explicitly the business context to use is safer in production.