Onfido Python SDK

Warnings

• breaking 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`.
  Fix: Uninstall the old `onfido` package if present (`pip uninstall onfido`). Always install and use `onfido-python`.
• breaking 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.
  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.
• breaking 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.
  Fix: Upgrade your Python environment to version 3.9 or later.
• gotcha 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.
  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.
• gotcha 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.
  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`.

Install

• pip install onfido-python Install with pip

Imports

• DefaultApi

  import onfido
  
  onfido_api = onfido.DefaultApi(onfido.ApiClient(onfido.Configuration(...)))

  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

Quickstart

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}")