build-zoom-rest-api-app

What this skill does

# /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