build-zoom-rest-api-app

# /build-zoom-rest-api-app Background reference for deterministic server-side Zoom automation and resource management. Prefer `plan-zoom-product`, `plan-zoom-integration`, or `debug-zoom` first, then route here for endpoint-level detail. # Zoom REST API Expert guidance for building server-side integrations with the Zoom REST API. This API provides 600+ endpoints for managing meetings, users, webinars, recordings, reports, and all Zoom platform resources programmatically. **Official Documentation**: https://developers.zoom.us/api-hub/ **API Hub Reference**: https://developers.zoom.us/api-hub/meetings/ **OpenAPI Inventories**: `https://developers.zoom.us/api-hub/<domain>/methods/endpoints.json` ## Quick Links **New to Zoom REST API? Follow this path:** 1. **[API Architecture](concepts/api-architecture.md)** - Base URLs, regional URLs, `me` keyword, ID vs UUID, time formats 2. **[Authentication Flows](concepts/authentication-flows.md)** - OAuth setup (S2S, User, PKCE, Device Code) 3. **[Meeting URLs vs Meeting SDK](concepts/meeting-urls-and-sdk-joining.md)** - Stop mixing `join_url` with Meeting SDK 3. **[Meeting Lifecycle](examples/meeting-lifecycle.md)** - Create → Update → Start → End → Delete with webhooks 4. **[Rate Limiting Strategy](concepts/rate-limiting-strategy.md)** - Plan tiers, per-user limits, retry patterns **Reference:** - **[Meetings](references/meetings.md)** - Meeting CRUD, types, settings - **[Users](references/users.md)** - User provisioning and management - **[Recordings](references/recordings.md)** - Cloud recording access and download - **[AI Services](references/ai-services.md)** - Scribe endpoint inventory and current AI Services path surface - **[GraphQL Queries](examples/graphql-queries.md)** - Alternative query API (beta) - **Integrated Index** - see the section below in this file Most domain files under `references/` are aligned to the official API Hub `endpoints.json` inventories. Treat those files as the local source of truth for method/path discovery. **Having issues?** - Start with preflight checks → [5-Minute Runbook](RUNBOOK.md) - 401 Unauthorized → [Authentication Flows](concepts/authentication-flows.md) (check token expiry, scopes) - 429 Too Many Requests → [Rate Limiting Strategy](concepts/rate-limiting-strategy.md) - Error codes → [Common Errors](troubleshooting/common-errors.md) - Pagination confusion → [Common Issues](troubleshooting/common-issues.md) - Webhooks not arriving → [Webhook Server](examples/webhook-server.md) - Forum-derived FAQs → [Forum Top Questions](troubleshooting/forum-top-questions.md) - Token/scope failures → [Token + Scope Playbook](troubleshooting/token-scope-playbook.md) **Building event-driven integrations?** - [Webhook Server](examples/webhook-server.md) - Express.js server with CRC validation - [Recording Pipeline](examples/recording-pipeline.md) - Auto-download via webhook events ## Quick Start ### Get an Access Token (Server-to-Server OAuth) ```bash curl -X POST "https://zoom.us/oauth/token" \ -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=account_credentials&account_id=ACCOUNT_ID" ``` Response: ```json { "access_token": "eyJhbGciOiJIUzI1NiJ9...", "token_type": "bearer", "expires_in": 3600, "scope": "meeting:read meeting:write user:read" } ``` ### Create a Meeting ```bash curl -X POST "https://api.zoom.us/v2/users/HOST_USER_ID/meetings" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "topic": "Team Standup", "type": 2, "start_time": "2025-03-15T10:00:00Z", "duration": 30, "settings": { "join_before_host": false, "waiting_room": true } }' ``` For S2S OAuth, use an explicit host user ID or email in the path. Do not use `me`. ### List Users with Pagination ```bash curl "https://api.zoom.us/v2/users?page_size=300&status=active" \ -H "Authorization: Bearer ACCESS_TOKEN" ``` ## Base URL ``` https://api.zoom.us/v2 ``` ### Regional Base URLs The `api_url` field in OAuth token responses indicates the user's region. Use regional URLs for data residency compliance: | Region | URL | |--------|-----| | Global (default) | `https://api.zoom.us/v2` | | Australia | `https://api-au.zoom.us/v2` | | Canada | `https://api-ca.zoom.us/v2` | | European Union | `https://api-eu.zoom.us/v2` | | India | `https://api-in.zoom.us/v2` | | Saudi Arabia | `https://api-sa.zoom.us/v2` | | Singapore | `https://api-sg.zoom.us/v2` | | United Kingdom | `https://api-uk.zoom.us/v2` | | United States | `https://api-us.zoom.us/v2` | **Note:** You can always use the global URL `https://api.zoom.us` regardless of the `api_url` value. ## Key Features | Feature | Description | |---------|-------------| | **Meeting Management** | Create, read, update, delete meetings with full scheduling control | | **User Provisioning** | Automated user lifecycle (create, update, deactivate, delete) | | **Webinar Operations** | Webinar CRUD, registrant management, panelist control | | **Cloud Recordings** | List, download, delete recordings with file-type filtering | | **Reports & Analytics** | Usage reports, participant data, daily statistics | | **Team Chat** | Channel management, messaging, chatbot integration | | **Zoom Phone** | Call management, voicemail, call routing | | **Zoom Rooms** | Room management, device control, scheduling | | **Webhooks** | Real-time event notifications for 100+ event types | | **WebSockets** | Persistent event streaming without public endpoints | | **GraphQL (Beta)** | Single-endpoint flexible queries at `v3/graphql` | | **AI Companion** | Meeting summaries, transcripts, AI-generated content | | **AI Services / Scribe** | File and archive transcription via Build-platform JWT-authenticated endpoints | ## Prerequisites - Zoom account (Free tier has API access with lower rate limits) - App registered on [Zoom App Marketplace](https://marketplace.zoom.us/) - OAuth credentials (Server-to-Server OAuth or User OAuth) - Appropriate scopes for target endpoints > **Need help with authentication?** See the **[zoom-oauth](../oauth/SKILL.md)** skill for complete OAuth flow implementation. ## Critical Gotchas and Best Practices ### ⚠️ JWT App Type is Deprecated The JWT app type is deprecated. Migrate to **Server-to-Server OAuth**. This does NOT affect JWT token signatures used in Video SDK — only the Marketplace "JWT" app type for REST API access. ```javascript // OLD (JWT app type - DEPRECATED) const token = jwt.sign({ iss: apiKey, exp: expiry }, apiSecret); // NEW (Server-to-Server OAuth) const token = await getServerToServerToken(accountId, clientId, clientSecret); ``` ### ⚠️ The `me` Keyword Rules - **User-level OAuth apps**: MUST use `me` instead of `userId` (otherwise: invalid token error) - **Server-to-Server OAuth apps**: MUST NOT use `me` — provide the actual `userId` or email - **Account-level OAuth apps**: Can use either `me` or `userId` ### ⚠️ Meeting ID vs UUID — Double Encoding UUIDs that begin with `/` or contain `//` must be **double URL-encoded**: ```javascript // UUID: /abc== // Single encode: %2Fabc%3D%3D // Double encode: %252Fabc%253D%253D ← USE THIS const uuid = '/abc=='; const encoded = encodeURIComponent(encodeURIComponent(uuid)); const url = `https://api.zoom.us/v2/meetings/${encoded}`; ``` ### ⚠️ Time Formats - `yyyy-MM-ddTHH:mm:ssZ` — **UTC time** (note the `Z` suffix) - `yyyy-MM-ddTHH:mm:ss` — **Local time** (no `Z`, uses `timezone` field) - Some report APIs only accept UTC. Check the API reference for each endpoint. ### ⚠️ Rate Limits Are Per-Account, Not Per-App All apps on the same Zoom account **share** rate limits. One heavy app can impact others. Monitor `X-RateLimit-Remaining` headers proactively. ### ⚠️ Per-User Daily Limits Meeting/Webinar create/update operations are limited to **100 per day per user** (resets at 00:00 UTC). Distribute operations across different host users when doing bulk operations. ### ⚠️ Download URLs Require Auth and Follow Redirects Recording `download_url` values require Bearer token authentication and may redirect. Always follow redirects: ```bash curl -L -H "Authorization: Bearer ACCESS_TOKEN" "https://zoom.us/rec/download/..." ``` ### Use Webhooks Instead of Polling ```javascript // DON'T: Poll every minute (wastes API quota) setInterval(() => getMeetings(), 60000); // DO: Receive webhook events in real-time app.post('/webhook', (req, res) => { if (req.body.event === 'meeting.started') { handleMeetingStarted(req.body.payload); } res.status(200).send(); }); ``` > **Webhook setup details:** See the **[zoom-webhooks](../webhooks/SKILL.md)** skill for comprehensive webhook implementation. ## Complete Documentation Library This skill includes comprehensive guides organized by category: ### Core Concepts - **[API Architecture](concepts/api-architecture.md)** - REST design, base URLs, regional routing, `me` keyword, ID vs UUID, time formats - **[Authentication Flows](concepts/authentication-flows.md)** - All OAuth flows (S2S, User, PKCE, Device Code) - **[Rate Limiting Strategy](concepts/rate-limiting-strategy.md)** - Limits by plan, retry patterns, request queuing ### Complete Examples - **[Meeting Lifecycle](examples/meeting-lifecycle.md)** - Full Create → Update → Start → End → Delete flow with webhook events - **[User Management](examples/user-management.md)** - CRUD users, list with pagination, bulk operations - **[Recording Pipeline](examples/recording-pipeline.md)** - Download recordings via webhooks + API - **[Webhook Server](examples/webhook-server.md)** - Express.js server with CRC validation and signature verification - **[GraphQL Queries](examples/graphql-queries.md)** - GraphQL queries, mutations, cursor pagination ### Troubleshooting - **[Common Errors](troubleshooting/common-errors.md)** - HTTP status codes, Zoom error codes, error response formats - **[Common Issues](troubleshooting/common-issues.md)** - Rate limits, token refresh, pagination pitfalls, gotchas ### References (39 files covering all Zoom API domains) #### Core APIs - **[references/meetings.md](references/meetings.md)** - Meeting CRUD, types, settings - **[references/users.md](references/users.md)** - User provisioning, types, scopes - **[references/webinars.md](references/webinars.md)** - Webinar management, registrants - **[references/recordings.md](references/recordings.md)** - Cloud recording access - **[references/reports.md](references/reports.md)** - Usage reports, analytics - **[references/accounts.md](references/accounts.md)** - Account management #### Communication - **[references/team-chat.md](references/team-chat.md)** - Team Chat messaging - **[references/chatbot.md](references/chatbot.md)** - Interactive chatbots - **[references/phone.md](references/phone.md)** - Zoom Phone - **[references/mail.md](references/mail.md)** - Zoom Mail - **[references/calendar.md](references/calendar.md)** - Zoom Calendar #### Infrastructure - **[references/rooms.md](references/rooms.md)** - Zoom Rooms - **[references/scim2.md](references/scim2.md)** - SCIM 2.0 provisioning APIs - **[references/rate-limits.md](references/rate-limits.md)** - Rate limit details - **[references/qss.md](references/qss.md)** - Quality of Service Subscription #### Advanced - **[references/graphql.md](references/graphql.md)** - GraphQL API (beta)