Skip to main content
A connection exists once an access token is obtained and stored securely. Once a connection is no longer needed or requested to be deleted by the customer, calling the /disconnect endpoint will disconnect all associated access tokens for that particular connection. It is important to know how Finch defines a connection to understand what happens when a connection is disconnected. If an employer has multiple entities (for example, separate legal entities or payroll groups) within their company, they may connect one or more of those entities in a single connection. Disconnection is performed by access token. If that connection includes multiple entities, all of those entities are disconnected when the connection is disconnected.

​
Best Practices

To ensure correct usage of the /disconnect endpoint and accurate billing, keep the following best practices in mind:
  1. Billing and Connection Tracking
    Billing is based on the number of unique connection_ids in your system. If you no longer wish to be billed for a connection, you must explicitly call the /disconnect endpoint for that connection. Simply ceasing to make API calls does not stop billing.
  2. Disconnect Before Disposing of Access Tokens
    The /disconnect endpoint requires the access_token associated with the connection. Be sure to call /disconnect before deleting, expiring, or discarding the access token from your system.
  3. No “Reconnect” Endpoint
    There is no /reconnect endpoint. Once a connection is disconnected, it cannot be reactivated. To re-establish data access, the employer must go through the Finch Connect flow again to create a new connection. The new connection will have a new connection_id and count as a new billable connection.
  4. Disconnect Only When You Intend to Stop Syncing Data
    Call /disconnect only when you permanently intend to stop syncing data for a company. If you expect to restore authentication later (for example, to reauthenticate an employer), do not disconnect. You should prompt the employer to go through a reauthentication session instead of disconnect.
  5. Understanding “Reauth” vs. “Disconnect”
    A connection in reauth status means Finch can no longer successfully authenticate with the provider. This does not equal or trigger a disconnect. You should not disconnect a connection in reauth status unless you no longer plan to sync data for that company.

​
Checkpoint + Next Step

After completing this step, you should know what will happen to a connection if an access token is disconnected. Your application should give your customers the ability to disconnect their connection, which subsequently calls the Finch Disconnect endpoint from the backend. By storing tokens securely and disconnecting connections when necessary, your application is more secure. If you plan on presenting the data back to the employer via a User Interface, it is crucial to control user access properly to ensure employment data is only viewable to the correct customer account.

​
Learn more