Disconnect an Entire Connection
Calling the/disconnect endpoint will disconnect all entities associated with the connection tied to the provided access token. Once disconnected, the connection is permanently terminated and the access token is revoked.
Use this when you intend to stop syncing data for an employer entirely.
Disconnect Specific Entities
If a connection includes multiple entities, you can remove specific entities without affecting the rest of the connection by calling/disconnect-entity with the entity_ids you want to remove in the request body. All other entities remain active and the access token stays valid.
Use this when an employer connected an entity by mistake, or when your application needs to stop syncing a particular entity while continuing to operate normally for others under the same connection.
An account.updated webhook will fire for each disconnected entity. If you disconnect multiple entities in one call, you’ll receive a separate webhook per entity.
Choosing Between /disconnect and /disconnect-entity
/disconnect | /disconnect-entity | |
|---|---|---|
| Scope | Disconnects the entire connection and all entities | Disconnects only the specified entities; others remain active |
| Required input | Access token only | Access token + entity_ids |
| Reversibility | If you disconnect an entity you did not intend to, a new connect session must be created | If you disconnect an entity you did not intend to, a re-auth session can be used to add the entity(s) back to the connection |
| Employer impact | The employer will then need to establish a new connection and select the desired entities in Finch Connect | Employer re-authenticates to add the entity back to the existing connection in Finch Connect |
Best Practices
Before You Disconnect
Choose the right endpoint. Use/disconnect to fully offboard an employer. Use /disconnect-entity to remove specific entities from a multi-entity connection while preserving the rest.
Disconnect before deleting tokens. /disconnect requires the access token. Always call it before you discard the token from your system.
Understanding Disconnect Behavior
Billing. Billing is based on uniqueconnection_ids — simply ceasing API calls does not stop billing. Only /disconnect removes a connection from billing. (/disconnect-entity does not, unless you remove every entity, but /disconnect is simpler if that’s your intent.)
No reconnect endpoint. Once a connection is fully disconnected via /disconnect, it cannot be reactivated. The employer must go through Finch Connect again, creating a new connection_id and a new billable connection.
Only disconnect when you mean it. A connection in reauth status is not a disconnect — prompt the employer to reauthenticate instead. Only call /disconnect or /disconnect-entity when you’re confident you no longer need the data. If you do disconnect an entity by mistake, the employer can re-add it via a reauth session. (Note: reauth lets employers add entities but not remove them — removal requires /disconnect-entity.)
Update your database after a successful /disconnect-entity call. When you receive a 200 response from /disconnect-entity, remove the corresponding entity_id(s) from your database. If you retain disconnected entity_id(s) and continue making data requests with them, those requests will fail with an invalid entity_id error.
Updated entity arrays in API responses. After disconnecting one or more entities, any subsequent call to /auth-token performed during re-authentication will only return the entities that are still actively connected. Disconnected entities will no longer appear in the response. If you need the historical context of every entity that was every linked to a connection, use the /introspect endpoint. This will return both actively connected and disconnected entities.
Viewing disconnected entities via /introspect. You can always use the introspect endpoint to see a full history of entities that have ever been associated with a connection — including those that have since been disconnected. Each entity in the entities object will include an individual status field indicating its current status.
Checkpoint + Next Step
After completing this step, you should understand when to use
/disconnect vs. /disconnect-entity and what happens to connections and entities in each case. Your application should give customers the ability to disconnect their connection (or specific entities), calling the appropriate Finch endpoint from your backend.
Next, learn how to control user access. 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 by the correct customer account.