Synchronizing Data

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

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 timeframes with the following date ranges (referred to asreportFrequency):

  • Monthly Timeframe: Synchronize all individual monthly reports from connection's first record date up to the last day of the previous month for financial statements or the current date for all other data types.
  • Quarterly Timeframe: Synchronize all individual quarterly reports from the connection's first record date up to the last day of the previous quarter for financial statements.
  • Yearly Snapshots: Synchronize all individual yearly reports from the connection's first record date up to the last day of the previous year for financial statements.

📘

Data Synchronization Example

Consider a connection that was created on 2021-01-16 and the first record date was on 2019-01-01. Railz will synchronize financial statements based on the following:

  • All monthly timeframe reports from 2019-01-01 up to 2020-12-31.
  • All quarterly timeframe reports from Q1 2019 up to Q4 2020.
  • All yearly timeframe reports from 2019 up to 2020.

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

  • All monthly timeframe reports from 2019-01-01 up to 2021-08-15.

Daily Data Synchronization

Railz synchronizes all connections 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.

🚧

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

Ther 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.

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

❗️

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

Read Next

Before data can be retrieved or pushed using Railz, you will need to create a new connection and wait for a successful data synchronization.

Did this page help you?