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 connectionUuid, which is generated by Railz when a business connects its service providers.



'connectionId' will be returned in the response but will be soon be deprecated as we move to identifying business connections by a 'connectionUuid'.

Connection Statuses

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

pendingAuthorization started but not completed by business (default status). No data will be available at this stage.
activeAuthorization is completed successfully by the business and you should be able to retrieve its data.
disconnectedThe connection was disconnected via the dashboard, API or based on service provider webhooks. 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.
expiredConnection failed when attempting to get data from a previously valid credential. 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.
invalidWas never able to transition from pending to active based on credentials. No data will be available at this stage.


Accounting Connection Limitations

A business can only have one unique active accounting connection.

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 specific 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 webhooks page in the Railz Dashboard™.

First Record Date

For each connection created, Railz will populate the firstRecordDate which corresponds to the date of the oldest transaction fetched by Railz, by default up to 5 years from the connection date.

Preventing Duplicate Accounting Connections

When a business links its accounting service provider account through Railz, a new connection is created. Two connections created for the same set of credentials (account) at the same 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 the dashboard or using the PUT /connections/disconnect endpoint and providing the connectionUuid 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.


Disconnect Connection Status Dependencies

Only active or pending connections can be disconnected.

Connection Disconnect Reasons

Each connection can have one of the following disconnect reasons:

Disconnect ReasonDescriptionApplicable to
duplicateAccountAccount already connected to using another business name.All integrations
unauthorizedClientIdKeyProvided client identifier and secret are not production keys.QuickBooks Online & Sage Business Cloud
unauthorizedCredentialsClient ID and Secret are not authorized, Token does not have a valid grant, Token is not authorized and Token does not have valid tenants.All integrations
expiredCredentialsRefresh token expired, reconnection was required and could not refresh the credentials.All integrations
credentialsNotFoundActive credential is not found for service provider during the pulling of data.All integrations
reauthorizationRequiredThe login details of this bank connection need to be reauthorized.Plaid
authorizationRevokedThe business has revoked its permission for your application to access its bank account.Plaid
institutionNotFoundUnable to retrieve institution details when business user made connection via Railz Connect.Plaid
insufficientPermissionRailz was not given the right permissions to fetch data.All integrations
disconnectedByCustomerThe connection was disconnected via the dashboard or API.All except Plaid
disconnectedByBusinessDeletionThe business was deleted via the dashboard.All Integrations
disconnectedByRedactionConnection disabled due to business data redaction request when using Shopify.Shopify
integrationKeyChangedConnection disconnected by changing the integration API keys in the Railz dashboard.All integrations

Read Next

Learn more about the integrations and types of data Railz supports.