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 connectionUuid, which is generated by Railz when a business connects its service providers.
ConnectionId
'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:
| Status | Description |
|---|---|
pending | Authorization started but not completed by business (default status). No data will be available at this stage. |
active | Authorization is completed successfully by the business and you should be able to retrieve its data. |
disconnected | 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. |
expired | 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. |
invalid | Was 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
activeorpendingconnections can be disconnected.
Connection Disconnect Reasons
Each connection can have one of the following disconnect reasons:
| Disconnect Reason | Description | Applicable to |
|---|---|---|
duplicateAccount | Account already connected to using another business name. | All integrations |
unauthorizedClientIdKey | Provided client identifier and secret are not production keys. | QuickBooks Online & Sage Business Cloud |
unauthorizedCredentials | Client 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 |
expiredCredentials | Refresh token expired, reconnection was required and could not refresh the credentials. | All integrations |
credentialsNotFound | Active credential is not found for service provider during the pulling of data. | All integrations |
reauthorizationRequired | The login details of this bank connection need to be reauthorized. | Plaid |
authorizationRevoked | The business has revoked its permission for your application to access its bank account. | Plaid |
institutionNotFound | Unable to retrieve institution details when business user made connection via Railz Connect. | Plaid |
insufficientPermission | Railz was not given the right permissions to fetch data. | All integrations |
disconnectedByCustomer | The connection was disconnected via the dashboard or API. | All except Plaid |
disconnectedByBusinessDeletion | The business was deleted via the dashboard. | All Integrations |
disconnectedByRedaction | Connection disabled due to business data redaction request when using Shopify. | Shopify |
integrationKeyChanged | Connection disconnected by changing the integration API keys in the Railz dashboard. | All integrations |
Updated 2 months ago