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.
Each connection has a status that can be one of the following values:
|Authorization started but not completed by business (default status). No data will be available at this stage.|
|Authorization completed successfully by business and you should be able to retrieve its data.|
|The 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.|
|Connection 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.|
|Was never able to transition from pending to active based on credentials. No data will be available at this stage.|
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™.
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.
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.
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.
pendingconnections can be disconnected.
Each connection can have one of the following disconnect reasons:
|Disconnect Reason||Description||Applicable to|
|Account already connected to using another business name.||All integrations|
|Provided client identifier and secret are not production keys.||QuickBooks Online & Sage Business Cloud|
|Client 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|
|Refresh token expired, reconnection required, could not refresh credentials.||All integrations|
|Active credential is not found for service provider during pulling of data.||All integrations|
|The login details of this bank connection have needs to be reauthorized.||Plaid|
|The business has revoked its permission for your application to access its bank account.||Plaid|
|Unable to retrieve institution details when business user made connection via Railz Connect.||Plaid|
|Railz was not given the right permissions to fetch data.||All integrations|
|The connection was disconnected via the dashboard or API.||All except Plaid|
|Connection disabled due to business data redaction request when using Shopify.||Shopify|
Updated about 2 months ago