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:
- Initial Data Synchronization
- Daily Data Synchronization
- 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 on2023-01-31
. Railz will retrieve data back to2018-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.
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
andlastReportId
Data Sync Statuses
Each Railz data synchronization goes through the flow below.
Status | Description |
---|---|
pending | Data 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. |
success | Data has been fetched, extracted and is ready through the API. Data sync webhook events will be triggered at this point. |
empty | An empty status indicates that Railz could not find any data for that specific period or data type. |
failed | A 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. |