{"id":798,"library":"purecloudplatformclientv2","title":"PureCloud Platform API SDK","description":"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.","status":"active","version":"254.0.0","language":"python","source_language":"en","source_url":"https://github.com/MyPureCloud/platform-client-sdk-python","tags":["api","swagger","purecloud","genesys","platform","sdk","communications"],"install":[{"cmd":"pip install PureCloudPlatformClientV2","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required Python version","package":"python","version":">=3.10","optional":false}],"imports":[{"note":"This is the primary import for the entire SDK.","symbol":"PureCloudPlatformClientV2","correct":"import PureCloudPlatformClientV2"},{"note":"The ApiClient is essential for configuring the SDK and handling authentication.","symbol":"ApiClient","correct":"import PureCloudPlatformClientV2.api_client\napi_client = PureCloudPlatformClientV2.api_client.ApiClient()"},{"note":"Used to access global SDK configuration settings like access token, logging, and base path.","symbol":"Configuration","correct":"PureCloudPlatformClientV2.configuration"},{"note":"Example of importing and instantiating a specific API class. Replace 'AuthorizationApi' with the desired API.","symbol":"AuthorizationApi","correct":"auth_api = PureCloudPlatformClientV2.AuthorizationApi(api_client)"},{"note":"Special class for handling 'year-month' formatted strings in API requests/responses.","symbol":"YearMonth","correct":"from PureCloudPlatformClientV2 import YearMonth"},{"note":"Used to explicitly send a JSON 'null' value for a property, as Python's 'None' is typically stripped.","symbol":"ApiNullValue","correct":"from PureCloudPlatformClientV2 import ApiNullValue"}],"quickstart":{"code":"import PureCloudPlatformClientV2\nimport os\n\n# Configure API client with Client Credentials Grant\n# Ensure GENESYS_CLOUD_CLIENT_ID and GENESYS_CLOUD_CLIENT_SECRET are set as environment variables\nCLIENT_ID = os.environ.get('GENESYS_CLOUD_CLIENT_ID', '')\nCLIENT_SECRET = os.environ.get('GENESYS_CLOUD_CLIENT_SECRET', '')\nGENESYS_CLOUD_REGION = os.environ.get('GENESYS_CLOUD_REGION', 'mypurecloud.com') # e.g., mypurecloud.ie\n\n# Set the Genesys Cloud region (e.g., 'mypurecloud.ie', 'mypurecloud.com.au')\n# Default is mypurecloud.com\nPureCloudPlatformClientV2.configuration.host = f'https://api.{GENESYS_CLOUD_REGION}'\n\napi_client = PureCloudPlatformClientV2.api_client.ApiClient()\n\ntry:\n    # Authenticate using client credentials\n    api_client.get_client_credentials_token(CLIENT_ID, CLIENT_SECRET)\n    print(\"Authentication successful!\")\n\n    # Instantiate an API class (e.g., UsersApi)\n    users_api = PureCloudPlatformClientV2.UsersApi(api_client)\n\n    # Make an API call (e.g., get the authenticated user's information)\n    me = users_api.get_users_me()\n    print(f\"Authenticated user: {me.name} (ID: {me.id})\")\n\nexcept PureCloudPlatformClientV2.rest.ApiException as e:\n    print(f\"Exception when calling Genesys Cloud API: {e}\")\n    print(f\"Ensure GENESYS_CLOUD_CLIENT_ID and GENESYS_CLOUD_CLIENT_SECRET are set correctly and have the necessary permissions.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Preview APIs included in the SDK are subject to breaking and non-breaking changes at any time without notice. These resources are not stable.","severity":"breaking","affected_versions":"All versions"},{"fix":"Regularly update the SDK to the latest version. Review release notes for potential breaking changes that might require code modifications.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"On Windows, the maximum path length limitation can cause a 'No such file or directory' error during installation.","severity":"gotcha","affected_versions":"All versions on Windows"},{"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`.","message":"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()`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"By default, SDK logging does not include request and response bodies due to potential PII.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"If connecting to a Genesys Cloud environment other than `mypurecloud.com` (e.g., `mypurecloud.ie`), the base path must be explicitly set.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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').","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T19:30:42.443Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"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.","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.","error":"ModuleNotFoundError: No module named 'PureCloudPlatformClientV2.rest'"},{"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()`.","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.","error":"AttributeError: module 'PureCloudPlatformClientV2' has no attribute 'PostAnalyticsConversationsAggregatesQueryRequest'"},{"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.","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).","error":"ApiException: {'message': 'Invalid login credentials.' ...} or ApiException: 'This request requires a user context. Client credentials cannot be used for requests to this resource.'"},{"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`.","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`.","error":"No such file or directory (during pip install PureCloudPlatformClientV2 on Windows)"},{"fix":"Install the library using pip: `pip install 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.","error":"ModuleNotFoundError: No module named 'purecloudplatformclientv2'"}],"ecosystem":"pypi","meta_description":null,"install_score":85,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"257.0.0","cli_name":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":null,"import_time_s":5.94,"mem_mb":153,"disk_size":"165.4M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":5.43,"mem_mb":151.8,"disk_size":"164.2M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":10.7,"import_time_s":3.38,"mem_mb":153,"disk_size":"166M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.6,"mem_mb":151.8,"disk_size":"165M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":null,"import_time_s":26.97,"mem_mb":177.2,"disk_size":"256.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":25.65,"mem_mb":175.7,"disk_size":"254.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":10.1,"import_time_s":22.48,"mem_mb":177.2,"disk_size":"257M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":22,"mem_mb":175.7,"disk_size":"255M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":null,"import_time_s":6.39,"mem_mb":173.9,"disk_size":"243.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":6.68,"mem_mb":172.6,"disk_size":"241.9M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":10.8,"import_time_s":6.3,"mem_mb":173.9,"disk_size":"244M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":6.79,"mem_mb":172.6,"disk_size":"242M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":null,"import_time_s":6.12,"mem_mb":170.8,"disk_size":"238.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":6.48,"mem_mb":169.5,"disk_size":"236.9M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":11,"import_time_s":6.17,"mem_mb":170.8,"disk_size":"239M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":6.57,"mem_mb":169.5,"disk_size":"237M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"sdist","failure_reason":null,"install_time_s":null,"import_time_s":3.91,"mem_mb":155.5,"disk_size":"153.7M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.35,"mem_mb":155.5,"disk_size":"153.7M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":11.1,"import_time_s":3.58,"mem_mb":155.5,"disk_size":"154M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.62,"mem_mb":155.5,"disk_size":"154M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}