### Install Onfido Python Library using Poetry

Source: https://github.com/onfido/onfido-python/blob/master/README.md

Install the library using Poetry. Ensure Python 3.9+ is used.

```sh
poetry add onfido-python
```

--------------------------------

### Complete Onfido Verification Workflow Example

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/README.md

This example demonstrates the full lifecycle of an Onfido verification, from creating an applicant to uploading documents and selfies, initiating a check, and retrieving report results. Ensure your ONFIDO_API_TOKEN environment variable is set.

```python
import onfido
from datetime import date
import os

# Configure
config = onfido.Configuration(
    api_token=os.environ['ONFIDO_API_TOKEN']
)

# Create API client
with onfido.ApiClient(config) as client:
    api = onfido.DefaultApi(client)
    
    # Create applicant
    applicant_builder = onfido.ApplicantBuilder(
        first_name='John',
        last_name='Doe',
        email='john@example.com',
        dob=date(1990, 1, 1)
    )
    applicant = api.create_applicant(applicant_builder)
    
    # Upload document
    with open('passport.pdf', 'rb') as f:
        document = api.upload_document(
            applicant.id,
            'passport',
            f.read(),
            'GB'
        )
    
    # Upload selfie
    with open('selfie.jpg', 'rb') as f:
        live_photo = api.upload_live_photo(applicant.id, f.read())
    
    # Create check
    check_builder = onfido.CheckBuilder(
        report_names=['document', 'facial_similarity_photo']
    )
    check = api.create_check(applicant.id, check_builder)
    
    # Wait for webhook or poll
    # ... handle check.completed webhook ...
    
    # Get report
    reports = api.list_reports(applicant.id)
    for report in reports.reports:
        print(f"{report.name}: {report.result}")
```

--------------------------------

### Instantiate ApiClient and DefaultApi

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/client-and-configuration.md

After configuring the client, instantiate an ApiClient and then the DefaultApi to interact with the Onfido API. This example uses a context manager for the ApiClient.

```python
with onfido.ApiClient(configuration) as api_client:
    api = onfido.DefaultApi(api_client)
    # Use api...
```

--------------------------------

### Install Onfido Python Library using Pip

Source: https://github.com/onfido/onfido-python/blob/master/README.md

Install the library using pip. Ensure Python 3.9+ is used.

```sh
pip install onfido-python
```

--------------------------------

### Initialize Configuration with API Token

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/client-and-configuration.md

Use this to set up the API client with an API token for authentication. Ensure the ONFIDO_API_TOKEN environment variable is set. This example also customizes the connection timeout.

```python
import onfido
import urllib3
from os import environ

# API Token Authentication
configuration = onfido.Configuration(
    api_token=environ['ONFIDO_API_TOKEN'],
    region=onfido.configuration.Region.EU,
    timeout=urllib3.util.Timeout(connect=60.0, read=60.0)
)
```

--------------------------------

### Create and Assign Address

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/builders-and-models.md

Example of creating an AddressBuilder instance and assigning it to an applicant builder.

```python
address = onfido.AddressBuilder(
    street='123 Main Street',
    town='London',
    postal_code='SW1A 1AA',
    country='GB'
)

applicant_builder.address = address
```

--------------------------------

### Production Setup for Onfido SDK

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/README.md

Configure the Onfido SDK for production with OAuth credentials, a specific region, SSL verification, a custom CA certificate path, and retry attempts.

```python
config = Configuration(
    oauth_client_id=os.getenv('ONFIDO_OAUTH_CLIENT_ID'),
    oauth_client_secret=os.getenv('ONFIDO_OAUTH_CLIENT_SECRET'),
    region=Region.US,
    verify_ssl=True,
    ssl_ca_cert='/etc/ssl/certs/ca-bundle.crt',
    retries=3
)
```

--------------------------------

### API Token Authentication Flow

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/README.md

Demonstrates the setup for API token authentication using the Configuration class. This method is straightforward, with the token included in every request header.

```python
Configuration(api_token='...')
    → ApiClient
    → Every request includes Token header
```

--------------------------------

### Import Onfido Library after Pip Installation

Source: https://github.com/onfido/onfido-python/blob/master/README.md

Import the onfido package after installation.

```python
import onfido
```

--------------------------------

### Create Applicant

Source: https://github.com/onfido/onfido-python/blob/master/README.md

Example of creating a new applicant using the `create_applicant` method. It shows how to use `ApplicantBuilder` to set applicant details and how to access the created applicant's properties.

```APIDOC
## Create Applicant

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

  # Access applicant information
  print(applicant.first_name)

except onfido.OpenApiException:
  # Handle Onfido API specific exceptions
  pass
except Exception:
  # Handle other general exceptions
  pass
```

### Description

This snippet demonstrates how to create an applicant using the `create_applicant` method of the `DefaultApi` client. An `ApplicantBuilder` is used to construct the applicant's data, such as first and last name. The response is an `Applicant` object, and its properties can be accessed directly. Error handling for `OpenApiException` and general exceptions is included.
```

--------------------------------

### Get Default Configuration

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Retrieve the currently set global default configuration for the Onfido SDK.

```python
# Get the current default
config = onfido.Configuration.get_default()
```

--------------------------------

### Get Default Configuration

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/client-and-configuration.md

Retrieves the currently set default Configuration instance. If no default configuration has been set, it will create and return a new one.

```python
config = onfido.Configuration.get_default()
```

--------------------------------

### Webhook Event Verification Example

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/webhooks.md

Integrates webhook signature verification into a Flask application. Ensure the ONFIDO_WEBHOOK_SECRET_TOKEN environment variable is set.

```python
import onfido
import os
from flask import Flask, request

app = Flask(__name__)
webhook_token = os.environ['ONFIDO_WEBHOOK_SECRET_TOKEN']
verifier = onfido.WebhookEventVerifier(webhook_token)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    try:
        raw_payload = request.get_data(as_text=True)
        signature = request.headers.get('X-Signature')
        
        event = verifier.read_payload(raw_payload, signature)
        
        # Process event
        if event.type == 'check.completed':
            print(f"Check completed for applicant: {event.payload.object.applicant_id}")
        
        return {'status': 'ok'}, 200
        
    except onfido.OnfidoInvalidSignatureError:
        print("Invalid webhook signature")
        return {'error': 'Invalid signature'}, 401
    except Exception as e:
        print(f"Error processing webhook: {e}")
        return {'error': 'Internal error'}, 500
```

--------------------------------

### Comprehensive API Error Handling in Python

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/errors.md

A complete example demonstrating how to handle various Onfido API exceptions, including authentication, bad requests, not found, service errors, and general API or unexpected errors.

```python
import onfido
from onfido.exceptions import (
    OpenApiException,
    BadRequestException,
    UnauthorizedException,
    NotFoundException,
    ServiceException
)

try:
    configuration = onfido.Configuration(api_token=api_token)
    with onfido.ApiClient(configuration) as api_client:
        api = onfido.DefaultApi(api_client)
        
        builder = onfido.ApplicantBuilder(
            first_name='John',
            last_name='Doe'
        )
        applicant = api.create_applicant(builder)
        
except UnauthorizedException:
    print("Invalid API token or expired OAuth credential")
except BadRequestException as e:
    print(f"Invalid request: {e.body}")
except NotFoundException:
    print("Resource not found")
except ServiceException as e:
    print(f"Server error: {e.reason}")
    # Implement exponential backoff retry
except OpenApiException as e:
    print(f"Unexpected API error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")
```

--------------------------------

### Error Handling with Exceptions

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/INDEX.md

This example shows how to implement robust error handling using try-except blocks to catch specific API exceptions like BadRequestException, UnauthorizedException, and ServiceException for appropriate responses.

```python
try:
  api.create_applicant()
except BadRequestException:
  # handle validation
except UnauthorizedException:
  # handle auth
except ServiceException:
  # retry with backoff
```

--------------------------------

### Initialize Configuration with OAuth2 Client Credentials

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/client-and-configuration.md

This snippet demonstrates setting up the API client using OAuth2 client ID and secret. Make sure to set the ONFIDO_OAUTH_CLIENT_ID and ONFIDO_OAUTH_CLIENT_SECRET environment variables.

```python
# OAuth2 Client Credentials Authentication
configuration = onfido.Configuration(
    oauth_client_id=environ['ONFIDO_OAUTH_CLIENT_ID'],
    oauth_client_secret=environ['ONFIDO_OAUTH_CLIENT_SECRET'],
    region=onfido.configuration.Region.US,
)
```

--------------------------------

### Initialize ApiClient with Configuration

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/client-and-configuration.md

Instantiate the ApiClient with a custom configuration, often used within a 'with' statement for automatic resource management. Requires importing the onfido library and creating a Configuration object with your API token.

```python
import onfido

# Using with statement for automatic cleanup
configuration = onfido.Configuration(api_token='your_token')
with onfido.ApiClient(configuration) as api_client:
    api = onfido.DefaultApi(api_client)
    applicant = api.create_applicant(
        onfido.ApplicantBuilder(first_name='John', last_name='Doe')
    )
```

--------------------------------

### Processing a Check Completed Webhook

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/webhooks.md

Example of how to read and process a 'check.completed' webhook event using the Onfido SDK.

```python
event = verifier.read_payload(raw_payload, signature)

if event.type == 'check.completed':
    applicant_id = event.payload.object.applicant_id
    check_id = event.payload.object.id
    
    # Fetch the check to get results
    check = api.find_check(applicant_id, check_id)
    
    if check.status == 'complete':
        # Get reports
        reports = api.list_reports(applicant_id)
        for report in reports.reports:
            print(f"{report.name}: {report.result}")
```

--------------------------------

### Configure Proxy Parameters

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Set up proxy server details, including the URL and any necessary authentication headers. This is useful for routing requests through a proxy.

```python
configuration = onfido.Configuration(
    proxy='http://proxy.example.com:8080',
    proxy_headers={'Proxy-Auth': 'token'},
)
```

--------------------------------

### Retrieve Report with Onfido Python SDK

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/README.md

Get detailed results and breakdown for a specific report associated with a check.

```python
report = api.find_report(applicant_id, report_id)
print(f"Result: {report.result}")  # 'clear', 'consider', 'unknown'
print(f"Breakdown: {report.breakdown}")  # Detailed reasons
```

--------------------------------

### Initialize Onfido API Client

Source: https://github.com/onfido/onfido-python/blob/master/README.md

Demonstrates how to initialize the Onfido API client using either an API token or OAuth2 client credentials. It also shows how to configure the region and timeout.

```APIDOC
## Initialize API Client with API Token

```python
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)
  # ... API calls can be made here
```

## Initialize API Client with OAuth2

```python
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)
  # ... API calls can be made here
```

### Description

This section shows how to set up the `onfido` client. You can authenticate using either an API token or OAuth2 client credentials. The `Configuration` object allows you to specify the API region and custom timeout values for connections and reads. The `DefaultApi` object is then instantiated with an `ApiClient` configured with these settings.
```

--------------------------------

### Create and Use ApplicantBuilder

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/builders-and-models.md

Demonstrates how to instantiate an ApplicantBuilder with personal details and use it to create an applicant via the API. Ensure necessary imports like `date` are included.

```python
from datetime import date

builder = onfido.ApplicantBuilder(
    first_name='John',
    last_name='Doe',
    email='john.doe@example.com',
    dob=date(1990, 5, 15),
    phone_number='+44 7700 900000'
)

applicant = api.create_applicant(builder)
```

--------------------------------

### Default ApiClient Management

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/client-and-configuration.md

Provides methods to get the default ApiClient instance or set a custom default instance for the SDK.

```APIDOC
### Class Methods

#### get_default() -> ApiClient

Returns the default ApiClient instance or creates one if not set.

```python
client = onfido.ApiClient.get_default()
```

#### set_default(default: ApiClient) -> None

Sets the default ApiClient instance used by the SDK.

```python
onfido.ApiClient.set_default(api_client)
```
```

--------------------------------

### SDK Structure Overview

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/README.md

Illustrates the directory structure of the Onfido Python SDK, highlighting key modules and their organization.

```tree
onfido/
├── __init__.py                  # Package exports
├── api_client.py                # HTTP client
├── api_response.py              # Response wrapper
├── configuration.py             # Configuration class
├── exceptions.py                # Exception definitions
├── webhook_event_verifier.py    # Webhook verification
├── api/
│   └── default_api.py          # Main API methods (~21,000 lines)
└── models/                      # 200+ data model classes
```

--------------------------------

### Generate SDK Token

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/default-api.md

Generates a token for the Onfido Web SDK. This token is required to initialize the SDK and start the verification process.

```APIDOC
## generate_sdk_token

### Description
Generate a token for the Onfido Web SDK.

### Method Signature
```python
def generate_sdk_token(
    self,
    sdk_token_builder: SdkTokenBuilder,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _content_type: Optional[str] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> SdkToken
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **sdk_token_builder** (SdkTokenBuilder) - Required - Token configuration with applicant_id

#### Other Parameters
- **_request_timeout** (float or (float, float)) - Optional - Request timeout
- **_request_auth** (Dict[str, Any]) - Optional - Override authentication
- **_content_type** (str) - Optional - Override Content-Type
- **_headers** (Dict[str, Any]) - Optional - Custom headers
- **_host_index** (int) - Optional - Host index

### Response
#### Success Response (200)
- **SdkToken** (object) - An object containing the token string.

### Response Example
```json
{
  "token": "your_sdk_token_here"
}
```

### Request Example
```python
token_builder = onfido.SdkTokenBuilder(applicant_id=applicant_id)
sdk_token = api.generate_sdk_token(token_builder)
print(sdk_token.token)
```
```

--------------------------------

### Configure Onfido SDK with Environment Variables

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/README.md

Initialize the Onfido SDK configuration using environment variables for the API token and specifying the region.

```python
import os
from onfido import Configuration, Region

config = Configuration(
    api_token=os.getenv('ONFIDO_API_TOKEN'),
    region=Region.EU
)
```

--------------------------------

### Create Configuration from Environment Variables

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Create an Onfido SDK configuration by reading credentials and settings from environment variables. Supports API token or OAuth client ID/secret, and region selection. Optionally configures SSL certificate paths or data.

```python
import onfido
import os
from pathlib import Path

def create_configuration():
    """Create configuration from environment variables."""
    
    api_token = os.getenv('ONFIDO_API_TOKEN')
    oauth_client_id = os.getenv('ONFIDO_OAUTH_CLIENT_ID')
    oauth_client_secret = os.getenv('ONFIDO_OAUTH_CLIENT_SECRET')
    region_str = os.getenv('ONFIDO_REGION', 'eu').upper()
    
    # Determine region
    region_map = {
        'EU': onfido.configuration.Region.EU,
        'US': onfido.configuration.Region.US,
        'CA': onfido.configuration.Region.CA,
    }
    region = region_map.get(region_str, onfido.configuration.Region.EU)
    
    # Choose auth method
    if oauth_client_id and oauth_client_secret:
        config = onfido.Configuration(
            oauth_client_id=oauth_client_id,
            oauth_client_secret=oauth_client_secret,
            region=region,
        )
    elif api_token:
        config = onfido.Configuration(
            api_token=api_token,
            region=region,
        )
    else:
        raise ValueError("ONFIDO_API_TOKEN or ONFIDO_OAUTH_CLIENT_ID/SECRET required")
    
    # Optional: SSL certificate
    ca_cert = os.getenv('ONFIDO_CA_CERT')
    if ca_cert:
        if Path(ca_cert).exists():
            config.ssl_ca_cert = ca_cert
        else:
            config.ca_cert_data = ca_cert
    
    return config

# Usage
config = create_configuration()
with onfido.ApiClient(config) as client:
    api = onfido.DefaultApi(client)
```

--------------------------------

### Get Default ApiClient Instance

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/client-and-configuration.md

Retrieve the globally set default ApiClient instance. If no default client has been set, this method will create and return one.

```python
client = onfido.ApiClient.get_default()
```

--------------------------------

### Handle ApiTypeError

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/errors.md

Catch and handle ApiTypeError specifically, which is raised when parameter type validation fails. This example shows how to access path information for the invalid field.

```python
try:
    builder = onfido.ApplicantBuilder(
        first_name=123,  # Must be string
        last_name='Doe'
    )
except onfido.ApiTypeError as e:
    print(f"Type error at {e.path_to_item}: {e}")
```

--------------------------------

### Minimal Onfido SDK Configuration

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Sets up the Onfido SDK with a default region (EU) and a 30-second timeout. Requires an API token to be set in the environment variable ONFIDO_API_TOKEN.

```python
import onfido
import os

# Uses default region (EU) and 30s timeout
config = onfido.Configuration(
    api_token=os.environ['ONFIDO_API_TOKEN']
)

with onfido.ApiClient(config) as client:
    api = onfido.DefaultApi(client)
```

--------------------------------

### Configure with API Token

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Use this method for simple, static token authentication. Ensure your API token is kept secure.

```python
configuration = onfido.Configuration(
    api_token='your_api_token_here'
)
```

--------------------------------

### Initialize DefaultApi

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/default-api.md

Initialize the DefaultApi with an ApiClient instance. This is required before using any API methods.

```python
import onfido

configuration = onfido.Configuration(api_token='your_token')
with onfido.ApiClient(configuration) as api_client:
    api = onfido.DefaultApi(api_client)
    # Use api methods...
```

--------------------------------

### Create Applicant with Onfido Python SDK

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/README.md

Use ApplicantBuilder to create a new applicant. Requires first and last name.

```python
builder = onfido.ApplicantBuilder(first_name='John', last_name='Doe')
applicant = api.create_applicant(builder)
```

--------------------------------

### ApiClient Initialization

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/client-and-configuration.md

Initializes an ApiClient instance with optional configuration and custom headers or cookies.

```APIDOC
## ApiClient

Generic API client for making HTTP requests to the Onfido API.

### Signature

```python
class ApiClient:
    def __init__(
        self,
        configuration: Optional[Configuration] = None,
        header_name: Optional[str] = None,
        header_value: Optional[str] = None,
        cookie: Optional[str] = None
    ) -> None
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| configuration | Configuration | No | Configuration.get_default() | Configuration instance for this client |
| header_name | str | No | — | Custom header name to include in requests |
| header_value | str | No | — | Custom header value to include in requests |
| cookie | str | No | — | Cookie to include in requests |

### Returns

Returns an ApiClient instance initialized with the given configuration.

### Example

```python
import onfido

# Using with statement for automatic cleanup
configuration = onfido.Configuration(api_token='your_token')
with onfido.ApiClient(configuration) as api_client:
    api = onfido.DefaultApi(api_client)
    applicant = api.create_applicant(
        onfido.ApplicantBuilder(first_name='John', last_name='Doe')
    )
```
```

--------------------------------

### Create Workflow Run

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/advanced-operations.md

Initiates a new workflow run instance with the provided configuration.

```APIDOC
## create_workflow_run

### Description
Create a workflow run instance.

### Method
POST (assumed, based on creation)

### Endpoint
/workflows/runs (assumed)

### Parameters
#### Request Body
- **workflow_run_builder** (WorkflowRunBuilder) - Required - Workflow configuration
- **_request_timeout** (float or tuple) - Optional - Request timeout
- **_request_auth** (Dict) - Optional - Override authentication
- **_content_type** (str) - Optional - Override Content-Type
- **_headers** (Dict) - Optional - Custom headers
- **_host_index** (int) - Optional - Host index

### Request Example
```python
workflow_builder = onfido.WorkflowRunBuilder(
    workflow_id=workflow_id,
    applicant_id=applicant_id,
    custom_data={'department': 'HR'}
)

workflow_run = api.create_workflow_run(workflow_builder)
print(f"Workflow started: {workflow_run.id}")
```

### Response
#### Success Response (200)
- **WorkflowRun** (WorkflowRun) - The created WorkflowRun object.
```

--------------------------------

### Download QES Signed Document (Python)

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/media-operations.md

Use this method to download a document that has been qualified electronically signed (QES). Requires applicant and document IDs.

```python
def download_qes_document(
    self,
    applicant_id: UUID,
    document_id: UUID,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> bytes
```

--------------------------------

### Configure SSL/TLS Parameters

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Manage SSL verification, provide custom CA certificates, client certificates, and keys, or enforce hostname verification. `verify_ssl` is enabled by default.

```python
configuration = onfido.Configuration(
    verify_ssl=True,           # Enable SSL verification (default)
    ssl_ca_cert='/path/to/ca-bundle.crt',  # Custom CA cert file
    ca_cert_data='pem_or_der_data',        # Inline cert data
    cert_file='/path/to/client.crt',       # Client certificate
    key_file='/path/to/client.key',        # Client private key
    assert_hostname='example.com',         # Enable hostname verification
    tls_server_name='example.com',         # SNI value
)
```

--------------------------------

### Download Live Video - Python

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/media-operations.md

Downloads a previously recorded live video for a given applicant and video ID. The video is returned as bytes and supports MP4 and WebM formats.

```python
video_data = api.download_live_video(applicant_id, live_video_id)
with open('live_video.mp4', 'wb') as f:
    f.write(video_data)
```

--------------------------------

### Webhook Integration for Events

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/INDEX.md

This pattern demonstrates how to set up a webhook to receive event notifications, such as check completion. It includes steps for verifying the webhook signature and accessing event data.

```python
create_webhook(url)
  → [receive check.completed webhook]
  → verifier.read_payload(raw, signature)
  → access event.payload.object.id
  → find_report()
```

--------------------------------

### Configure Authentication Parameters

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Set up API token or OAuth2 credentials for authenticating with the Onfido API. Ensure you use either `api_token` or the OAuth2 pair (`oauth_client_id`, `oauth_client_secret`).

```python
configuration = onfido.Configuration(
    api_token='token_string',  # API token auth
    # OR
    oauth_client_id='client_id',      # OAuth2 auth
    oauth_client_secret='secret',     # OAuth2 auth
)
```

--------------------------------

### Force Report Creation from Watchlist Monitor

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/advanced-operations.md

Initiate the creation of a watchlist report based on an existing monitor. Returns the generated Report object.

```python
def force_report_creation_from_watchlist_monitor(
    self,
    watchlist_monitor_id: UUID,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> Report:
    pass
```

--------------------------------

### Download Signed Evidence File (Python)

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/media-operations.md

Use this method to download a specific signed evidence file as bytes. Requires applicant and check IDs.

```python
def download_signed_evidence_file(
    self,
    applicant_id: UUID,
    check_id: UUID,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> bytes
```

--------------------------------

### Download Live Photo - Python

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/media-operations.md

Downloads a live photo associated with an applicant and live photo ID. The returned bytes represent the image file content.

```python
def download_live_photo(
    self,
    applicant_id: UUID,
    live_photo_id: UUID,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> bytes
```

--------------------------------

### Onfido SDK Configuration with Logging

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Enables debug logging for the Onfido SDK and urllib3, directing logs to a specified file. Requires the ONFIDO_API_TOKEN environment variable.

```python
import onfido
import logging
import os

config = onfido.Configuration(
    api_token=os.environ['ONFIDO_API_TOKEN'],
    debug=True,
)

config.logger_file = '/var/log/onfido.log'

# Set logging level for SDK
logging.getLogger('onfido').setLevel(logging.DEBUG)
logging.getLogger('urllib3').setLevel(logging.DEBUG)

with onfido.ApiClient(config) as client:
    api = onfido.DefaultApi(client)
```

--------------------------------

### Configure Connection Parameters

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Specify a custom API host URL, select a region, and configure connection and read timeouts using `urllib3.util.Timeout`. Default timeouts apply if not specified.

```python
configuration = onfido.Configuration(
    host='https://api.custom.onfido.com',  # Custom host URL
    region=onfido.configuration.Region.EU,  # Region
    timeout=urllib3.util.Timeout(
        connect=60.0,  # Connection timeout
        read=60.0      # Read timeout
    ),
)
```

--------------------------------

### Download Evidence Folder (Python)

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/media-operations.md

Use this method to download a ZIP archive containing all evidence files for a check. Requires applicant and check IDs.

```python
def download_evidence_folder(
    self,
    applicant_id: UUID,
    check_id: UUID,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> bytes
```

--------------------------------

### Download Motion Capture - Python

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/media-operations.md

Downloads motion capture video data as bytes for a specified applicant and motion capture ID.

```python
def download_motion_capture(
    self,
    applicant_id: UUID,
    motion_capture_id: UUID,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> bytes
```

--------------------------------

### Download Check Summary (Python)

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/media-operations.md

Use this method to download a check summary as PDF bytes. Requires applicant and check IDs.

```python
def download_check(
    self,
    applicant_id: UUID,
    check_id: UUID,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> bytes
```

--------------------------------

### Set Default Configuration

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/client-and-configuration.md

This class method allows you to set a default Configuration instance that will be used by the SDK if no specific configuration is provided.

```python
onfido.Configuration.set_default(configuration)
```

--------------------------------

### Use Context Managers for API Client Lifecycle

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/README.md

Utilize context managers (`with` statement) when initializing the Onfido API client. This ensures proper cleanup of resources after the client is no longer needed.

```python
# Context manager ensures cleanup
with onfido.ApiClient(config) as client:
    api = onfido.DefaultApi(client)
    # Use api...
```

--------------------------------

### list_tasks

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/advanced-operations.md

List all available tasks.

```APIDOC
## list_tasks

### Description
List all tasks.

### Method
Not specified (likely a SDK method call)

### Endpoint
Not specified

### Parameters
#### Path Parameters
None specified.

#### Query Parameters
None specified.

#### Request Body
None specified.

### Request Example
```python
# Example usage (assuming 'client' is an initialized SDK client)
client.list_tasks()
```

### Response
#### Success Response (200)
- **TaskList** (object) - Contains a list of tasks.
```

--------------------------------

### Create a Watchlist Monitor

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/builders-and-models.md

Utilize WatchlistMonitorBuilder to configure watchlist monitoring for a specific applicant and report type. This is essential for real-time risk assessment.

```python
monitor_builder = onfido.WatchlistMonitorBuilder(
    applicant_id=applicant_id,
    report_name='watchlist_aml'
)

monitor = api.create_watchlist_monitor(monitor_builder)
```

--------------------------------

### Configure Onfido API Client with API Token

Source: https://github.com/onfido/onfido-python/blob/master/README.md

Initialize the Onfido API client configuration using an API token. Supports EU, US, and CA regions. Default timeout is 30 seconds, can be customized.

```python
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)
  ...
```

--------------------------------

### Onfido SDK Configuration with Custom Headers

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Configures the Onfido SDK with a custom API token and sets default headers for 'X-Client-ID' and 'X-Request-ID'. Requires the ONFIDO_API_TOKEN environment variable.

```python
import onfido
import os

config = onfido.Configuration(
    api_token=os.environ['ONFIDO_API_TOKEN']
)

with onfido.ApiClient(config) as client:
    client.set_default_header('X-Client-ID', 'my-app-id')
    client.set_default_header('X-Request-ID', 'request-123')
    
    api = onfido.DefaultApi(client)
```

--------------------------------

### Create a Webhook Registration

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/builders-and-models.md

Use WebhookBuilder to define webhook details such as the URL, status, and event types. This builder is useful for setting up notifications for specific events.

```python
webhook = onfido.WebhookBuilder(
    url='https://example.com/webhooks',
    enabled=True,
    event_types=['check.completed', 'report.completed']
)

registered_webhook = api.create_webhook(webhook)
```

--------------------------------

### Create Watchlist Monitor

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/advanced-operations.md

Use this to set up ongoing AML/sanctions screening for an applicant. Requires a WatchlistMonitorBuilder object.

```python
def create_watchlist_monitor(
    self,
    watchlist_monitor_builder: WatchlistMonitorBuilder,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _content_type: Optional[str] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> WatchlistMonitor:
    pass
```

```python
monitor_builder = onfido.WatchlistMonitorBuilder(
    applicant_id=applicant_id,
    report_name='watchlist_aml'
)

monitor = api.create_watchlist_monitor(monitor_builder)
print(f"Monitor created: {monitor.id}")
```

--------------------------------

### Upload Signing Document - Python

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/media-operations.md

Uploads a document in video format for signing by an applicant. Optionally specify a file name.

```python
def upload_signing_document(
    self,
    applicant_id: UUID,
    file: bytes,
    file_name: Optional[str] = None,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> SigningDocument
```

--------------------------------

### Download Live Video Frame - Python

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/media-operations.md

Downloads a specific frame from a live video as JPEG bytes. Requires applicant ID and live video ID.

```python
def download_live_video_frame(
    self,
    applicant_id: UUID,
    live_video_id: UUID,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> bytes
```

--------------------------------

### Onfido SDK Configuration with Proxy

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Configures the Onfido SDK to use a corporate proxy with specified proxy headers for authentication. Requires the ONFIDO_API_TOKEN environment variable.

```python
import onfido
import os

config = onfido.Configuration(
    api_token=os.environ['ONFIDO_API_TOKEN'],
    proxy='http://corporate-proxy.internal:8080',
    proxy_headers={
        'Proxy-Authorization': 'Basic dXNlcjpwYXNz'
    }
)

with onfido.ApiClient(config) as client:
    api = onfido.DefaultApi(client)
```

--------------------------------

### Configure with OAuth2 Client Credentials

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Recommended for enhanced security, this method uses OAuth2 client ID and secret for automatic token generation and refresh. Keep credentials secure in environment variables.

```python
configuration = onfido.Configuration(
    oauth_client_id='your_client_id',
    oauth_client_secret='your_client_secret'
)
```

--------------------------------

### Module Graph

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/README.md

Depicts the module dependencies within the Onfido Python SDK, showing the flow from Configuration to Models.

```text
Configuration (auth, hosts, timeouts)
        ↓
    ApiClient (HTTP client)
        ↓
  DefaultApi (API operations)
        ↓
  Models (Request/Response DTOs)
```

--------------------------------

### Onfido SDK Configuration with Client Certificates (mTLS)

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Configures the Onfido SDK for mutual TLS (mTLS) authentication using client certificate and key files, along with a custom CA bundle for verification. Requires the ONFIDO_API_TOKEN environment variable.

```python
import onfido
import os

config = onfido.Configuration(
    api_token=os.environ['ONFIDO_API_TOKEN'],
    cert_file='/etc/ssl/certs/client.crt',
    key_file='/etc/ssl/private/client.key',
    verify_ssl=True,
    ssl_ca_cert='/etc/ssl/certs/ca-bundle.crt',
)

with onfido.ApiClient(config) as client:
    api = onfido.DefaultApi(client)
```

--------------------------------

### Onfido SDK Configuration with Higher Timeouts for Large Files

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Configures the Onfido SDK with extended connection (120 seconds) and read (600 seconds) timeouts, suitable for uploading large files like videos. Includes 3 retries. Requires the ONFIDO_API_TOKEN environment variable.

```python
import onfido
import urllib3
import os

config = onfido.Configuration(
    api_token=os.environ['ONFIDO_API_TOKEN'],
    timeout=urllib3.util.Timeout(
        connect=120.0,  # 2 minute connection timeout
        read=600.0      # 10 minute read timeout
    ),
    retries=3,
)

with onfido.ApiClient(config) as client:
    api = onfido.DefaultApi(client)
    # Safe for uploading large videos
```

--------------------------------

### List Watchlist Monitors

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/advanced-operations.md

Retrieve a list of all configured watchlist monitors.

```python
def list_watchlist_monitors(
    self,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> WatchlistMonitorsList:
    pass
```

--------------------------------

### Create an Applicant using Onfido API

Source: https://github.com/onfido/onfido-python/blob/master/README.md

Make a call to the Onfido API to create an applicant. Access applicant information via object properties. Handles potential API exceptions.

```python
  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
```

--------------------------------

### Configure Onfido API Client with OAuth2 Credentials

Source: https://github.com/onfido/onfido-python/blob/master/README.md

Initialize the Onfido API client configuration using OAuth2 client ID and secret. The client automatically handles token exchange and refresh. Supports EU, US, and CA regions. Default timeout is 30 seconds, can be customized.

```python
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)
  ...
```

--------------------------------

### Generate SDK Token with Onfido Python SDK

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/README.md

Create an SDK token for embedding the Onfido Web SDK. Requires applicant ID.

```python
token_builder = onfido.SdkTokenBuilder(applicant_id=applicant_id)
sdk_token = api.generate_sdk_token(token_builder)
```

--------------------------------

### download_live_video

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/default-api.md

Download a live video file associated with an applicant.

```APIDOC
## download_live_video

### Description
Download a live video file.

### Method
GET (assumed, based on download action)

### Endpoint
/v1/applicants/{applicant_id}/live-videos/{live_video_id}

### Parameters
#### Path Parameters
- **applicant_id** (UUID) - Required - The ID of the applicant.
- **live_video_id** (UUID) - Required - The ID of the live video.

### Response
#### Success Response (200)
- **bytes** - Video file content as bytes.
```

--------------------------------

### Configure Logging Parameters

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Enable debug mode for verbose logging and specify a file path for log output, along with a custom log format. Logs help in debugging and monitoring API interactions.

```python
configuration = onfido.Configuration(
    debug=True,
)
configuration.logger_file = '/var/log/onfido.log'
configuration.logger_format = '%(asctime)s %(levelname)s %(message)s'
```

--------------------------------

### Stream Download Evidence Folder

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/media-operations.md

Downloads an evidence folder as a zip file without loading the entire content into memory. The SDK returns bytes, which can be written directly to a file.

```python
def download_evidence_folder_streaming(applicant_id, check_id):
    """Download evidence folder without loading entire file in memory."""
    try:
        # Note: SDK returns bytes, but you can write immediately
        zip_data = api.download_evidence_folder(applicant_id, check_id)
        
        output_path = f'evidence_{check_id}.zip'
        with open(output_path, 'wb') as f:
            f.write(zip_data)
        
        return output_path
    except onfido.NotFoundException:
        print("Evidence folder not found")
        raise
```

--------------------------------

### List Passkeys

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/advanced-operations.md

List all passkeys associated with a specific applicant. Requires the applicant ID.

```python
def list_passkeys(
    self,
    applicant_id: UUID,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> PasskeysList
```

--------------------------------

### Download Document with Onfido Python SDK

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/README.md

Retrieve the content of an uploaded document using applicant ID and document ID.

```python
file_data = api.download_document(applicant_id, document_id)
```

--------------------------------

### List Applicants with Onfido Python SDK

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/README.md

Retrieve a paginated list of applicants. Supports specifying page number and items per page.

```python
applicants = api.list_applicants(page=1, per_page=20)
```

--------------------------------

### Create Watchlist Monitor

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/advanced-operations.md

Creates a watchlist monitor for ongoing AML/sanctions screening. Requires a WatchlistMonitorBuilder object with monitor configuration.

```APIDOC
## create_watchlist_monitor

### Description
Create a watchlist monitor for ongoing AML/sanctions screening.

### Method
```python
def create_watchlist_monitor(
    self,
    watchlist_monitor_builder: WatchlistMonitorBuilder,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _content_type: Optional[str] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> WatchlistMonitor
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **watchlist_monitor_builder** (WatchlistMonitorBuilder) - Required - Monitor configuration

### Request Example
```python
monitor_builder = onfido.WatchlistMonitorBuilder(
    applicant_id=applicant_id,
    report_name='watchlist_aml'
)

monitor = api.create_watchlist_monitor(monitor_builder)
print(f"Monitor created: {monitor.id}")
```

### Response
#### Success Response (200)
- **WatchlistMonitor** (WatchlistMonitor) - The created WatchlistMonitor object.

#### Response Example
```json
{
  "id": "<uuid>",
  "applicant_id": "<uuid>",
  "report_name": "watchlist_aml",
  "created_at": "<timestamp>",
  "updated_at": "<timestamp>"
}
```
```

--------------------------------

### List Workflow Runs

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/advanced-operations.md

Fetches a list of all initiated workflow runs.

```APIDOC
## list_workflow_runs

### Description
List all workflow runs.

### Method
GET (assumed, based on listing)

### Endpoint
/workflows/runs (assumed)

### Parameters
#### Query Parameters
- **_request_timeout** (float or tuple) - Optional - Request timeout
- **_request_auth** (Dict) - Optional - Override authentication
- **_headers** (Dict) - Optional - Custom headers
- **_host_index** (int) - Optional - Host index

### Response
#### Success Response (200)
- **WorkflowRunsList** (WorkflowRunsList) - A list containing workflow runs.
```

--------------------------------

### Production Onfido SDK Configuration with OAuth2

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/configuration.md

Configures the Onfido SDK for production use with OAuth2, specifying the US region, custom connection and read timeouts (60 seconds each), SSL verification, a custom CA certificate path, and a retry count of 3. Requires ONFIDO_OAUTH_CLIENT_ID and ONFIDO_OAUTH_CLIENT_SECRET environment variables.

```python
import onfido
import urllib3
import os

config = onfido.Configuration(
    oauth_client_id=os.environ['ONFIDO_OAUTH_CLIENT_ID'],
    oauth_client_secret=os.environ['ONFIDO_OAUTH_CLIENT_SECRET'],
    region=onfido.configuration.Region.US,
    timeout=urllib3.util.Timeout(connect=60.0, read=60.0),
    verify_ssl=True,
    ssl_ca_cert='/etc/ssl/certs/ca-bundle.crt',
    retries=3,
    debug=False,
)

with onfido.ApiClient(config) as client:
    api = onfido.DefaultApi(client)
    # Make API calls...
```

--------------------------------

### Upload Live Photo with Onfido Python SDK

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/README.md

Upload a live selfie photo for an applicant. Requires applicant ID and photo file content.

```python
with open('selfie.jpg', 'rb') as f:
    live_photo = api.upload_live_photo(applicant_id, f.read())
```

--------------------------------

### Create Check with Onfido Python SDK

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/README.md

Initiate a verification check for an applicant, specifying the desired report names.

```python
builder = onfido.CheckBuilder(
    report_names=['document', 'facial_similarity_photo']
)
check = api.create_check(applicant_id, builder)
```

--------------------------------

### Download Signing Document

Source: https://github.com/onfido/onfido-python/blob/master/_autodocs/api-reference/media-operations.md

Download a signing document file for a given applicant and signing document ID. Returns the file content as bytes.

```python
def download_signing_document(
    self,
    applicant_id: UUID,
    signing_document_id: UUID,
    _request_timeout: Optional[Union[float, Tuple[float, float]]] = None,
    _request_auth: Optional[Dict[str, Any]] = None,
    _headers: Optional[Dict[str, Any]] = None,
    _host_index: int = 0,
) -> bytes
```