Synchronising a company's data

Synchronising a data type ensures that our data cache is up-to-date with the data source and means you'll be able to retrieve the synchronised company's data using our API or view the data in our portal.

There are three mechanisms for initiating the synchronisation of data:

  1. Using the API to queue a data synchronisation (known as a dataset)
  2. Using the sync settings built into the Codat portal
  3. Companies can initiate a synchronisation themselves from an on-premises connector (Sage 50 or QuickBooks Desktop)

By default, a full synchronisation of each data type marked as Fetch on first link in your sync settings will be queued automatically when a company first authorises itself with Codat.

Dataset statuses

All datasets are created in the Queued state. For online packages, the transition to Fetching will be near instant but for offline packages, the synchronisation will remain Queued until the on-premises connector on the end user's machine is online and ready to process the dataset.

A dataset going to the AuthError state indicates that the connection to the data source is no longer authorised and will require the company to re-authorise your connection before you're able to complete subsequent data synchronisations for that connection.

Other error states may be resolved by queueing a new synchronisation after waiting some time. For example, you may see datasets go to FetchError if you attempt a synchronisation during a period of scheduled maintenance for the underlying data source.

Datasets can also transition to the NotSupported state if the dataset you are trying to sync is not supported by the linked platform.

Dataset statuses from Queued through to Complete. 
Click to expand.Dataset statuses from Queued through to Complete. 
Click to expand.

Dataset statuses from Queued through to Complete.
Click to expand.

Use the Codat API to queue a synchronisation of data

There are two POST endpoints in the API for queuing a synchronisation of data:

  1. /companies/{companyId}/data/queue/{dataType}
    • Will queue a dataset for the specified data type
    • dataType is the key of the data type e.g. invoices
  2. /companies/{companyId}/data/all
    • Will queue a dataset for each of the data types marked as Fetch on first link in your sync settings, where that data type is supported by the company's linked data connections

📘

Multiple dataset queued exception

If you try to queue a synchronisation for a data type that is already in process, you'll receive an exception.

"error": "DatasetAlreadyInProgressException: Cannot queue {dataType} sync for {companyId} as previous sync {dataSetId} is still in progress"

Use the sync settings built into the Codat portal

The "sync settings" page in the Codat portal allows users to set a default synchronisation frequency for each data type to ensure your customers' data is kept up-to-date. The available options are hourly (only available in production), daily, weekly and monthly.

If you require a more specific schedule, you should use the API directly (as described above).

For more information on configuring your sync settings, please see Configure sync settings.

Initiate a synchronisation from an on-premises connector

Users of our Sage 50 Connector or QuickBooks Desktop Connector can trigger a data synchronisation by clicking the "Perform Sync" action from within the connector. This will queue a dataset for each of the data types marked as Fetch on first link in your sync settings, where that data type is supported by the connector.

📘

Token expiry and connection de-authorisation

For some accounting platforms, if you don’t synchronise the data of a company for a significant time period (between 60 and 100 days) authorisation is revoked. In this case, provide your customer with the linkURL for their company so that they can renew your access to their data.


Did this page help you?