Onfido Python Client Library

Version 1.1.1

The official wrapper for Onfido's API. Refer to the full API documentation for details of expected requests and responses.

This project supersedes the automatically generated api-python-client library (onfido in PyPI).

Installation

pip install onfido-python

:warning: Having the old onfido package installed at the same time will cause errors.

Usage

Make API calls by using an instance of the Api class and providing your API token:

import onfido

api = onfido.Api("<YOUR_API_TOKEN>")

Regions

Set the region in the API instance using the base_url parameter.

The library will use the default base URL (api.onfido.com) for the EU region, if no region is specified.

To specify the US region do:

from onfido.regions import Region

api = onfido.Api("<YOUR_API_TOKEN>", base_url=Region.US)

To specify the CA region do:

from onfido.regions import Region

api = onfido.Api("<YOUR_API_TOKEN>", base_url=Region.CA)

See https://documentation.onfido.com/#regions for supported regions.

Response format

The Python library will return data directly from the API.

See https://documentation.onfido.com/#request,-response-format for more information.

Resources

All resources share the same interface when making API calls. For example, use .create to create a resource, .find to find one, and .all to fetch all resources.

Applicants

Applicants are the object upon which Onfido checks are performed.

api.applicant.create(params)  # => Creates an applicant
api.applicant.update("<APPLICANT_ID>", params)  # => Updates an applicant
api.applicant.delete("<APPLICANT_ID>")  # => Schedule an applicant for deletion
api.applicant.restore("<APPLICANT_ID>") # => Restore an applicant scheduled for deletion
api.applicant.find("<APPLICANT_ID>")  # => Finds a single applicant
api.applicant.all()  # => Returns all applicants

applicant.all() takes the following optional arguments:

include_deleted=true: include applicants scheduled for deletion. per_page: set the number of results per page. Defaults to 20. page: return specific pages. Defaults to 1.

Note: Calling api.applicant.delete adds the applicant and all associated documents, photos, videos, checks, reports and analytics data to our deletion queue. Please read https://documentation.onfido.com/#delete-applicant for more information.

Documents

Some report types require identity documents (passport, driving licence etc.) in order to be processed.

request_body = {"applicant_id": "<APPLICANT_ID>", "type": "passport"}
sample_file = open("<FILE_NAME>", "rb")

api.document.upload(sample_file, request_body)   # => Uploads a document
api.document.find("<DOCUMENT_ID>")      # => Finds a document
api.document.download("<DOCUMENT_ID>")  # => Downloads a document as a binary data
api.document.all("<APPLICANT_ID>")      # => Returns all documents belonging to an applicant

See https://documentation.onfido.com/#document-types for example document types.

Live Photos

Live photos are images of the applicant’s face, typically taken at the same time as documents are provided. These photos are used to perform Facial Similarity Photo reports on the applicant.

request_body = {"applicant_id": "<APPLICANT_ID>", "advanced_validation": "True"}
sample_file = open("<FILE_NAME>", "rb")

api.live_photo.upload(sample_file, request_body)   # => Uploads a live photo
api.live_photo.find("<LIVE_PHOTO_ID>")      # => Finds a live photo
api.live_photo.download("<LIVE_PHOTO_ID>")  # => Downloads a live photo as binary data
api.live_photo.all("<APPLICANT_ID>")        # => Returns all live photos belonging to an applicant

Checks

Checks are performed on an applicant. Depending on the type of check you wish to perform, different information will be required when you create an applicant. A check consists of one or more reports.

request_body = {"applicant_id": "12345", "report_names": ["document", "facial_similarity_photo"]}

api.check.create(request_body) # => Creates a check
api.check.find("<CHECK_ID>")    # => Finds a check
api.check.resume("<CHECK_ID>")  # => Resumes a paused check
api.check.all("<APPLICANT_ID>") # => Returns all an applicant's checks

Reports

Reports provide details of the results of some part of a check. They are created when a check is created, so the Onfido API only provides support for finding and listing them. For paused reports specifically, additional support for resuming and cancelling reports is also available.

api.report.find("<REPORT_ID>")    # => Finds a report
api.report.resume("<REPORT_ID>")  # => Resumes a paused report
api.report.all("<CHECK_ID>")      # => Returns all the reports in a check
api.report.cancel("<REPORT_ID>")  # => Cancels a paused report

Address Lookups

Onfido provides an address lookup service, to help ensure well-formatted addresses are provided when creating applicants. To search for addresses by postcode, use:

api.address.pick("SW46EH") # => Returns all addresses in a given postcode

Webhook Endpoints

Onfido allows you to set up and view your webhook endpoints via the API, as well as through the Dashboard.

request_body = {
  "url": "https://<URL>",
  "events": [
    "report.completed",
    "check.completed"
  ]
}

api.webhook.create(request_body) # => Registers a webhook
api.webhook.find("<WEBHOOK_ID>")  # => Finds a single webhook
api.webhook.edit("<WEBHOOK_ID>", new_webhook_details) # => Edits a webhook
api.webhook.delete("<WEBHOOK_ID>") # => Deletes a webhook
api.webhook.all() # => Returns all webhooks

Webhook Verification

A webhook event is valid if the signature from the header is equal to the expected signature you compute for it.

event = verifier.read_payload(raw_event, signature)

See https://documentation.onfido.com/#verifying-webhook-signatures for more information.

SDK Tokens

Onfido allows you to generate JSON Web Tokens via the API in order to authenticate with Onfido's SDKs.

request_body = {"applicant_id": "<APPLICANT_ID>", "application_id": "<APPLICATION_ID>"}

api.sdk_token.generate(request_body) # => Creates an SDK token

Extraction (Autofill)

Extract data from documents. This endpoint only returns extracted data that can be used for automatic form filling. You must provide the ID of a document that has already been uploaded.

api.extraction.perform("<DOCUMENT_ID>") # => Returns data extracted from the document

Error Handling

OnfidoServerError is raised whenever Onfido returns a 5xx response
OnfidoRequestError is raised whenever Onfido returns a 4xx response
OnfidoInvalidSignatureError is raised whenever a signature from the header is not equal to the expected signature you compute for it
OnfidoTimeoutError is raised if a timeout occurs
OnfidoConnectionError is raised whenever any other network error occurs
OnfidoUnknownError is raised whenever something unexpected happens

Contributing

Fork it ( https://github.com/onfido/onfido-python/fork )
Create your feature branch (git checkout -b my-new-feature)
Run the tests (poetry run pytest tests/test_my_new_feature.py)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

Metadata

Release files for onfido-python 1.1.1

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 1.1.1
File	Size	Uploaded	Provenance
onfido-python-1.1.1.tar.gz	11.4 kB	Oct 22, 2020	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for onfido-python 1.1.1
File	Interpreter	ABI	Platform	Reset
onfido_python-1.1.1-py3-none-any.whl 12.2 kB Oct 22, 2020 Without provenance	Python 3	none	any	Details

Total release size: 23.6 kB

Release files / onfido-python-1.1.1.tar.gz

Download URL	onfido-python-1.1.1.tar.gz
Size	11.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`032374bd617cd9a1c15c87ad886c8432fe2179af02c3f7dc9af8ac55d7c33174`
BLAKE2b-256 checksum How to use checksums	`3048969defd2778855b8a40f2d3f5b338824bafcedc42339732dd5d2dd5a2d40`
Upload date	Oct 22, 2020
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.0.10 CPython/3.8.6 Darwin/19.6.0`

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

Download URL	onfido_python-1.1.1-py3-none-any.whl
Size	12.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5ad243cd53183afdb08196fca691c68cdf69c7637317d102f95590559b58d86c`
BLAKE2b-256 checksum How to use checksums	`b444e896a8a231a385728c0bd262fafa21b6040f1adb11c02e0c1444bb0881e6`
Upload date	Oct 22, 2020
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.0.10 CPython/3.8.6 Darwin/19.6.0`

Security for onfido-python 1.1.1

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.