{"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":"python","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,"search_vec":"'-3':75 '0.11.0':63 '1':74 '3.9':32 'access':23 'api':19,28,77 'applic':33 'asynchron':50,84 'authent':85 'cadenc':69 'client':51,78 'conveni':22 'current':60 'definit':36 'everi':73 'field':43 'fraud':82 'generat':57 'httpx':54 'interact':15 'librari':13,45 'maintain':65 'month':76 'offer':34 'offici':11 'paramet':40 'power':52 'prelud':1,6,18,25 'prelude-python-sdk':5 'prevent':83 'provid':21 'python':2,7,12,31 'rapid':67 'releas':68 'request':39 'respons':42 'rest':27 'sdk':3,8,79 'secur':80 'stainless':59 'support':46 'synchron':48 'type':35 'typic':72 'updat':71 'verif':81 'version':62","created_at":"2026-04-12T03:44:12.503114+00:00","updated_at":"2026-04-16T18:09:35.936216+00:00","problems":[{"fix":"Install the library using pip: `pip install prelude-python-sdk`","cause":"The `prelude-python-sdk` package has not been installed or is not accessible in the current Python environment.","error":"ModuleNotFoundError: No module named 'prelude_python_sdk'"},{"fix":"Ensure you are using a valid and active API token. Set it either via the `API_TOKEN` environment variable or by passing `api_token='YOUR_API_TOKEN'` when initializing the client.\n\nExample:\n```python\nimport os\nfrom prelude_python_sdk import Prelude\n\nclient = Prelude(api_token=os.environ.get(\"API_TOKEN\"))\n# Or directly:\n# client = Prelude(api_token=\"YOUR_PRELUDE_API_TOKEN\")\n```","cause":"The API token provided is invalid, expired, or missing, resulting in a 401 Unauthorized HTTP status code from the Prelude API.","error":"prelude_python_sdk.AuthenticationError: Authentication failed"},{"fix":"Check your internet connection and ensure that the Prelude API endpoint is reachable. Review any firewall or proxy settings that might be blocking the connection. You can also inspect the `__cause__` attribute of the exception for the underlying `httpx` error for more details.","cause":"The client was unable to establish a network connection to the Prelude API, possibly due to network issues, DNS problems, or a timeout.","error":"prelude_python_sdk.APIConnectionError: The server could not be reached"},{"fix":"Review the API method documentation and ensure all required parameters are provided with correct data types and formats. For instance, verify phone numbers are in E.164 format or UUIDs are valid.","cause":"The request sent to the Prelude API contained invalid or missing parameters, or the data was not in the expected format, resulting in a 400 Bad Request HTTP status code.","error":"prelude_python_sdk.BadRequestError: The request was malformed"},{"fix":"Implement exponential backoff or another rate-limiting strategy in your application to reduce the frequency of API calls. The Prelude SDK automatically retries certain errors, including 429, by default, but you might need to adjust `max_retries` or your application's call pattern.","cause":"Your application has exceeded the allowed rate limits for making requests to the Prelude API, causing the API to return a 429 Too Many Requests HTTP status code.","error":"prelude_python_sdk.RateLimitError: A 429 status code was received"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.13.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://prelude.so","github":"https://github.com/prelude-so/python-sdk","docs":null,"changelog":null,"pypi":"https://pypi.org/project/prelude-python-sdk/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","serialization","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}