Zenoti APIs FAQ
Answers to common questions about the Zenoti API platform, covering authentication, authorization, rate limits, pagination, error handling, webhooks, and common integration scenarios.
Authentication and authorization
- What is the difference between API key and access token authentication?
- How long does an API key last?
- How long does an access token last?
- What permissions do I need to generate an API key?
- What are API groups and how do they affect authorization?
Rate limits and performance
- What is the API rate limit?
- What happens when I exceed the rate limit?
- How can I monitor my rate limit usage?
Pagination
Error handling
Webhooks
- How do webhooks differ from polling the API?
- What happens when a webhook delivery fails?
- How do I recover a deactivated webhook?
Custom sources
General
- What base URL do I use for API calls?
- Can I create separate backend applications for different integrations?
- Where can I find the API changelog?
Authentication and authorization
What is the difference between API key and access token authentication?
API key authentication is designed for server-to-server integrations that need organization-wide data access. API keys do not expire for one year and provide unrestricted access scope. Include the API key in the header as Authorization: apikey {{api_key}}.
Access token authentication is designed for client-side applications that need role-based access control. Access tokens expire after 10 hours and respect the user's security role permissions. Include the access token in the header as Authorization: bearer {{access_token}}.
For most integrations, Zenoti recommends access tokens for tighter security control. See Set up API authentication.
How long does an API key last?
API keys are valid for one year from the date of generation. Plan to renew your API key before it expires to avoid service interruptions.
How long does an access token last?
Access tokens expire after 10 hours. Use the Refresh Token API to obtain a new access token without requiring the user to re-authenticate. See Use authentication token APIs.
What permissions do I need to generate an API key?
You need the following permissions enabled on your security role:
- Navigate to Configuration > Security > Security roles.
- Select your role and open Permissions.
- Expand Administrator settings.
- Enable Manage API Keys, Manage Apps, and Manage Automation.
What are API groups and how do they affect authorization?
API groups control which API endpoints a backend application can access. Zenoti uses a two-level authorization system: first it checks the user's security role permissions, then it checks the backend application's API group permissions. Both checks must pass for an API call to succeed. See Set up API authorization.
Rate limits and performance
What is the API rate limit?
Zenoti enforces a default rate limit of 60 API calls per minute per organization. This is a sliding window limit.
What happens when I exceed the rate limit?
When you exceed the rate limit, the API returns a 429 Too Many Requests response. Implement retry logic with exponential backoff and check the RateLimit-Reset response header to know when the limit resets. See Configure API rate limits.
How can I monitor my rate limit usage?
Check the following response headers on every API call:
RateLimit-Remaining-- Number of API calls remaining in the current window.RateLimit-Reset-- Seconds until the rate limit resets.Organization-RateLimit-Limit-- The total limit configuration.
Pagination
How does pagination work in Zenoti APIs?
All list endpoints accept page (default: 1) and size (default: 10) query parameters. Responses include a page_info object with total, page, and size fields. See Configure API pagination.
What is the maximum page size?
The maximum page size is 100 records per request. Requesting more than 100 returns a 422 validation error.
Error handling
What does a 503 error mean?
A 503 Service Unavailable response typically indicates an unexpected spike in API access traffic. The service usually restores within approximately 5 minutes. Implement retry logic for this error.
How do I handle authentication errors?
A 401 response indicates an expired or invalid credential. If using access tokens, refresh the token using the Refresh Token API. If using an API key, verify the key has not expired (one-year validity). See Configure API error handling.
Webhooks
How do webhooks differ from polling the API?
Webhooks push data to your application in real time when events occur in Zenoti. Polling requires your application to repeatedly call the API to check for changes, which consumes rate limit quota and introduces latency. Webhooks reduce API call frequency and provide near-instant notifications.
What happens when a webhook delivery fails?
Zenoti retries failed deliveries up to 5 times with exponential backoff (30 seconds minimum to 10 minutes maximum). If failures reach 20 consecutive failures, Zenoti automatically deactivates the webhook and sends a failure notification email. See Set up webhook integration.
How do I recover a deactivated webhook?
- Verify your destination URL is operational.
- Review the webhook failure logs for the cause.
- Fix the issues at your destination URL.
- Re-enable the webhook from the inactive webhooks tab.
Custom sources
What are custom sources?
Custom sources identify the origin of bookings created through API integrations. Zenoti supports four sources: Consumer Mobile App (External-CMA), Webstore (External-Webstore), Client App, and Bot. Source icons appear on appointment blocks and in reports.
How do I tag bookings with a custom source?
Zenoti automatically maps API calls to a source based on the backend application configuration. No additional parameters are needed in the booking API call. See Configure custom API sources.
General
What base URL do I use for API calls?
All Zenoti API requests use the base URL https://api.zenoti.com. Endpoints are versioned (for example, /v1/centers).
Can I create separate backend applications for different integrations?
Yes, and Zenoti recommends this approach. Create individual backend applications for individual use cases. A single application with global permissions creates debugging difficulties and security risks. Each application receives its own App ID, App Secret, and API Key.
Where can I find the API changelog?
The API changelog is available at the Zenoti developer documentation site. It lists changes organized by date, including new endpoints, parameter changes, and deprecated features. Check the changelog regularly to stay informed about API updates.