RingCentral Python SDK

0.9.2 · active · verified Thu Apr 16

The RingCentral Python SDK provides a convenient way to interact with the RingCentral API, simplifying authentication, request signing, and API call execution. It is currently at version 0.9.2 and follows a semi-regular release cadence, often bundling bug fixes and minor feature enhancements.

Common errors

```
ringcentral.RestException: HTTP Error 403 Forbidden
```
cause The authenticated application or user lacks the necessary permissions (scopes) to access the requested API endpoint or resource.

fix Check your RingCentral application's permissions/scopes in the Developer Portal. For user authorization, ensure the user has the necessary roles/permissions assigned within RingCentral to perform the action.
```
ringcentral.RestException: HTTP Error 400 Bad Request
```
cause The API request body or parameters are malformed, missing required fields, or contain invalid data.

fix Review the RingCentral API documentation for the specific endpoint you are calling to ensure all required parameters are present and correctly formatted (e.g., JSON structure, data types). Print the request body before sending for debugging.
```
ImportError: cannot import name 'SDK' from 'ringcentral'
```
cause The `ringcentral` library is either not installed, or an outdated version is installed that does not expose the `SDK` class directly.

fix Ensure the library is installed: `pip install ringcentral`. If already installed, upgrade to the latest version: `pip install --upgrade ringcentral`. If you intend to use an older `RestClient` interface, import that instead or migrate to the `SDK` class.

Warnings

breaking As the library is pre-1.0 (currently 0.9.x), minor version updates can introduce breaking changes without explicit major version increments. Always review changelogs when upgrading.
Fix: Consult the GitHub releases and changelog for specific migration steps before upgrading. Test new versions thoroughly in a development environment.
gotcha Confusing sandbox (developer) and production server URLs. Using production credentials on a sandbox URL or vice-versa will lead to authentication failures.
Fix: Ensure `RINGCENTRAL_SERVER_URL` is set correctly: `https://platform.devtest.ringcentral.com` for sandbox and `https://platform.ringcentral.com` for production. Match your credentials to the correct environment.
gotcha Handling token expiration and refresh. While the `SDK`'s `platform` object automatically refreshes tokens when using `platform.login()`, if you manage tokens manually or re-instantiate `SDK` frequently, you might encounter expired token errors.
Fix: For long-running applications, reuse the `platform` object returned by `rcsdk.platform()`. If implementing custom token management, ensure you handle `RestException` for 401 Unauthorized errors and re-authenticate or refresh tokens.
gotcha RingCentral APIs are versioned (e.g., `/restapi/v1.0/`). While the SDK generally defaults to the latest stable, hardcoding API paths might lead to issues if a new major API version is released.
Fix: Always use the full `/restapi/vX.Y/` path segment in your API calls. Monitor RingCentral API documentation for upcoming version changes and ensure your code is compatible.

Install

pip install ringcentral Install latest version

Imports

SDK
```
from ringcentral import SDK
```
RestClient
wrong:
```
from ringcentral import SDK; RestClient(client_id, client_secret, server_url)
```
correct:
```
from ringcentral import RestClient
```
While `RestClient` can be imported directly, the recommended approach is to instantiate it via `SDK.platform()` to leverage token management and other SDK features.

Quickstart

This quickstart initializes the RingCentral SDK using environment variables for credentials (client ID, client secret, server URL, username, password). It then performs a login using the password flow and fetches basic account information, finally logging out. Remember to replace placeholder values or set environment variables.

import os
from ringcentral import SDK

# Environment variables for RingCentral credentials
CLIENT_ID = os.environ.get('RINGCENTRAL_CLIENT_ID', 'YOUR_CLIENT_ID')
CLIENT_SECRET = os.environ.get('RINGCENTRAL_CLIENT_SECRET', 'YOUR_CLIENT_SECRET')
SERVER_URL = os.environ.get('RINGCENTRAL_SERVER_URL', 'https://platform.ringcentral.com') # Use 'https://platform.devtest.ringcentral.com' for sandbox
USERNAME = os.environ.get('RINGCENTRAL_USERNAME', 'YOUR_USERNAME') # Phone number with country code, e.g., +1650xxxxxxx
PASSWORD = os.environ.get('RINGCENTRAL_PASSWORD', 'YOUR_PASSWORD')
EXTENSION = os.environ.get('RINGCENTRAL_EXTENSION', None) # Optional, usually '101' for main extension

try:
    if not all([CLIENT_ID, CLIENT_SECRET, SERVER_URL, USERNAME, PASSWORD]):
        print("Please set RINGCENTRAL_CLIENT_ID, RINGCENTRAL_CLIENT_SECRET, RINGCENTRAL_SERVER_URL, RINGCENTRAL_USERNAME, and RINGCENTRAL_PASSWORD environment variables.")
        exit(1)

    rcsdk = SDK(CLIENT_ID, CLIENT_SECRET, SERVER_URL)
    platform = rcsdk.platform()

    # Authorize using password flow
    platform.login(username=USERNAME, password=PASSWORD, extension=EXTENSION)
    print("Logged in successfully!")

    # Example: Fetch extension info
    resp = platform.get('/restapi/v1.0/account/~')
    account_info = resp.json()
    print(f"Account ID: {account_info['id']}")
    print(f"Account Name: {account_info['name']}")

    platform.logout()
    print("Logged out.")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →