Skip to main content

Refresh company data

Overview of queuing a data refresh in Codat's API

Minimal data sync frequency

You should refresh at least one data type monthly to ensure your connectionConnection A link between a Codat company and a data source (like an accounting platform). Each connection represents authorized access to pull or push data from that platform. token does not expire when not actively synchronising data, unless only a one-time syncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. is required.

Check data 'freshness'​

Use the GET /companies/{companyId}/dataStatus endpoint to check the last time each data type was synchronized.

In this request, companyId is the unique ID that you have received in a response to creating this company.

When you’re reading data for the first time, use this endpoint to check if the syncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. was successful.

GET /companies/{companyId}/dataStatus

Response for a successful first sync
{
  "suppliers": {
    "dataType": "suppliers",
    "lastSuccessfulSync": "2019-06-11T13:26:54.6884704Z",
    "currentStatus": "Complete",
    "latestSyncId": "31632c48-23dc-4cb1-b3ff-0829343c8e85",
    "latestSuccessfulSyncId": "31632c48-23dc-4cb1-b3ff-0829343c8e85"
  },
  ...
}
Response for an unsuccessful first sync
{
  "suppliers": {
    "dataType": "suppliers”
    "currentStatus": "FetchError",
    "latestSyncId": "31632c48-23dc-4cb1-b3ff-0829343c8e85",
  },
  ...
}

Refresh data​

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

  1. /companies/{companyId}/data/all
    • Will queue a dataset for each of the data types marked as Fetch on first linkLink The authorization flow that allows end users to connect their accounting, banking, or commerce platforms to your application via Codat. in your data type settings, where that data type is supported by the companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources.'s linked data connectionsConnection A link between a Codat company and a data source (like an accounting platform). Each connection represents authorized access to pull or push data from that platform.
  2. /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
Multiple dataset queued exception

If you try to queue a synchronization 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"

Refreshing data can take different amounts of time depending on the integration and the amount of data being retrieved. You can use webhooks to be updated when the operation completes.

Records deleted between syncsSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule.​

For our accounting source data types, Codat stores records deleted by a companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. in the underlying accounting software between successive data syncsSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. to ensure better consistency in the data. If such records are not relevant for your use case, you can exclude them by querying on the metadata.isDeleted!=true flag.

Records that were created and deleted by a companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. before the first syncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. took place will never be read and stored by Codat.

Scheduled refresh​

Codat can also refresh data at a set schedule, based on the set 'SyncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. frequency' for each data type.

SyncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. frequency​

The recommended syncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. frequency is weekly. It provides you with recent enough data while catering for data types that do not change often and decreasing the number of APIAPI A set of rules and protocols that allows different software applications to communicate with each other. Codat provides APIs for accessing financial data from accounting, banking, and commerce platforms. calls required.

Some data types like companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources., tax rates and charts of accounts will rarely change (monthly if at all), but are so small to syncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. they have no performance impact.

However, you can set a more frequent syncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. schedule if it is required for your use case.

  • Monthly: We recommend that you syncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. at least one data type monthly (e.g. CompanyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. info) to ensure connectionConnection A link between a Codat company and a data source (like an accounting platform). Each connection represents authorized access to pull or push data from that platform. token does not expire when not actively synchronizing data (unless only a one-time syncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. is required).
  • Weekly (recommended): Keeps data reasonably fresh, particularly where data types change less frequently, while also reducing the number of required APIAPI A set of rules and protocols that allows different software applications to communicate with each other. Codat provides APIs for accessing financial data from accounting, banking, and commerce platforms. calls.
  • Daily: Gives you close-to-live picture of most data types while staying within the conservative rate limits of most accounting software.
  • Hourly: Recommended for specific use cases only and may require consideration for the rate limits, e.g. invoices and payments for invoice financing.

💡 Tips and traps​

  • Ensure to perform a monthly syncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. for at least one data type to keep your connectionConnection A link between a Codat company and a data source (like an accounting platform). Each connection represents authorized access to pull or push data from that platform. token operational if you are not performing active synchronization. You can disregard this if you only require a one-time syncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule..

  • If you are building your own reports or accessing Codat-generated ones that rely on multiple data types, fetch all required data types before you generate the report. Otherwise, there may be inconsistencies in the data freshness. You can check for possible inconsistencies using the data types' lastSuccessfulSync properties.

    For example, if you calculate a companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources.'s accounts receivable (AR) position using invoices, credit notes, payments, account transactions, and customers with lastSuccessfulSync dates of 2023-07-10, and compare it to the AR position on the balance sheet with the lastSuccessfulSync of 2023-07-11, the results are likely to differ.

  • For most data types, we retrieve all available history. For financial statement data types (balanceSheet, profitAndLoss, cashFlowStatement), we retrieve 24 months of history. These default settings can be overridden via our APIAPI A set of rules and protocols that allows different software applications to communicate with each other. Codat provides APIs for accessing financial data from accounting, banking, and commerce platforms. using advanced sync settings.

Was this page useful?
👏
👍
🤔
👎
😭

Contents

Suggest edits