Install & Compatibility
Where this runs
tested against v6.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 4.194s · 43.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.5s · import 3.946s · 43MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DefaultApi
✓ import onfido
onfido_api = onfido.DefaultApi(onfido.ApiClient(onfido.Configuration(...)))
✗ from onfido import Api
api = Api(api_token)
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.
WebhookEventVerifier
✓ from onfido import WebhookEventVerifier
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.
import onfido
import urllib3
import os
# Ensure ONFIDO_API_TOKEN is set in your environment
ONFIDO_API_TOKEN = os.environ.get('ONFIDO_API_TOKEN', 'YOUR_API_TOKEN_HERE')
# Configure the Onfido API client
configuration = onfido.Configuration(
api_token=ONFIDO_API_TOKEN,
region=onfido.configuration.Region.EU, # Or US, CA, or custom base_url
timeout=urllib3.util.Timeout(connect=60.0, read=60.0)
)
with onfido.ApiClient(configuration) as api_client:
onfido_api = onfido.DefaultApi(api_client)
try:
# Create an applicant
applicant = onfido_api.create_applicant(
onfido.ApplicantBuilder(
first_name='John',
last_name='Doe'
)
)
print(f"Created Applicant ID: {applicant.id}")
# Example: Retrieve the applicant
retrieved_applicant = onfido_api.find_applicant(applicant.id)
print(f"Retrieved Applicant Name: {retrieved_applicant.first_name} {retrieved_applicant.last_name}")
except onfido.ApiException as e:
print(f"Onfido API Error: {e.body}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingThe `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`.fixUninstall the old `onfido` package if present (`pip uninstall onfido`). Always install and use `onfido-python`.
affects: <=4.x.x of onfido-python, all versions of the old 'onfido' package
breakingVersion 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.fixRefactor 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.
affects: >=5.0.0
breakingAs 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.fixUpgrade your Python environment to version 3.9 or later.
affects: >=5.4.0
gotchaWhen 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.fixPass 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.
affects: All versions
gotchaThis 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.fixFor 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`.
affects: All versions
Errors
Common errors & fixes
AttributeError: 'DocumentProperties' object has no attribute 'driving_license'
In onfido-python v6.0.0, specific driving license information was moved from the general `DocumentProperties` class to a new `DocumentPropertiesWithDrivingLicenceInformation` class, making the old attribute inaccessible.
fixUpdate your code to instantiate and use `onfido.DocumentPropertiesWithDrivingLicenceInformation` when dealing with documents that contain driving license data, and access relevant fields from this new object instead.
ModuleNotFoundError: No module named 'onfido'
The `onfido-python` library is either not installed in your environment, or there is an import conflict with an older, superseded `onfido` package that should be uninstalled.
fixFirst, ensure `onfido-python` is correctly installed using `pip install onfido-python`. If the issue persists, check for and uninstall any older `onfido` package (e.g., `pip uninstall onfido`) to avoid conflicts.
onfido.exceptions.OpenApiException: (401) Reason: Unauthorized
This error typically occurs when the API token provided in the `onfido.Configuration` is invalid, missing, revoked, or is a sandbox token being used in a live environment (or vice-versa).
fixVerify that your API token is correct, active, and corresponds to the environment (sandbox or live) you are trying to access. Ensure it is passed correctly to the `api_token` parameter of `onfido.Configuration`.
The following reports have not been enabled for your account: identity.
Your Onfido account is not configured to use the specific report type you are requesting (e.g., 'identity'). Onfido accounts often have a limited set of reports enabled by default.
fixContact Onfido's client support (`client-support@onfido.com`) to request the activation of the necessary report types (such as 'identity') for your account.
Upgrade
Version history
6.2.0latest on PyPI · released May 21, 2026
Audit
Dependencies
python-dateutilrequiredRequired for date/time parsing in API responses.
pydanticrequiredUsed for data validation and serialization of models.
urllib3requiredHTTP client library, used for making API requests and configuring timeouts.