Connections

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:

StatusDescription
pendingAuthorization started but not completed by business (default status). No data will be available at this stage.
activeAuthorization completed successfully by 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.

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.

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, Token does not have valid tenants.All integrations
expiredCredentialsRefresh token expired, reconnection required, could not refresh credentials.All integrations
credentialsNotFoundActive credential is not found for service provider during pulling of data.All integrations
reauthorizationRequiredThe login details of this bank connection have needs 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
disconnectedByRedactionConnection disabled due to business data redaction request when using Shopify.Shopify

Did this page help you?