Onfido Python Library

The official Python library for integrating with the Onfido API.

Documentation is available at https://documentation.onfido.com.

This version uses Onfido API v3.6. Refer to our API versioning guide for details. It explains which client library versions use which versions of the API.

Build Status

Installation & Usage

Requirements

Python 3.9+

Installation

Pip

If the Python package is hosted on a repository, you can install it directly using:

pip install onfido-python

Then import the package:

import onfido

Poetry

poetry add onfido-python

Then import the package:

import onfido

Tests

Execute pytest to run the tests.

Getting Started

Import the DefaultApi object, this is the main object used for interfacing with the API:

import onfido

import urllib3
from os import environ

configuration = onfido.Configuration(
    api_token=environ['ONFIDO_API_TOKEN'],
    region=onfido.configuration.Region.EU,     # Supports `EU`, `US` and `CA`
    timeout=urllib3.util.Timeout(connect=60.0, read=60.0)
  )

with onfido.ApiClient(configuration) as api_client:
  onfido_api = onfido.DefaultApi(api_client)
  ...

You can also authenticate using OAuth2 client credentials instead of an API token:

configuration = onfido.Configuration(
    oauth_client_id=environ['ONFIDO_OAUTH_CLIENT_ID'],
    oauth_client_secret=environ['ONFIDO_OAUTH_CLIENT_SECRET'],
    region=onfido.configuration.Region.EU,
    timeout=urllib3.util.Timeout(connect=60.0, read=60.0)
  )

with onfido.ApiClient(configuration) as api_client:
  onfido_api = onfido.DefaultApi(api_client)
  ...

The client will automatically exchange credentials for an access token and refresh it when it expires.

NB: by default, timeout values are set to 30 seconds. You can change the default timeout values by setting the timeout parameter in the Configuration object, as shown in the example above.

Making a call to the API

  try:
    applicant = onfido_api.create_applicant(
        onfido.ApplicantBuilder(
          first_name= 'First',
          last_name= 'Last')
      )

    # To access the information access the desired property on the object, for example:
    applicant.first_name

    # ...

  except OpenApiException:
    # ...
    pass
  except Exception:
    # ...
    pass

Specific exception types are defined into exceptions.py.

Webhook event verification

Webhook events payload needs to be verified before it can be accessed. Verifying webhook payloads is crucial for security reasons, as it ensures that the payloads are indeed from Onfido and have not been tampered with. The library allows you to easily decode the payload and verify its signature before returning it as an object for user convenience:

  try:
    verifier = onfido.WebhookEventVerifier(os.environ["ONFIDO_WEBHOOK_SECRET_TOKEN"])

    signature = "a0...760e"

    event = verifier.read_payload('{"payload":{"r...3"}}', signature)
  except onfido.OnfidoInvalidSignatureError:
    # Invalid webhook signature
    pass

Recommendations

Do not use additional properties

Except for accessing Task object's outputs, avoid using the additional_properties dictionary to access undefined properties to prevent breaking changes when these fields appear.

Contributing

This library is automatically generated using OpenAPI Generator (version: 7.16.0); therefore, all contributions (except test files) should target the Onfido OpenAPI specification repository instead of this repository. Please follow the contribution guidelines provided in the OpenAPI specification repository.

For contributions to the tests instead, please follow the steps below:

Fork the repository
Create your feature branch (git checkout -b my-new-feature)
Make your changes
Commit your changes (git commit -am 'Add detailed description of the feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

Versioning policy

Versioning helps manage changes and ensures compatibility across different versions of the library.

Semantic Versioning policy is used for library versioning, following the guidelines and limitations outlined below:

MAJOR versions (x.0.0) may:
- target a new API version
- include non-backward compatible change
MINOR versions (0.x.0) may:
- add a new functionality, non-mandatory parameter or property
- deprecate an old functionality
- include non-backward compatible change to a functionality which is:
  - labelled as alpha or beta
  - completely broken and not usable
PATCH version (0.0.x) will:
- fix a bug
- include backward compatible changes only

Support

Should you encounter any technical issues during integration, please contact Onfido's Customer Support team via the Customer Experience Portal which also includes support documentation.

Metadata

Release files for onfido-python 6.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for onfido-python 6.2.0
File	Size	Uploaded
onfido_python-6.2.0.tar.gz	156.7 kB	May 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for onfido-python 6.2.0
File	Interpreter	ABI	Platform	Reset
onfido_python-6.2.0-py3-none-any.whl 554.6 kB May 21, 2026	Python 3	none	any	Details

Total release size: 711.3 kB

Release files / onfido_python-6.2.0.tar.gz

Download URL	onfido_python-6.2.0.tar.gz
Size	156.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`6d198997d21cf1c4e87869ce2a58d54f4646b98da5fca7a627170f478e0bc567`
BLAKE2b-256 checksum How to use checksums	`a50efea6bec8e809a486b4bc6ba52559f3c52cb28c822afd1c99ee40a3e7d5c1`
Upload date	May 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Release files / onfido_python-6.2.0-py3-none-any.whl

Download URL	onfido_python-6.2.0-py3-none-any.whl
Size	554.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`44488158ae640db33e29903971f19f770dd6ddde0a3f24cb846d07185be3ab3e`
BLAKE2b-256 checksum How to use checksums	`46bb8ae65a42ffead77fff760126c27564edf31033ad00938e555a98d1436c8f`
Upload date	May 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`