Debt Recovery Agency Integration
This article explains how to configure the Debt Recovery integration in Zenoti, which allows a third-party debt recovery agency to claim and pursue suspended memberships on your organization's behalf.
Audience: Organization administrators who manage integrations and membership collections.
Before you begin
- This configuration is organization-level and applies to all centers in your organization.
- You must have EDIT permission on the target organization to save or rotate the Debt Recovery configuration. If you do not have this permission, Zenoti displays the message: "Please contact your account owner to configure this integration."
- Identify the agency name and short code with your debt recovery agency contact before starting.
- Decide in advance whether claimed memberships should be eligible for release or reinstatement after a claim is resolved. This setting cannot be changed per-membership after it is configured.
Permission: You need EDIT access to the target organization to save configuration or generate and rotate API keys. Non-authorized users see a support message directing them to contact their account owner.
Steps
Open the Debt Recovery Configuration page
- In Zenoti, navigate to Configuration > Integrations > Integration settings.
- Locate and expand the Debt Recovery accordion.
Enable the integration
Turn on the Enable Debt Recovery toggle.
When this toggle is off, all agency-specific fields are hidden. The fields appear only after you enable it.
Configure agency details
Configure the following fields:
- Agency Name β Enter the name of the debt recovery agency. Maximum 200 characters. Defaults to "Aldous" if left unchanged. This field is required; an inline error appears if it is empty.
- Short Code β Enter a unique short identifier for the agency. Must be 1β50 characters with no spaces. An inline error appears if the value is empty or contains spaces.
- Cancellation Reason β Select the cancellation reason to associate with debt recovery operations. This reason is recorded when the agency cancels a membership.
- Custom Payment Method β Select the custom payment method to associate with debt recovery transactions.
Set the membership reinstatement behavior:
- Allow claimed memberships to be released or reinstated β Turn this toggle on to allow memberships that were claimed by the agency to be released or reinstated after a claim is resolved. When this toggle is off, any membership ever claimed by the agency is permanently blocked from suspension release or reinstatement, even after the claim is resolved.
Generate an API key
Important: The API key is displayed exactly once immediately after generation. Copy and store it securely before closing or navigating away. The key cannot be retrieved again after the dialog closes.
Click Generate Key to generate an API key for the agency.
Zenoti generates the key and displays it in full. A warning confirms: "This key will only be shown once. Copy and store it securely β it cannot be retrieved again."
Click Copy API key to copy the key to your clipboard. Confirm the display shows Copied! before closing the dialog.
Share the key with your debt recovery agency through a secure channel.
After a key has been generated, the page shows the current status as API key configured. If no key has ever been generated, the status shows No API key generated yet. The key value is never displayed again on the page.
Save the configuration
- Click Save to save all configuration settings.
Rotate an API key
If your agency's API key is compromised or you need to issue a new one, you can rotate it. Rotating the key immediately invalidates the previously issued key β the agency will lose access until you provide the new key.
Important: Rotating the API key immediately revokes the existing key. Coordinate with your debt recovery agency before rotating to avoid service interruption.
- On the Debt Recovery Configuration page, click Rotate Key.
- Review the confirmation prompt and confirm that you want to proceed.
- Zenoti generates a new key and displays it exactly once. Follow the same steps as the initial generation to copy and store it securely.
- Provide the new key to your debt recovery agency.
Tips
- Test before go-live. Before providing the API key to your agency, confirm your cancellation reason and custom payment method are correctly configured by reviewing a test membership claim scenario with your agency contact.
- Coordinate key rotation. Always notify your debt recovery agency before rotating the API key so they can update their system immediately. The old key is invalidated the moment you confirm the rotation β there is no grace period.
- Reinstatement policy is permanent per membership. The Allow claimed memberships to be released or reinstated setting controls behavior for all memberships ever claimed. Consider your business policy carefully before turning this toggle off, as there is no per-membership override.
Troubleshooting
| Problem | Likely cause | Resolution |
|---|---|---|
| Agency-specific fields are not visible on the page | The Enable Debt Recovery toggle is off | Turn on the Enable Debt Recovery toggle. Fields appear only when the integration is enabled. |
| Cannot save configuration; seeing "Please contact your account owner" | Your account does not have EDIT access to the organization | Contact your organization's account owner to request the necessary permission. |
| Short Code field shows an inline error | The value is empty, exceeds 50 characters, or contains spaces | Enter a value of 1β50 characters with no spaces. |
| API key was not copied before closing the dialog | The key is no longer accessible | Rotate the key using Rotate Key, then copy and store the new key immediately. |
| Agency reports access issues after configuration was saved | An API key has not been generated yet, or the existing key was rotated without updating the agency | Confirm the status shows API key configured. If you recently rotated the key, provide the new key to your agency. |