Synchronizing Data

Synchronizing data ensures that our data is up-to-date with the accounting 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

Initial Data Synchronization

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

Railz synchronizes each data type in monthly, quarterly and yearly snapshots with the following date ranges (referred to as reportFrequency):

  • Monthly Snapshots: Synchronize all individual monthly reports since business inception date up to the last day of the previous month.
  • Quarterly Snapshots: Synchronize all individual quarterly reports since business inception date up to the last day of the previous quarter.
  • Yearly Snapshots: Synchronize all individual yearly reports since business inception date up to the last day of the previous year.

📘

Business inception date refers to the date a business started using the accounting service provider and not the actual incorporation date of the business.

As an example, if your connection was created on 2021-01-16 Railz will synchronize the following:

  • All monthly reports up to 2020-12-31.
  • All quarterly reports up to Q4 2020.
  • All yearly reports up to 2020.

🚧

Transactional data (e.g. bills, bank transactions, etc.) are synchronized in monthly snapshots including the current month, which could be a partial one.

Daily Data Synchronization

Railz synchronizes all accounting data every 24 hours from the initial synchronization/connection date.

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.

On-demand Data Synchronization Using the Railz API

Ther /data/sync POST 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.

{
    "businessName": "BIZ-d6b1c7d3-fe41-4447-ae72-3814b78b5142",
    "serviceName": "quickbooks",
    "dataType": "accounts"
}

❗️

QuickBooks Desktop

On-demand data synchronization is not available for 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.
  • If the last sync was within the last two hours.

"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

📘

Successful syncs will have a matching lastSuccessfulReportId and lastReportId

Data Sync Statuses

Each Railz data synchronization goes through the flow below.

  • 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 accounting service provider, or during a period of scheduled maintenance for the underlying connection.

Did this page help you?