By default the Data API is in read-only mode, to enable write back please request the feature be enabled on your account.

Ensure you are familiar with the general concepts of our API first before using the write capability.

The ability to write data to the Common Data Model (CDM) enables a number of common use cases such as:

  • Augmenting the datasets available to Boss Insights to derive new metrics, insights and ratios

  • Push data to end users software systems to:

    • Accounting

      • Create or update an invoice

      • Log an expense against a new or existing Vendor

      • Alter the chart of accounts

    • Commerce

      • Update customer contact details

      • Mark an invoice as paid

    • Banking

      • Preload banking transaction data to reconcile with Accounting data

Push To Source

By default API updates will update the CDM only, to have those updates flow through to any connected end-user software applications you need to set the X-Sync-Data header to a value of push

Data Flow

When you post data via the API it is synchronously written to the CDM and you receive an immediate response indicating whether the data was successfully updated or if a validation error has occurred.

If the X-Sync-Data header has been set to a value of push then an asynchronous task will push data to any underlying source application the end-user has connected. A response header of X-Sync-ID will be returned which allows you to track the status of this async operation, this same ID will be included in any webhooks. By default the data will be pushed to any connected system which can receive data updates of that particular object e.g. If the end-user has connected both their CRM and Accounting software then when creating a new Customer it will be pushed to both systems - you can limit this by setting the X-Sync-Sources header to a comma separated list of allowed applications (e.g. quickbooks ) or application types (e.g. accounting)

The API key that you use to make API calls must have api.write scope enabled, this is set when you create the API key

Tracking ID

You can provide your own custom tracking ID in a X-Tracking-ID header when making calls to the API which will then be reflected back to you in any API responses and webhooks, this is particularly useful to identify which request resulted in a given webhook call.

Webhooks

Webhooks are initially configured in the Portal Administration within the developers subsection. When a specific event occurs such as API Push Update your application will receive a POST request containing the result of an operation.