Introduction
Using Zoom APIs
Pagination
Error Definitions
Rate Limits
Testing Zoom APIs with Postman
Accounts
Billing
Chat Channels
Chat Channels (Account-level)
Chat Messages
Chatbot Messages
Contacts
Cloud Recording
Dashboards
Devices
Groups
IM Chat
IM Groups
Meetings
PAC
Phone
Phone Auto Receptionists
Phone Blocked List
Phone Call Queues
Phone Devices
Phone Reports
Phone Shared Line Groups
Phone Site
Common Area Phones
Reports
Roles
Rooms
Rooms Account
Rooms Location
SIP Phone
TrackingField
TSP
Users
Webinars
Rooms Devices
SIP Connected Audio
Deprecated API Endpoints
Account Events
App Events
Billing Events
Chat Message Events
Chat Channel Events
Chatbot Events
Meeting Events
Phone Events
Recording Events
TSP Events
User Events
Webinar Events
Zoom Room Events
Data Compliance

Using Zoom APIs


Zoom APIs allow developers to request information from the Zoom, including (but not limited) to user details, meeting reports, dashboard data, as well as perform actions on the Zoom platform on a user’s behalf. For example, creating a new user or deleting meeting recordings.

Authentication

Each HTTP request made to the Zoom API must be authenticated by Zoom. Zoom supports the following authentication request methods:

Using OAuth 2.0

OAuth 2.0 allows applications to obtain access to Zoom resources (such as the user’s profile information) that are made available via the Zoom API.

The following sections provide an overview on the OAuth protocol. To start using the OAuth protocol for your app’s authentication with Zoom, you must first create an OAuth app in the Zoom App Marketplace.

To see a sample OAuth app in action, read the Quickstart - OAuth guide.

OAuth Roles

The OAuth protocol defines four specific roles. These roles are actively involved in the process of authentication with Zoom APIs:

  • Resource Owner — A user in a Zoom account who can either authorize or decline a Client from accessing information related to the user’s Zoom account.

  • Resource Server — The server that hosts the resource. If your app is integrating with the Zoom API to obtain user-related information, then the Zoom API server is considered the resource server.

  • Client — The application that requests access to the user’s information. If your app makes access requests to the Zoom API, then your app is considered the Client.

Client and app terms

In this document, you will see the terms Client and app used interchangeably. Both of these terms refer to the app that needs to integrate with the Zoom APIs.

Generally, the interaction between a Client (your app), a Zoom user, Zoom’s authorization service, and the Zoom API will look similar to the following image:

The Zoom authorization process
The Zoom authorization process
  1. The Client (your app) requests authorization from the Zoom user to access the user’s information.

  2. The user authorizes the app and the app receives an Authorization Grant.

  3. The app presents the Authorization Grant to the Zoom Authorization Server to verify that it has received the user’s permission to access user information.

  4. The Zoom Authorization Server acknowledges that user has permitted the app with requested access and it sends an Access Token along with a Refresh Token back to the app. The access token must be used as a means of authentication while making API calls to the Zoom API Server.

What is an Access Token?

An Access Token is a credential in the form of string that represents the authorization granted to the app. It can be compared with that of an ID card that identifies a person with their level of authority (such as a person’s driving license indicates that the person is authorized to drive).

  1. The app calls the Zoom API to access requested resource by including the Access Token in the request as a means of authentication. When an access token expires, it becomes invalid. In this case, the client must use the Refresh Token to request another valid access token.

  2. After the Zoom API server authenticates the app, it sends back the Requested Resource in the form of a JSON response. If the authentication fails, an error is thrown stating what caused the error.

OAuth Grant Types

An Authorization Grant is the authorization assigned to the Client by the resource owner. The grant type refers to the method the Client uses to request authorization.

OAuth 2.0 supports various grant types. However, with Zoom APIs, you should either the authorization code or client credentials grant types where applicable:

Authorization Code

An Authorization Code is the most commonly-used grant type for Zoom APIs. The usage of this grant type is described in detail in the OAuth with Zoom guide.

The following steps provide an overview of the Authorization Code grant flow:

  1. The Client directs the user to the Zoom authorization server. The user will see a dialog box with permission request for access. This process is provisioned by Zoom via the Publishable URL. When a user tries to install or re-install your app, the user will be directed to the Zoom API authorization endpoint. To test it with your app locally, copy the Testable URL of your app and open it in a browser. A page similar to the one shown in the image below appears:
An example of the permission request dialog box.
An example of the permission request dialog box.
  1. The user clicks Authorize.

  2. The user is redirected to the app’s redirect_url along with an authorization code in the query string. The URL with the authorization code resembles following URL: https://yourappsredirecturl/?code={theauthorizationcode}.

  3. The Client makes a request to Zoom to exchange the authorization code for an access token.

Example
var request = require("request");

var options = {
  method: 'POST',
  url: 'https://zoom.us/oauth/token',
  qs: {
   grant_type: 'authorization_code',
   //The code below is a sample authorization code. Replace it with your actual authorization code while making requests.
   code: 'B1234558uQ',
    //The uri below is a sample redirect_uri. Replace it with your actual redirect_uri while making requests.
   redirect_uri: 'https://abcd.example.com'
  },
  headers: {
    /**The credential below is a sample base64 encoded credential. Replace it with "Authorization: 'Basic ' + Buffer.from(your_app_client_id + ':' + your_app_client_secret).toString('base64')"
    **/
   Authorization: 'Basic abcdsdkjfesjfg'
  }
};

  request(options, function(error, response, body) {
   if (error) throw new Error(error);

   console.log(body);
  });

Client Credentials

The Client Credentials grant is used to get an access token for APIs that require only a service’s permission. Thsi grant does not require a user’s permission.

For Zoom APIs, use the Client Credentials to get an access token from the Chatbot service in order to use the Send Chatbot Messages API.

To use Client Credentials grant type, perform the following steps:

  1. Navigate to your app’s dashboard in the Zoom App Marketplace.

  2. In the App Credentials section of your app, copy your app’s Client ID and Client Secret information.

  3. Make a POST request to the following Zoom Authorization Endpoint URL:

    https://zoom.us/oauth/token?grant_type=client_credentials

    The value of the grant_type query parameter is set as client_credentials to indicate the Client Credentials grant type.

    Use the Basic access authentication Header and provide the base64-encoded string of your Client ID and Client Secret as credentials.

Example
var request = require("request");

var options = {
  method: 'POST',
  url: 'https://zoom.us/oauth/token?grant_type=client_credentials',
  headers: {
    /**The credential below is a sample base64 encoded credential. Replace it with "Authorization: 'Basic ' + Buffer.from(your_app_client_id + ':' + your_app_client_secret).toString('base64')"
    **/
   Authorization: 'Basic abcdsdkjfesjfg'
  }
  };

  request(options, function(error, response, body) {
   if (error) throw new Error(error);

   console.log(body);
  });

After you receive you access token, you can start using the Send Chatbot Messages API.

To learn more about how you can start using OAuth in your app, read the OAuth with Zoom guide, followed by the Quickstart - OAuth tutorial.

Using JWT

A JSON Web Token (JWT) lets you to create tokens that provide secure data transmission using a compact JSON object. JWTs contain a signed payload that helps establish server-to-server authentication.

If only you or your Zoom account users will use your app, it is recommended that you use JWT authentication. To do this, register a JWT app in the Zoom App Marketplace. Use the token generated from the JWT app and start making API requests to the Zoom APIs.

To learn more about JWTs, read the JWT with Zoom guide and the Quickstart - JWT tutorial.

API requests

All API requests must be made over HTTPS. The https://api.zoom.us/v2/ URL is the request base URL. The complete URL varies depending on the accessed resource.

For example, to get a user’s details in your app, you must make an HTTP GET request to the https://api.zoom.us/v2/users/{userId} URL. If your app is registered in the Zoom App Marketplace as an account-level OAuth app, your app must have the user:read:admin scope in order to use the Get a user API.

Requests for JWT apps

You do not need any scopes for JWT apps. Your JWT app will only have access to your Zoom account’s information. To view a specific user’s information, you must provide the user’s userId or email address as the {userId} value in the API path. You can also use the me keyword instead of the userId value.

Example
For Account-level Apps
var request = require("request");

var options = {
	method: 'GET',
	// A non-existing sample userId is used in the example below. 
	url: 'https://api.zoom.us/v2/users/sjkf1234',
	headers: {
		authorization: 'Bearer {yourtokenhere}' // Do not publish or share your token publicly.
	}
};

request(options, function (error, response, body) {
	if (error) throw new Error(error);

	console.log(body);
});

Requests for OAuth apps

To get information about a user with a user-level OAuth app, the app must have the user:read scope. While the URL for the request is the same, the behavior of userId value is different from an account-level apps. Instead of providing a user’s userId or email address, you must use the me keyword as the value of the userId path parameter. Otherwise, your app will receive an invalid token error.

Example
For User-level Apps

var request = require("request");

var options = {
	method: 'GET',
	// Use the `me` keyword for the request below. 
	url: 'https://api.zoom.us/v2/users/me',
	headers: {
		authorization: 'Bearer {yourtokenhere}' // Do not publish or share your token with anyone.
	}
};

request(options, function (error, response, body) {
	if (error) throw new Error(error);

	console.log(body);
});

The me keyword

You can use the me keyword in place of the userId keyword in any supported API call. When you use the me keyword, the API call uses the authenticated user’s access token.

For example, to use the API to update a user’s settings as the authenticated user, you would call the API with the /users/me/settings path, not the /users/{userId}/settings path.


Need help?

If you're looking for help, try Developer Support or our Developer Forum. Priority support is also available with Premier Developer Support plans.