Syncing Data

Overview of how to sync & refresh data in Railz's API

Synchronizing data ensures that our data is up-to-date with the service provider and means you'll be able to retrieve the synchronized business data using our API or view the data in our Dashboard.

There are three ways for initiating data synchronization:

  1. Initial Data Synchronization
  2. Daily Data Synchronization
  3. On-demand Data Synchronization Using the Railz API

Data Sync Enum Values

The different synchronization enum values are the following: firstSync, fullSync, dailyCronSync,manualSync.

Initial Data Synchronization

By default, Railz will synchronize all supported data types on an initial and successful business connection.

Railz synchronizes each data type for up to 5 years in monthly, quarterly and yearly timeframes from the connection date (referred to asreportFrequency). All time frames are calendar based.

📘

Data Synchronization Example

Consider a connection that was created on 2023-01-31. Railz will retrieve data back to 2018-01-01.

Railz will synchronize financial statements based on the following:

  • All monthly timeframe reports from 2018-01-01 up to 2023-01-31.
  • All quarterly timeframe reports from Q1 2018 up to Q4 2022.
  • All yearly timeframe reports from 2018 up to 2022.

Continuing with the example above, if a non-financial statement data type (e.g. invoices) was synchronized on 2023-01-17, Railz will synchronize:

  • All monthly timeframe reports from 2018-01-01 up to 2023-01-17.

Daily Data Synchronization

Railz synchronizes all connections every 24 hours from the connection date and retrieves all new transactions since the previous sync.

For example, if you created a business connection on 2021-01-16 at 2:00 PM, the next scheduled synchronization would occur on 2021-01-17 at 2:00 PM and will retrieve all transactions modified or added since 2021-01-16.

🚧

Daily Data Synchronization for Banking Integrations

Data related to banking integrations will be synchronized based on alerts triggered by the banking service providers.

On-demand Data Synchronization Using the Railz API

The POST /data/sync endpoint in the Railz API can be used for queuing data synchronization. The data sync API will queue a dataset for the specified data type if that data type is supported by the business's connection.

{
	"connectionUuid":"CON-396d5daa-26b2-4979-89b6-cafb2c298155",
	"dataType": "accounts",
  "fullSync": false
}

❗️

On-demand Data Synchronization for On-premise Accounting Integrations

On-demand data synchronization is not available for on-premise accounting integrations such as QuickBooks Desktop.

❗️

On-demand Data Synchronization for Banking Integrations

On-demand data synchronization is not available for banking integrations such as Plaid.

🚧

Multiple Dataset Queued Conflict

You'll receive 409 Conflict response code:

  • If you try to queue a synchronization for a data type that is already in process.
  • If the latest automatic (initial or daily) sync for business hasn’t been completed.

"error": {"message": "Data Sync is already in progress", "statusCode": 409}

Monitoring Sync Status

When you pull data using the Railz API, you can check the last time each data type was synchronized using the GET /data/syncStatus endpoint.

The /data/syncStatus endpoint returns:

  • A full list of data types for your business with their current sync status: currentStatus.
  • The last time each data type was synced successfully: lastSuccessfulSync.
  • The last successful report: lastSuccessfulReportId
  • The last synchronized report: lastReportId
  • The initial sync time in seconds: syncTime

👍

Successful Syncs

Successful syncs will have a matching lastSuccessfulReportId and lastReportId

Data Sync Statuses

Each Railz data synchronization goes through the flow below.

StatusDescription
pendingData extraction is in progress. Accessing data for a specific data type will return a 204 response code at this time. All data synchronizations are created in the Pending (pending) state.
successData has been fetched, extracted and is ready through the API. Data sync webhook events will be triggered at this point.
emptyAn empty status indicates that Railz could not find any data for that specific period or data type.
failedA failed status indicated that Railz has encountered an exception during the data extraction process. This could be a result of the service no longer being authorized (will require the business to re-authorize the connection), connectivity issues, a sudden change of response format from the service provider, or during a period of scheduled maintenance for the underlying connection.