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. Queue a sync to refresh the data from within Codat's Portal
  2. Using the API to queue a data synchronisation (known as a dataset)
  3. Using the sync settings built into the Codat portal

By default, a full synchronisation of each data type marked as Fetch on first link in your data type settings will be queued automatically when a company first authorizes 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 authorized and will require the company to re-authorize 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.

960960

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

Refreshing data in the Codat Portal

  1. On the Companies page, find the company whose data you want to refresh.
  2. On the Company page, click Underlying data, then View datasets.
  3. On the Data History page, click Refresh data.
  4. You can toggle the Poll for Updates checkbox to view the progress of the refresh in real time.
  5. Once the refresh has been completed, you can view the latest data.

Use the Codat API to queue a synchronization 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, 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.

📘

Token expiry and connection de-authorization

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