At Railz, a connection refers to a business connection to a service provider authorized by the business (e.g. an accounting service provider) allowing you to sync data from and to that service provider.

Connections are uniquely identified by their connection ID, denoted by connectionId, which is generated by Railz when a business connects its service providers.


Accounting Connection Limitations

A business can only have one unique active accounting connection.

Connection Statuses

Each connection has a status that can be one of the following values:

  • pending: New connections are created in this state; this corresponds to businesses that have not yet connected to a service provider and, therefore, you won't be able to sync any data yet.
  • active: The business has connected to a service provider and you should be able to retrieve its data.
  • expired: The business was connected to a service provider, but Railz has been told that the connection is no longer authorized. You will still be able to access any data that was already synchronized, but you won't be able to retrieve any new data until the business completes the authorization process again.
  • disconnected: Unlinked; similar to expired in that you can access data already synchronized but not retrieve new data.
  • invalid: The connection was quickly marked as invalid after connecting due to one of the following reasons: invalid integrations settings in the Dashboard, business attempting connecting through a non-admin login, or business has an expired license with the service provider.

Connection Monitoring

Webhook events help you monitor changes in the connection status or data syncs of a business. Railz provides a set of webhooks that you can use to be notified about certain events, such as:

  • A new connection was created
  • A connection authentication was completed
  • A connection has finished synchronizing data from or to the service provider
  • A connection was disconnected

You can subscribe to these webhook events either through the Railz Dashboard™.

First Record Date

For each connection created, Railz will populate the firstRecordDate which corresponds to the date of the first transaction posted by the business in the accounting service provider. Railz calculates the firstRecordDate if it was not provided by the service provider.

Preventing Duplicate Accounting Connections

When a user links their accounting service provider account through Railz, a new connection is created. Two connections created for the same set of credentials (account) at the same accounting service provider will be considered a duplicate and will result in the most recent one being invalidated. Preventing a user from accidentally linking a connection they have already linked can help avoid confusing behaviour in your application and will also prevent you from potentially being billed for both connections.

Disconnecting a Connection

If you'd like to revoke your access to a connection, you can disconnect it from the manage services menu on dashboard or using the PUT /connections/disconnect endpoint and providing the connectionId in the request body.

Once a connection is disconnected, you will be able to access any data that was already synchronized, but you won't be able to perform any new data syncs until the business completes the authorization process again.


Only active or pending connections can be disconnected.

Did this page help you?