{"id":4176,"library":"prelude-python-sdk","title":"Prelude Python SDK","description":"The `prelude-python-sdk` is the official Python library for interacting with the Prelude API. It provides convenient access to Prelude's REST API from any Python 3.9+ application, offering type definitions for all request parameters and response fields. The library supports both synchronous and asynchronous clients, powered by httpx, and is generated with Stainless. Currently at version 0.11.0, it maintains a rapid release cadence with updates typically every 1-3 months.","status":"active","version":"0.11.0","language":"en","source_language":"en","source_url":"https://github.com/prelude-so/python-sdk","tags":["API client","SDK","security","verification","fraud prevention","asynchronous","authentication"],"install":[{"cmd":"pip install prelude-python-sdk","lang":"bash","label":"Default installation"},{"cmd":"pip install prelude-python-sdk[aiohttp]","lang":"bash","label":"Install with aiohttp for improved async performance"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false},{"reason":"Optional dependency for the asynchronous client to use aiohttp as the HTTP backend for improved concurrency performance. Defaults to httpx.","package":"aiohttp","optional":true}],"imports":[{"note":"Main synchronous client.","wrong":null,"symbol":"Prelude","correct":"from prelude_python_sdk import Prelude"},{"note":"Main asynchronous client.","wrong":null,"symbol":"AsyncPrelude","correct":"from prelude_python_sdk import AsyncPrelude"},{"note":"Required when initializing AsyncPrelude to use aiohttp as the backend.","wrong":null,"symbol":"DefaultAioHttpClient","correct":"from prelude_python_sdk import DefaultAioHttpClient"}],"quickstart":{"code":"import os\nfrom prelude_python_sdk import Prelude\n\n# It's recommended to set API_TOKEN as an environment variable (e.g., export API_TOKEN=\"your_token\")\napi_token = os.environ.get(\"API_TOKEN\", \"YOUR_DEFAULT_API_TOKEN\")\n\nif api_token == \"YOUR_DEFAULT_API_TOKEN\":\n    print(\"Warning: Please set the API_TOKEN environment variable or replace 'YOUR_DEFAULT_API_TOKEN' with your actual Prelude API token.\")\n\ntry:\n    client = Prelude(api_token=api_token)\n\n    # Example: Create a phone number verification\n    verification = client.verification.create(\n        target={\n            \"type\": \"phone_number\",\n            \"value\": \"+15551234567\", # Replace with a valid test phone number\n        },\n    )\n    print(f\"Successfully initiated verification with ID: {verification.id}\")\n\n    # Example: Check a verification code (uncomment and replace with actual code/target)\n    # check_response = client.verification.check(\n    #     target={\n    #         \"type\": \"phone_number\",\n    #         \"value\": \"+15551234567\",\n    #     },\n    #     code=\"123456\", # Replace with the received verification code\n    # )\n    # print(f\"Verification check successful for ID: {check_response.id}, status: {check_response.status}\")\n\nexcept Exception as e:\n    print(f\"An error occurred during Prelude API interaction: {e}\")\n","lang":"python","description":"This quickstart initializes the synchronous Prelude client using an API token from environment variables and demonstrates how to initiate a phone number verification. For asynchronous usage, import `AsyncPrelude` and use `await` with API calls."},"warnings":[{"fix":"Users relying on strict type checking or undocumented internal APIs should review changelogs carefully before updating minor versions. Consider pinning to exact minor versions to avoid unexpected changes.","message":"While generally following Semantic Versioning (SemVer), the library explicitly states that certain backwards-incompatible changes may be released as minor versions. These include changes to static types, internal library implementation, or changes not expected to affect the majority of users.","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure your project's Pydantic version is compatible with the SDK. If encountering model-related issues, try upgrading to the latest SDK version or adjusting your Pydantic version. The SDK is generated using Stainless, which often aligns with Pydantic v2.","message":"The library's Pydantic models might have compatibility issues with different major versions of Pydantic in your environment. Version 0.4.0 notably included a fix for 'pydantic v1: more robust Mod'.","severity":"gotcha","affected_versions":"<0.4.0 (potential for issues), All versions (general compatibility care)"},{"fix":"To use aiohttp, install the extra and pass `http_client=DefaultAioHttpClient()` to `AsyncPrelude`. Otherwise, `httpx` will be used, or an `ImportError` might occur if `aiohttp` classes are referenced without installation.","message":"When using the asynchronous client, while `httpx` is the default HTTP backend, choosing `aiohttp` for potentially better concurrency requires an explicit extra installation (`pip install prelude-python-sdk[aiohttp]`) and explicit client instantiation with `http_client=DefaultAioHttpClient()`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use the client within a `with` statement (`with Prelude() as client: ...`) or explicitly call `client.close()` when the client is no longer needed, especially in async contexts.","message":"HTTP client connections are closed automatically when the client object is garbage collected. However, in long-running applications or serverless functions, it's best practice to explicitly close the client to prevent resource leaks (e.g., open sockets).","severity":"gotcha","affected_versions":"All versions"},{"fix":"If `response.my_field is None` and `'my_field' not in response.model_fields_set`, the field was missing. Otherwise, if it's in `model_fields_set`, it was explicitly `null`.","message":"In API responses, fields that are explicitly `null` in the JSON and fields that are entirely `missing` will both appear as `None` in Python. To differentiate between these two cases, you must check the `response.model_fields_set` property.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}