News
Get the latest updates here!
Coming Soon -May 2026!
New Feature: Disconnecting a Client Connection for Partner apps
We are empowering our partners with greater control over their integrated applications. You can now programmatically disconnect a client's connection to your application directly via the API.
This feature is designed for situappsations where a client relationship has ended, such as:
- The client is no longer using your integrated solution.
- The client has stopped paying for your services.
- You are performing general application cleanup and wish to remove inactive connections.
By disconnecting a client, you ensure that you are no longer billed by Paychex for that inactive connection in the next billing month.
Critical Prerequisite: Client Consent
This action is powerful and has significant consequences for the client. Therefore, it can only be performed if the client has previously agreed to an updated version of our Terms of Use (ToU) that explicitly permits the partner to initiate a disconnection.
- For Existing Clients: You can only disconnect clients who have consented to the required ToU version (version Paychex Third Party Terms of Use Rev. 2.17.2026.pdf or newer).
- For New Clients: The Paychex authorization flow has been updated. When a new client connects to your application, they will be presented with the latest ToU of Paychex Third Party Terms of Use Rev. 2.17.2026.pdf or newer. They must accept these terms to complete the connection, ensuring you have the ability to disconnect them later if necessary.
New API Endpoint:
This action permanently removes a client's connection to your application. This is an irreversible action.
‘DELETE /management/removeclientaccess/{displayId}’
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| clientId | string | Required. The unique identifier (companyId) of the client you wish to disconnect. |
Responses
✅ Successful Disconnection
A successful request will return an HTTP 200 empty body response. This indicates that the client connection has been successfully and permanently removed.
Potential Errors
| Status Code | Description |
|---|---|
| 400 | Cannot disconnect a client who has not consented to partner disconnect terms. |
| 403 | Your application is not authorized to access the resource |
| 404 | The specified clientId does not exist or is not connected to your application. (TBD?) |
Impact of a Successful Disconnection:
When a client connection is successfully removed:
- Client Admin Notification: The next time an ADMIN user from the client company logs into Paychex Flex, they will receive an in-app message notifying them that your application has been disconnected by you (as the third party).
- Webhook Notification: Your application will receive a company.disconnected webhook event (CLT_ACCESS) containing the companyId of the disconnected client. Ensure your system is configured to listen for and process this event.
Frequently Asked Questions (FAQ):
Q: What if I try to disconnect a client who connected to my app a long time ago? A: If the client has not re-authorized since our Terms of Use were updated, the API call will fail with the 400 error shown above. The connection will remain active. You cannot force this action via the API.
Q: Will the client know that I was the one who initiated the disconnection? A: Yes. The in app notifications sent to the client will state that the connection to your specific application has been removed.
Q: What happens if the API call fails for any reason? Does the connection get partially removed? A: No. The disconnection process is atomic. If any part of the process fails (e.g., a prerequisite check is not met), the entire operation is rolled back. The client connection will remain fully intact as if no call was made.