{"id":4145,"library":"onfido-python","title":"Onfido Python SDK","description":"The official Python library for integrating with the Onfido API. This version (6.0.0) is built using OpenAPI Generator and currently uses Onfido API v3.6. It is actively maintained and frequently updated in line with the Onfido OpenAPI specification, with major versions often introducing non-backward compatible changes.","status":"active","version":"6.0.0","language":"en","source_language":"en","source_url":"https://github.com/onfido/onfido-python","tags":["identity-verification","kyc","api-client","openapi","security"],"install":[{"cmd":"pip install onfido-python","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for date/time parsing in API responses.","package":"python-dateutil","optional":false},{"reason":"Used for data validation and serialization of models.","package":"pydantic","optional":false},{"reason":"HTTP client library, used for making API requests and configuring timeouts.","package":"urllib3","optional":false}],"imports":[{"note":"The `onfido-python` library (post v5.0.0) uses a `Configuration` -> `ApiClient` -> `DefaultApi` pattern due to being auto-generated by OpenAPI Generator. The old `onfido` package (superseded) and earlier versions of `onfido-python` used a simpler `onfido.Api(api_token)` client instantiation.","wrong":"from onfido import Api\napi = Api(api_token)","symbol":"DefaultApi","correct":"import onfido\n\nonfido_api = onfido.DefaultApi(onfido.ApiClient(onfido.Configuration(...)))"},{"symbol":"WebhookEventVerifier","correct":"from onfido import WebhookEventVerifier"}],"quickstart":{"code":"import onfido\nimport urllib3\nimport os\n\n# Ensure ONFIDO_API_TOKEN is set in your environment\nONFIDO_API_TOKEN = os.environ.get('ONFIDO_API_TOKEN', 'YOUR_API_TOKEN_HERE')\n\n# Configure the Onfido API client\nconfiguration = onfido.Configuration(\n    api_token=ONFIDO_API_TOKEN,\n    region=onfido.configuration.Region.EU, # Or US, CA, or custom base_url\n    timeout=urllib3.util.Timeout(connect=60.0, read=60.0)\n)\n\nwith onfido.ApiClient(configuration) as api_client:\n    onfido_api = onfido.DefaultApi(api_client)\n\n    try:\n        # Create an applicant\n        applicant = onfido_api.create_applicant(\n            onfido.ApplicantBuilder(\n                first_name='John',\n                last_name='Doe'\n            )\n        )\n        print(f\"Created Applicant ID: {applicant.id}\")\n\n        # Example: Retrieve the applicant\n        retrieved_applicant = onfido_api.find_applicant(applicant.id)\n        print(f\"Retrieved Applicant Name: {retrieved_applicant.first_name} {retrieved_applicant.last_name}\")\n\n    except onfido.ApiException as e:\n        print(f\"Onfido API Error: {e.body}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"Initializes the Onfido API client with an API token and region, then demonstrates how to create and retrieve an applicant. The API token should be provided via an environment variable for security. Default timeouts are 30 seconds but can be customized."},"warnings":[{"fix":"Uninstall the old `onfido` package if present (`pip uninstall onfido`). Always install and use `onfido-python`.","message":"The `onfido` PyPI package (`onfido/api-python-client` GitHub repository) is obsolete and has been superseded by `onfido-python`. Installing both can lead to import conflicts and unexpected errors. Ensure you are using `onfido-python`.","severity":"breaking","affected_versions":"<=4.x.x of onfido-python, all versions of the old 'onfido' package"},{"fix":"Refactor API client initialization to use `onfido.Configuration`, `onfido.ApiClient`, and `onfido.DefaultApi`. Consult the library's `README.md` and Onfido's API documentation for the latest usage patterns.","message":"Version 5.0.0 of `onfido-python` introduced significant breaking changes to the API client's instantiation and usage. The client is now auto-generated via OpenAPI Generator, requiring `onfido.Configuration`, `onfido.ApiClient`, and `onfido.DefaultApi` instead of the former simpler `onfido.Api(token)` pattern. Object structures and method signatures may also have changed.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade your Python environment to version 3.9 or later.","message":"As of version 5.4.0, `onfido-python` officially dropped support for Python 3.8 and now requires Python 3.9 or higher. Installing on older Python versions may lead to unexpected behavior or installation failures.","severity":"breaking","affected_versions":">=5.4.0"},{"fix":"Pass the raw, unparsed HTTP request body (as a string) to `onfido.WebhookEventVerifier.read_payload()` along with the `X-SHA2-Signature` header and your webhook secret token.","message":"When verifying webhook signatures, it is crucial to use the *raw* event request body, not a pre-parsed JSON object. Parsing can reorder fields, causing signature verification to fail. The library provides `onfido.WebhookEventVerifier` for secure verification.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For feature requests or bug fixes that involve API changes, contribute to the OpenAPI specification repository. For client-specific issues (e.g., test failures, build issues), contribute to `onfido-python`.","message":"This library is automatically generated from the Onfido OpenAPI specification. Therefore, direct code contributions (except for test files) should target the `onfido/onfido-openapi-spec` repository, not this `onfido-python` repository, to ensure consistency and prevent changes from being overwritten.","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"}