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 to the Webhook URL you specify containing the result of an operation.

Webhooks support HTTP Basic Authentication to authorize access to your Webhook endpoint.

When configuring a webhook you may limit which events trigger a call to your endpoint by selecting only the events you are interested in receiving.

Filter for Webhook event selection

A webhook request will be retried 3 times before failing. Your endpoint needs to return a 200 status code for the webhook payload to be considered successfully delivered

The webhook data format is sent in JSON, for example:

{
  "event" : "document_conversion_complete",  
  "requestId" : "6ba7b814-9dad-11d1-80b4-00c04fd430c8", 
  "domain" : "example.myintranetapps.com", 
  "message" : "Document #59 conversion completed",
  "data" : {
    "docId": 59
  }
}
JSON

Common data elements are:

field

format

description

event

string

the type of webhook event that is being triggered

requestId`

string

system generated request identifier

domain

string

the domain for the account where the event is being triggered

message

string

short event explaination

data

object

event specific data