PureCloud Platform API SDK

254.0.0 · active · verified Sun Mar 29

The `PureCloudPlatformClientV2` library is the official Python SDK for interacting with the Genesys Cloud Platform API. It provides a comprehensive set of classes and methods generated from the API's Swagger definition, allowing developers to programmatically manage various aspects of their Genesys Cloud environment. The library is actively maintained by Genesys Developer Evangelists, with releases tied to the Genesys Cloud API's update cadence, typically following Semantic Versioning to reflect changes in the underlying API. The current version is 254.0.0.

Warnings

breaking Preview APIs included in the SDK are subject to breaking and non-breaking changes at any time without notice. These resources are not stable.
Fix: Avoid using Preview APIs in production environments or be prepared for frequent updates and code changes. Check the Genesys Cloud Developer Center for a list of preview APIs.
breaking The SDK can have major version bumps due to changes in the underlying Platform API's Swagger definition, even if the API itself remains at major version 2. It is strongly recommended to keep the SDK updated to the latest version.
Fix: Regularly update the SDK to the latest version. Review release notes for potential breaking changes that might require code modifications.
gotcha On Windows, the maximum path length limitation can cause a 'No such file or directory' error during installation.
Fix: Remove the maximum path length limitation on your Windows system as described in Microsoft documentation, or install the project in a shorter directory path.
gotcha By default, Python's `None` values for model properties are stripped out before sending requests, meaning they won't be serialized as JSON `null`. To explicitly send a JSON `null` value, use `PureCloudPlatformClientV2.ApiNullValue()`.
Fix: If an API endpoint requires sending a `null` value for a property (e.g., to reset it), assign `PureCloudPlatformClientV2.ApiNullValue()` to that property instead of `None`.
gotcha The Client Credentials Grant is intended for non-human applications. Some API endpoints (e.g., Conversations API) require a user context and will not work with client credentials, resulting in a 'This request requires a user context' error.
Fix: For endpoints requiring a user context, use user-based authorization grants like Authorization Code Grant, PKCE Grant, or Implicit Grant. These typically involve redirecting a user to the Genesys Cloud login page in a browser.
gotcha By default, SDK logging does not include request and response bodies due to potential PII.
Fix: To log request/response bodies for debugging, set `PureCloudPlatformClientV2.configuration.logger.log_request_body = True` and `PureCloudPlatformClientV2.configuration.logger.log_response_body = True`. Be mindful of PII in logs.
gotcha If connecting to a Genesys Cloud environment other than `mypurecloud.com` (e.g., `mypurecloud.ie`), the base path must be explicitly set.
Fix: Set `PureCloudPlatformClientV2.configuration.host = 'https://api.YOUR_REGION.pure.cloud'` before constructing any API classes, replacing `YOUR_REGION.pure.cloud` with your specific Genesys Cloud environment domain (e.g., `api.mypurecloud.ie`).

Install

pip install PureCloudPlatformClientV2 Install latest version

Imports

PureCloudPlatformClientV2
```
import PureCloudPlatformClientV2
```
This is the primary import for the entire SDK.

ApiClient

import PureCloudPlatformClientV2.api_client
api_client = PureCloudPlatformClientV2.api_client.ApiClient()

The ApiClient is essential for configuring the SDK and handling authentication.

Configuration
```
PureCloudPlatformClientV2.configuration
```
Used to access global SDK configuration settings like access token, logging, and base path.
AuthorizationApi
```
auth_api = PureCloudPlatformClientV2.AuthorizationApi(api_client)
```
Example of importing and instantiating a specific API class. Replace 'AuthorizationApi' with the desired API.
YearMonth
```
from PureCloudPlatformClientV2 import YearMonth
```
Special class for handling 'year-month' formatted strings in API requests/responses.
ApiNullValue
```
from PureCloudPlatformClientV2 import ApiNullValue
```
Used to explicitly send a JSON 'null' value for a property, as Python's 'None' is typically stripped.

Quickstart

This quickstart demonstrates how to authenticate using the Client Credentials Grant and fetch the current user's details. Ensure your `GENESYS_CLOUD_CLIENT_ID`, `GENESYS_CLOUD_CLIENT_SECRET`, and optionally `GENESYS_CLOUD_REGION` are set as environment variables. This grant type is suitable for non-human applications or services.

import PureCloudPlatformClientV2
import os

# Configure API client with Client Credentials Grant
# Ensure GENESYS_CLOUD_CLIENT_ID and GENESYS_CLOUD_CLIENT_SECRET are set as environment variables
CLIENT_ID = os.environ.get('GENESYS_CLOUD_CLIENT_ID', '')
CLIENT_SECRET = os.environ.get('GENESYS_CLOUD_CLIENT_SECRET', '')
GENESYS_CLOUD_REGION = os.environ.get('GENESYS_CLOUD_REGION', 'mypurecloud.com') # e.g., mypurecloud.ie

# Set the Genesys Cloud region (e.g., 'mypurecloud.ie', 'mypurecloud.com.au')
# Default is mypurecloud.com
PureCloudPlatformClientV2.configuration.host = f'https://api.{GENESYS_CLOUD_REGION}'

api_client = PureCloudPlatformClientV2.api_client.ApiClient()

try:
    # Authenticate using client credentials
    api_client.get_client_credentials_token(CLIENT_ID, CLIENT_SECRET)
    print("Authentication successful!")

    # Instantiate an API class (e.g., UsersApi)
    users_api = PureCloudPlatformClientV2.UsersApi(api_client)

    # Make an API call (e.g., get the authenticated user's information)
    me = users_api.get_users_me()
    print(f"Authenticated user: {me.name} (ID: {me.id})")

except PureCloudPlatformClientV2.rest.ApiException as e:
    print(f"Exception when calling Genesys Cloud API: {e}")
    print(f"Ensure GENESYS_CLOUD_CLIENT_ID and GENESYS_CLOUD_CLIENT_SECRET are set correctly and have the necessary permissions.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →