Registry /
communication / purecloudplatformclientv2
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.
Install & Compatibility
Where this runs
tested against v259.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 9.845s · 166.7MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 9.8s · import 8.446s · 167MB
212MB installed
● package 212MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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}")
Debug
Known issues
breakingPreview APIs included in the SDK are subject to breaking and non-breaking changes at any time without notice. These resources are not stable.fixAvoid 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.
affects: All versions
breakingThe 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.fixRegularly update the SDK to the latest version. Review release notes for potential breaking changes that might require code modifications.
affects: All versions
gotchaOn Windows, the maximum path length limitation can cause a 'No such file or directory' error during installation.fixRemove the maximum path length limitation on your Windows system as described in Microsoft documentation, or install the project in a shorter directory path.
affects: All versions on Windows
gotchaBy 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()`.fixIf 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`.
affects: All versions
gotchaThe 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.fixFor 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.
affects: All versions
gotchaBy default, SDK logging does not include request and response bodies due to potential PII.fixTo 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.
affects: All versions
gotchaIf connecting to a Genesys Cloud environment other than `mypurecloud.com` (e.g., `mypurecloud.ie`), the base path must be explicitly set.fixSet `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`).
affects: All versions
breakingAuthentication failed because the `client_id` or `client_secret` was missing or invalid, resulting in an `invalid_client` error (e.g., 'no client id provided' or 'invalid client credentials').fixEnsure that `GENESYS_CLOUD_CLIENT_ID` and `GENESYS_CLOUD_CLIENT_SECRET` environment variables are correctly set, or that `PureCloudPlatformClientV2.configuration.client_id` and `PureCloudPlatformClientV2.configuration.client_secret` are properly assigned before initializing the API client. Verify that the client ID and secret values are correct for your Genesys Cloud OAuth client.
affects: All versions
breakingAuthentication requests resulting in 'invalid_client' or 'no client id provided' errors indicate that the client ID or client secret is missing or incorrect in the authentication configuration.fixEnsure that `GENESYS_CLOUD_CLIENT_ID` and `GENESYS_CLOUD_CLIENT_SECRET` environment variables (or corresponding configuration parameters) are correctly set with valid credentials for your Genesys Cloud OAuth client.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'PureCloudPlatformClientV2.rest'
This error typically occurs when the `purecloudplatformclientv2` package is not installed correctly, or there are environment-specific issues preventing Python from locating the submodules.
fixEnsure the package is installed via `pip install PureCloudPlatformClientV2`. If on Windows, resolve potential maximum path length limitations before installation. Verify your Python environment and path are correctly configured.
AttributeError: module 'PureCloudPlatformClientV2' has no attribute 'PostAnalyticsConversationsAggregatesQueryRequest'
This indicates an attempt to access an API class or method that either does not exist, has been renamed, or is nested differently within the SDK than expected, often due to outdated documentation or an incorrect understanding of the SDK structure.
fixRefer to the official SDK documentation or the `platform-client-sdk-python` GitHub repository to find the correct API class. For analytics queries, the correct class is typically `PureCloudPlatformClientV2.AnalyticsApi()`.
ApiException: {'message': 'Invalid login credentials.' ...} or ApiException: 'This request requires a user context. Client credentials cannot be used for requests to this resource.'
These `ApiException` errors are related to authentication. 'Invalid login credentials' means the client ID, client secret, or region configuration is incorrect. 'This request requires a user context' means you are attempting to use client credentials (app-level authentication) for an API endpoint that requires user-specific authorization (e.g., Implicit Grant, Authorization Code Grant, PKCE Grant).
fixFor 'Invalid login credentials', double-check your `GENESYS_CLOUD_CLIENT_ID`, `GENESYS_CLOUD_CLIENT_SECRET`, and `PureCloudPlatformClientV2.configuration.host` (region). For 'This request requires a user context', use an appropriate OAuth grant type that provides a user context (like Authorization Code Grant or PKCE) for the specific API endpoint.
No such file or directory (during pip install PureCloudPlatformClientV2 on Windows)
This error often occurs on Windows due to the default maximum path length limitation, which prevents `pip` from installing packages with deeply nested file structures, like `purecloudplatformclientv2`.
fixOn Windows, disable the maximum path length limitation. This can typically be done via a Group Policy setting or a registry edit (e.g., enabling 'Enable Win32 long paths' in Local Group Policy Editor under 'Computer Configuration > Administrative Templates > System > Filesystem'). After applying the change, restart your system if necessary and retry `pip install PureCloudPlatformClientV2`.
ModuleNotFoundError: No module named 'purecloudplatformclientv2'
The `purecloudplatformclientv2` library is not installed in the Python environment, or the script is being run in an environment different from where the library was installed.
fixInstall the library using pip: `pip install purecloudplatformclientv2`
Audit
Dependencies
pythonrequiredRequired Python version