PureCloud Platform API SDK

254.0.0 verified Tue May 12 auth: no python install: verified quickstart: verified

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.

pip install PureCloudPlatformClientV2

Common errors

error ModuleNotFoundError: No module named 'PureCloudPlatformClientV2.rest' ↓

cause This error typically occurs when the `purecloudplatformclientv2` package is not installed correctly, or there are environment-specific issues preventing Python from locating the submodules.

fix

Ensure 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.

error AttributeError: module 'PureCloudPlatformClientV2' has no attribute 'PostAnalyticsConversationsAggregatesQueryRequest' ↓

cause 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.

fix

Refer 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().

error ApiException: {'message': 'Invalid login credentials.' ...} or ApiException: 'This request requires a user context. Client credentials cannot be used for requests to this resource.' ↓

cause 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).

fix

For '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.

error No such file or directory (during pip install PureCloudPlatformClientV2 on Windows) ↓

cause 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`.

fix

On 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.

error ModuleNotFoundError: No module named 'purecloudplatformclientv2' ↓

cause 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.

fix

Install the library using pip: pip install purecloudplatformclientv2

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`).

breaking Authentication 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'). ↓

fix Ensure 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.

breaking Authentication 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. ↓

fix Ensure 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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) sdist - 5.94s 165.4M

3.10 alpine (musl) - - 5.43s 164.2M

3.10 slim (glibc) wheel 10.7s 3.38s 166M

3.10 slim (glibc) - - 3.60s 165M

3.11 alpine (musl) sdist - 26.97s 256.4M

3.11 alpine (musl) - - 25.65s 254.4M

3.11 slim (glibc) wheel 10.1s 22.48s 257M

3.11 slim (glibc) - - 22.00s 255M

3.12 alpine (musl) sdist - 6.39s 243.8M

3.12 alpine (musl) - - 6.68s 241.9M

3.12 slim (glibc) wheel 10.8s 6.30s 244M

3.12 slim (glibc) - - 6.79s 242M

3.13 alpine (musl) sdist - 6.12s 238.9M

3.13 alpine (musl) - - 6.48s 236.9M

3.13 slim (glibc) wheel 11.0s 6.17s 239M

3.13 slim (glibc) - - 6.57s 237M

3.9 alpine (musl) sdist - 3.91s 153.7M

3.9 alpine (musl) - - 4.35s 153.7M

3.9 slim (glibc) wheel 11.1s 3.58s 154M

3.9 slim (glibc) - - 3.62s 154M

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 verified last tested: 2026-04-24

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}")