SDKs and External Integration Surface - Python SDK Resources, Shared Errors, and Webhook Helpers

Overview

The Python SDK is the typed integration layer for Lita’s regional API surface. It gives application code a small set of resource facades for the consent lifecycle, evidence retrieval, async feature computation, and job status polling, while mapping the API payloads into explicit Python models and literal state values.

This surface mirrors the same REST semantics exposed by the Node and Java SDKs: consent creation uses the same request fields, evidence is retrieved by evidence_ref, async work is started through features.compute and tracked through status.get, and webhook events are validated with the same HMAC-SHA256 signature scheme. The SDK also centralizes API error handling through a shared exception hierarchy and provides a webhook verification helper for inbound event handlers.

Architecture Overview

flowchart TB
    subgraph AppCode[Consumer Application]
        App[Application code]
        WebhookHandler[Webhook endpoint]
    end

    subgraph PythonSDK[Python SDK Surface]
        ConsentsResource[ConsentsResource]
        EvidenceResource[EvidenceResource]
        FeaturesResource[FeaturesResource]
        StatusResource[StatusResource]
        WebhooksHelper[construct_event]
        ErrorTypes[LitaError hierarchy]
        SharedTypes[Type aliases and models]
    end

    subgraph LitaAPI[Lita API]
        ConsentAPI[Consent endpoints]
        EvidenceAPI[Evidence endpoint]
        FeaturesAPI[Feature compute endpoint]
        StatusAPI[Job status endpoint]
        WebhookDelivery[Webhook delivery]
    end

    App --> ConsentsResource
    App --> EvidenceResource
    App --> FeaturesResource
    App --> StatusResource
    App --> WebhooksHelper

    ConsentsResource --> ConsentAPI
    EvidenceResource --> EvidenceAPI
    FeaturesResource --> FeaturesAPI
    StatusResource --> StatusAPI

    LitaAPI --> WebhookHandler
    WebhookHandler --> WebhooksHelper

    ConsentsResource -.-> SharedTypes
    EvidenceResource -.-> SharedTypes
    FeaturesResource -.-> SharedTypes
    StatusResource -.-> SharedTypes
    WebhooksHelper -.-> SharedTypes

    ConsentsResource -.-> ErrorTypes
    EvidenceResource -.-> ErrorTypes
    FeaturesResource -.-> ErrorTypes
    StatusResource -.-> ErrorTypes

Packaging and Runtime Dependencies

sdks/python/pyproject.toml

[!NOTE] The Python SDK keeps the same resource boundaries as the other official SDKs, but it uses Python naming conventions: construct_event in Python corresponds to constructEvent in Node and Java.

The Python package is published as lita-python and targets Python 3.9 or newer. Runtime and development dependencies are declared centrally in pyproject.toml.

Setting Value Responsibility
project.name lita-python Package identity for distribution
project.version 1.2.0 SDK release version
project.description Official Lita Python SDK Public package description
project.license.text MIT License declaration
project.requires-python >=3.9 Supported interpreter range
project.dependencies httpx>=0.27.0 HTTP transport dependency
project.optional-dependencies.dev pytest, pytest-asyncio, mypy, ruff, respx Development and test tooling
tool.setuptools.packages.find.include lita* Package discovery scope
tool.mypy.strict true Strict type checking
tool.mypy.python_version 3.9 Type-check target
tool.ruff.line-length 100 Lint formatting constraint
build-system.requires setuptools>=68, wheel Build requirements
build-system.build-backend setuptools.backends.legacy:build Packaging backend

Shared Type System

Type Aliases

The SDK uses literal-backed state tokens so callers can branch on API state without parsing free-form strings.

Alias Values Used By
Region us, jp Regional routing and webhook payloads
ConsentPurpose RENTAL_SCREENING, LENDING_UNDERWRITING, EMPLOYMENT_SCREENING, ACCOUNT_OPENING Consent creation
DataCategory transactions, income, payment_behavior, obligations, employment Consent creation
ConsentStatus PENDING, ACTIVE, REVOKED, EXPIRED Consent lifecycle responses
JobStatus PROCESSING, COMPLETE, FAILED Async feature job status
ScoreDecision APPROVE, REVIEW, DECLINE, INSUFFICIENT_DATA Score responses
KycStatus PASSED, REVIEW, FAILED, PENDING KYC responses and webhook payloads
DelinquencyBucket CURRENT, 30_DPD, 60_DPD, 90_PLUS_DPD, CHARGE_OFF, WRITE_OFF Evidence snapshots
WebhookEventType consent.activated, consent.expired, consent.revoked, data.updated, features.computed, score.completed, kyc.updated Webhook event routing

Represents the consent record returned by create, get, and revoke operations.

Property Type Description
consent_id str Consent identifier
status ConsentStatus Current consent state
applicant_id str Applicant identifier supplied at creation
purpose ConsentPurpose Declared consent purpose
expires_at str Expiration timestamp
redirect_url Optional[str] Redirect target returned during creation
created_at Optional[str] Creation timestamp
activated_at Optional[str] Activation timestamp
revoked_at Optional[str] Revocation timestamp
connections List[Connection] Linked provider connections

Connection (sdks/python/lita/types.py)

Returned inside Consent.connections.

Property Type Description
connection_id str Provider connection identifier
provider str Provider name
status str Provider connection status string

KycCheckDetail (sdks/python/lita/types.py)

Represents a single KYC or AML check result inside KycResult.checks.

Property Type Description
status KycStatus Check outcome
method Optional[str] Verification method name
lists_screened Optional[List[str]] Lists screened during the check
risk_level Optional[str] Risk classification returned by the API

KycResult (sdks/python/lita/types.py)

Returned by ConsentsResource.get_kyc.

Property Type Description
consent_id str Consent identifier tied to the compliance result
status KycStatus Overall compliance outcome
checks Dict[str, KycCheckDetail] Named per-check results
completed_at str Completion timestamp

ComputeFeaturesResponse (sdks/python/lita/types.py)

Returned by FeaturesResource.compute.

Property Type Description
job_id str Async job identifier
status JobStatus Current job state
consent_id str Consent processed by the job
estimated_completion_ms int Estimated completion time in milliseconds

JobStatusResponse (sdks/python/lita/types.py)

Returned by StatusResource.get.

Property Type Description
job_id str Async job identifier
status JobStatus Current job state
consent_id str Consent associated with the job
completed_at Optional[str] Completion timestamp when available
error Optional[Dict[str, str]] Error payload when the job fails

Score (sdks/python/lita/types.py)

Returned by ConsentsResource.get_score.

Property Type Description
consent_id str Consent identifier
applicant_id str Applicant identifier
score int Computed score value
score_range ScoreRange Score bounds returned by the API
decision ScoreDecision Decision derived from the score
score_factors List[str] Factors used in the score explanation
evidence_ref str Evidence snapshot reference
scored_at str Score timestamp
model_version str Model version used for scoring

EvidenceSnapshot (sdks/python/lita/types.py)

Returned by EvidenceResource.get.

Property Type Description
evidence_ref str Immutable evidence reference
consent_id str Consent identifier
applicant_id str Applicant identifier
snapshot_version str Snapshot schema version
created_at str Snapshot creation timestamp
score_inputs Dict[str, Any] Score input payload returned by the API
kyc_result Dict[str, Any] KYC payload returned by the API
delinquency_bucket DelinquencyBucket Final delinquency classification

TransactionListResponse (sdks/python/lita/types.py)

Returned by ConsentsResource.list_transactions.

Property Type Description
data List[Transaction] Paginated transaction records
next_cursor Optional[str] Cursor for the next page
total_count int Total count returned by the API

WebhookEvent (sdks/python/lita/types.py)

Returned by construct_event.

Property Type Description
event_id str Event identifier
event_type WebhookEventType Event kind
created_at str Event timestamp
region Region Region that emitted the event
data Dict[str, Any] Event payload

Error Hierarchy

LitaError (sdks/python/lita/errors.py)

Base exception for API failures.

Property Type Description
status int HTTP status code
code str Machine-readable error code
request_id str Request correlation identifier
retryable bool Retryability flag returned by the API

Public methods

Method Description
__init__ Builds the exception from a status code and an error response body
__repr__ Returns a compact string representation containing the status and code

LitaAuthError (sdks/python/lita/errors.py)

Specializes LitaError for 401 and 403 responses. It does not add new fields.

LitaNotFoundError (sdks/python/lita/errors.py)

Specializes LitaError for 404 responses. It does not add new fields.

LitaRateLimitError (sdks/python/lita/errors.py)

Specializes LitaError for 429 responses and exposes retry metadata.

Property Type Description
retry_after Optional[int] Retry delay when the API returns rate-limit guidance

LitaWebhookSignatureError (sdks/python/lita/errors.py)

Raised when webhook signature verification fails. The exception message is fixed to:

Webhook signature verification failed. Ensure you are using the correct webhook secret.

Resource Facades

ConsentsResource (sdks/python/lita/resources/consents.py)

This resource wraps the consent lifecycle, score retrieval, transactions, and KYC inspection. Its methods call the injected HTTP client directly and convert the raw JSON into typed Python objects.

Constructor Dependency

Type Description
HttpClient Transport client used for all consent-related requests

Public Methods

Method Description
create Creates a consent from applicant_id, purpose, data_categories, and expires_in_days, then returns Consent
get Fetches the current consent state by consent ID and returns Consent
revoke Revokes a consent by consent ID and returns Consent
get_score Retrieves the computed score for a consent and returns Score
list_transactions Lists paginated transactions for a consent and returns TransactionListResponse
get_kyc Retrieves KYC and AML results for a consent and returns KycResult
{
    "title": "Create Consent",
    "description": "Creates a consent and returns the redirect URL",
    "method": "POST",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/consents",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"applicant_id\": \"app_demo_001\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"data_categories\": [\n        \"transactions\",\n        \"income\",\n        \"payment_behavior\"\n    ],\n    \"expires_in_days\": 30\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"con_01J2ABCDEF1234567890\",\n    \"status\": \"PENDING\",\n    \"applicant_id\": \"app_demo_001\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"expires_at\": \"2026-04-30T12:00:00Z\",\n    \"redirect_url\": \"https://connect.joinlita.com/consents/con_01J2ABCDEF1234567890/redirect\",\n    \"created_at\": \"2026-03-31T12:00:00Z\",\n    \"activated_at\": null,\n    \"revoked_at\": null,\n    \"connections\": []\n}"
        }
    }
}
{
    "title": "Get Consent",
    "description": "Fetches the current consent state",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/consents/{consent_id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "value": "con_01J2ABCDEF1234567890",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"con_01J2ABCDEF1234567890\",\n    \"status\": \"ACTIVE\",\n    \"applicant_id\": \"app_demo_001\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"expires_at\": \"2026-04-30T12:00:00Z\",\n    \"redirect_url\": \"https://connect.joinlita.com/consents/con_01J2ABCDEF1234567890/redirect\",\n    \"created_at\": \"2026-03-31T12:00:00Z\",\n    \"activated_at\": \"2026-03-31T12:03:00Z\",\n    \"revoked_at\": null,\n    \"connections\": [\n        {\n            \"connection_id\": \"conn_01J2XYZ9876543210\",\n            \"provider\": \"bank_one\",\n            \"status\": \"ACTIVE\"\n        }\n    ]\n}"
        }
    }
}
{
    "title": "Revoke Consent",
    "description": "Revokes an active consent",
    "method": "DELETE",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/consents/{consent_id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "value": "con_01J2ABCDEF1234567890",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"con_01J2ABCDEF1234567890\",\n    \"status\": \"REVOKED\",\n    \"applicant_id\": \"app_demo_001\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"expires_at\": \"2026-04-30T12:00:00Z\",\n    \"redirect_url\": \"https://connect.joinlita.com/consents/con_01J2ABCDEF1234567890/redirect\",\n    \"created_at\": \"2026-03-31T12:00:00Z\",\n    \"activated_at\": \"2026-03-31T12:03:00Z\",\n    \"revoked_at\": \"2026-03-31T12:20:00Z\",\n    \"connections\": [\n        {\n            \"connection_id\": \"conn_01J2XYZ9876543210\",\n            \"provider\": \"bank_one\",\n            \"status\": \"CLOSED\"\n        }\n    ]\n}"
        }
    }
}
{
    "title": "Get Consent Score",
    "description": "Retrieves the computed score for a consent",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/consents/{consent_id}/score",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "value": "con_01J2ABCDEF1234567890",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"con_01J2ABCDEF1234567890\",\n    \"applicant_id\": \"app_demo_001\",\n    \"score\": 742,\n    \"score_range\": {\n        \"min\": 300,\n        \"max\": 850\n    },\n    \"decision\": \"APPROVE\",\n    \"score_factors\": [\n        \"payment_behavior\",\n        \"income_stability\",\n        \"low_obligations\"\n    ],\n    \"evidence_ref\": \"evd_01J2EVIDENCE123456\",\n    \"scored_at\": \"2026-03-31T12:15:00Z\",\n    \"model_version\": \"score-v3.2.0\"\n}"
        }
    }
}

List Transactions

{
    "title": "List Transactions",
    "description": "Lists paginated transactions for a consent",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/consents/{consent_id}/data/transactions",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "limit",
            "value": "25",
            "required": false
        },
        {
            "key": "cursor",
            "value": "cursor_01J2NEXTPAGE",
            "required": false
        },
        {
            "key": "from_date",
            "value": "2026-01-01",
            "required": false
        },
        {
            "key": "to_date",
            "value": "2026-03-31",
            "required": false
        }
    ],
    "pathParams": [
        {
            "key": "consent_id",
            "value": "con_01J2ABCDEF1234567890",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"data\": [\n        {\n            \"transaction_id\": \"txn_01J2TXN0001\",\n            \"date\": \"2026-03-29\",\n            \"amount\": -42.35,\n            \"currency\": \"USD\",\n            \"description\": \"Grocery Store\",\n            \"category\": \"groceries\",\n            \"type\": \"DEBIT\"\n        }\n    ],\n    \"next_cursor\": \"cursor_01J2NEXTPAGE\",\n    \"total_count\": 128\n}"
        }
    }
}

Get KYC Results

{
    "title": "Get KYC Results",
    "description": "Retrieves KYC and AML compliance check results for a consent",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/consents/{consent_id}/kyc",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "value": "con_01J2ABCDEF1234567890",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"con_01J2ABCDEF1234567890\",\n    \"status\": \"PASSED\",\n    \"checks\": {\n        \"identity\": {\n            \"status\": \"PASSED\",\n            \"method\": \"document_and_selfie\",\n            \"lists_screened\": [\n                \"government_id\"\n            ],\n            \"risk_level\": \"low\"\n        },\n        \"sanctions\": {\n            \"status\": \"PASSED\",\n            \"method\": \"watchlist_screening\",\n            \"lists_screened\": [\n                \"sanctions\",\n                \"pep\"\n            ],\n            \"risk_level\": \"low\"\n        }\n    },\n    \"completed_at\": \"2026-03-31T12:05:00Z\"\n}"
        }
    }
}

EvidenceResource (sdks/python/lita/resources/evidence.py)

[!NOTE] revoke parses the response back into the full Consent model, so the Python SDK expects the revoke response to contain the same core consent fields used by create and get.

This resource retrieves immutable evidence snapshots for audit trails, adverse action notices, and regulatory responses. The docstring explicitly states that snapshots are retained for 7 years from creation.

Constructor Dependency

Type Description
HttpClient Transport client used for evidence snapshot retrieval

Public Methods

Method Description
get Retrieves an immutable evidence snapshot by evidence_ref and returns EvidenceSnapshot

Get Evidence Snapshot

{
    "title": "Get Evidence Snapshot",
    "description": "Retrieves an immutable evidence snapshot",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/evidence/{evidence_ref}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "evidence_ref",
            "value": "evd_01J2EVIDENCE123456",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"evidence_ref\": \"evd_01J2EVIDENCE123456\",\n    \"consent_id\": \"con_01J2ABCDEF1234567890\",\n    \"applicant_id\": \"app_demo_001\",\n    \"snapshot_version\": \"1\",\n    \"created_at\": \"2026-03-31T12:05:00Z\",\n    \"score_inputs\": {\n        \"payment_behavior\": {\n            \"payments_observed\": 18,\n            \"avg_payment_delay_days\": 2,\n            \"late_payment_count_30d_plus\": 0\n        },\n        \"income\": {\n            \"monthly_net_income\": 6200,\n            \"income_stability_score\": 91\n        },\n        \"obligations\": {\n            \"total_monthly_obligations\": 1450,\n            \"obligation_to_income_ratio\": 0.23\n        }\n    },\n    \"kyc_result\": {\n        \"status\": \"PASSED\",\n        \"checks\": [\n            \"identity\",\n            \"sanctions\"\n        ]\n    },\n    \"delinquency_bucket\": \"CURRENT\"\n}"
        }
    }
}

FeaturesResource (sdks/python/lita/resources/features.py)

This resource starts the async feature computation pipeline and returns the job metadata immediately.

Constructor Dependency

Type Description
HttpClient Transport client used to start feature jobs

Public Methods

Method Description
compute Starts feature computation for an active consent and returns ComputeFeaturesResponse

Compute Features

{
    "title": "Compute Features",
    "description": "Triggers the feature computation pipeline",
    "method": "POST",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/features/compute",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"consent_id\": \"con_01J2ABCDEF1234567890\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"job_id\": \"job_01J2FEATURE123456\",\n    \"status\": \"PROCESSING\",\n    \"consent_id\": \"con_01J2ABCDEF1234567890\",\n    \"estimated_completion_ms\": 4500\n}"
        }
    }
}

StatusResource (sdks/python/lita/resources/status.py)

[!NOTE] The compute docstring marks the operation as asynchronous and directs callers toward the score.completed webhook rather than polling whenever possible.

This resource polls async job status for a job_id returned by FeaturesResource.compute.

Constructor Dependency

Type Description
HttpClient Transport client used for job status polling

Public Methods

Method Description
get Polls an async job by job ID and returns JobStatusResponse

Get Job Status

{
    "title": "Get Job Status",
    "description": "Polls the status of an async processing job",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/status/{job_id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "job_id",
            "value": "job_01J2FEATURE123456",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"job_id\": \"job_01J2FEATURE123456\",\n    \"status\": \"COMPLETE\",\n    \"consent_id\": \"con_01J2ABCDEF1234567890\",\n    \"completed_at\": \"2026-03-31T12:10:30Z\",\n    \"error\": null\n}"
        }
    }
}

Webhook Helpers

construct_event (sdks/python/lita/webhooks.py)

[!NOTE] The docstring explicitly says polling is rate-limited to 2 requests per second per job ID and recommends webhooks when available.

The webhook helper verifies the X-Lita-Signature header and returns a parsed WebhookEvent. It accepts the raw request body as bytes or str, computes an HMAC-SHA256 digest using the shared secret, compares the result in constant time, and only then parses the JSON payload.

Parameters

Parameter Type Description
raw_body Union[bytes, str] Raw request body; string values are encoded as UTF-8 before verification
signature str Value of the X-Lita-Signature header
secret str Webhook signing secret from the Lita dashboard

Returns

Return type Description
WebhookEvent Parsed webhook event object

Failure mode

Condition Exception
Signature mismatch LitaWebhookSignatureError
from lita.webhooks import construct_event
from lita.errors import LitaWebhookSignatureError

try:
    event = construct_event(raw_body, signature, secret)
except LitaWebhookSignatureError:
    # Reject the request
    ...

Webhook Verification Flow

sequenceDiagram
    participant LitaAPI as Lita API
    participant App as Webhook endpoint
    participant Helper as construct_event
    participant Types as WebhookEvent model

    LitaAPI->>App: POST webhook payload and signature
    App->>Helper: construct_event raw body signature secret
    Helper->>Helper: Encode body if needed
    Helper->>Helper: Compute HMAC SHA256
    Helper->>Helper: Compare signature in constant time
    alt Signature mismatch
        Helper-->>App: LitaWebhookSignatureError
    else Signature valid
        Helper->>Types: Build WebhookEvent
        Types-->>Helper: WebhookEvent
        Helper-->>App: Parsed event
    end

Feature Flows

A typical consent flow starts with ConsentsResource.create, then uses the returned consent ID later for consent inspection and score retrieval.

sequenceDiagram
    participant App as Application
    participant CR as ConsentsResource
    participant HC as HttpClient
    participant API as Lita API

    App->>CR: create
    CR->>HC: post consents
    HC->>API: POST /{region}/consents
    API-->>HC: Consent JSON
    HC-->>CR: Consent
    CR-->>App: Consent with redirect_url

    App->>CR: get_score
    CR->>HC: get consents consent score
    HC->>API: GET /{region}/consents/{consent_id}/score
    API-->>HC: Score JSON
    HC-->>CR: Score
    CR-->>App: Score and decision

Evidence Snapshot Retrieval for Audit Use

Evidence snapshots are retrieved by reference and are intended for audit and regulatory use cases.

sequenceDiagram
    participant App as Application
    participant ER as EvidenceResource
    participant HC as HttpClient
    participant API as Lita API

    App->>ER: get
    ER->>HC: get evidence ref
    HC->>API: GET /{region}/evidence/{evidence_ref}
    API-->>HC: EvidenceSnapshot JSON
    HC-->>ER: EvidenceSnapshot
    ER-->>App: Immutable snapshot for audit use

Async Feature Computation and Status Polling

FeaturesResource.compute starts the job and returns immediately. The job is then observed through StatusResource.get or completed through webhook delivery.

sequenceDiagram
    participant App as Application
    participant FR as FeaturesResource
    participant SR as StatusResource
    participant HC as HttpClient
    participant API as Lita API

    App->>FR: compute
    FR->>HC: post features compute
    HC->>API: POST /{region}/features/compute
    API-->>HC: ComputeFeaturesResponse
    HC-->>FR: Job metadata
    FR-->>App: job_id and estimated_completion_ms

    App->>SR: get
    SR->>HC: get status job_id
    HC->>API: GET /{region}/status/{job_id}
    API-->>HC: JobStatusResponse
    HC-->>SR: JobStatusResponse
    SR-->>App: status update

State Management

The SDK models server-side state as literal values and response objects instead of mutable client-side state.

State family Values Where it appears
ConsentStatus PENDING, ACTIVE, REVOKED, EXPIRED Consent.status
JobStatus PROCESSING, COMPLETE, FAILED ComputeFeaturesResponse.status, JobStatusResponse.status
KycStatus PASSED, REVIEW, FAILED, PENDING KycCheckDetail.status, KycResult.status, webhook payloads
ScoreDecision APPROVE, REVIEW, DECLINE, INSUFFICIENT_DATA Score.decision
WebhookEventType consent.activated, consent.expired, consent.revoked, data.updated, features.computed, score.completed, kyc.updated WebhookEvent.event_type
DelinquencyBucket CURRENT, 30_DPD, 60_DPD, 90_PLUS_DPD, CHARGE_OFF, WRITE_OFF EvidenceSnapshot.delinquency_bucket
Region us, jp URL routing and webhook payloads
ConsentPurpose RENTAL_SCREENING, LENDING_UNDERWRITING, EMPLOYMENT_SCREENING, ACCOUNT_OPENING Consent creation
DataCategory transactions, income, payment_behavior, obligations, employment Consent creation

Integration Points

  • Lita API regional surfaces: resource methods are routed under /{region}/..., matching the same regional split used by the other official SDKs.
  • Consent lifecycle: create, get, revoke, get_score, list_transactions, and get_kyc all operate on the same consent record.
  • Evidence and audit workflows: EvidenceResource.get consumes the evidence_ref returned by scoring flows.
  • Async job workflows: FeaturesResource.compute starts work, StatusResource.get polls it, and webhook consumers can validate completion events through construct_event.
  • Webhook receivers: inbound handlers use the shared webhook signature scheme and parse into WebhookEvent.
  • Shared error envelope: the SDK’s LitaError structure is aligned with the API’s nested error payload shape.
  • Cross-SDK parity: the Python surface mirrors the same resource set and payload semantics exposed by Node and Java.

Error Handling

The Python SDK models HTTP and webhook failures as typed exceptions.

  • LitaError reads the nested error object from the API response body.
  • LitaAuthError represents authentication and authorization failures.
  • LitaNotFoundError represents missing resources.
  • LitaRateLimitError captures server-provided retry timing through retry_after.
  • LitaWebhookSignatureError is raised when webhook verification fails.
from lita.errors import LitaError, LitaRateLimitError, LitaWebhookSignatureError
from lita.webhooks import construct_event

try:
    consent = client.consents.create(
        applicant_id="app_demo_001",
        purpose="LENDING_UNDERWRITING",
        data_categories=["transactions", "income", "payment_behavior"],
        expires_in_days=30,
    )
except LitaRateLimitError as exc:
    print(exc.status, exc.code, exc.retry_after)
except LitaError as exc:
    print(exc.status, exc.code, exc.request_id, exc.retryable)

try:
    event = construct_event(raw_body, signature, secret)
except LitaWebhookSignatureError:
    print("Reject webhook")

Testing Considerations

[!NOTE] LitaError falls back to Unknown error, unknown, an empty request ID, and False if those fields are absent from the API error body.

  • Use respx to stub the httpx transport and assert the exact path fragments used by each resource method.
  • Validate that consent creation sends applicant_id, purpose, data_categories, and expires_in_days.
  • Verify that EvidenceResource.get maps the snapshot fields into EvidenceSnapshot and preserves nested score_inputs and kyc_result payloads.
  • Assert that FeaturesResource.compute returns job_id, status, consent_id, and estimated_completion_ms.
  • Assert that StatusResource.get handles completed_at and error as optional fields.
  • Verify webhook signatures against raw bytes and raw strings, including the sha256= prefix.
  • Keep mypy strictness and ruff formatting aligned with the package configuration.

Key Classes Reference

Class Responsibility
Consent (types.py) Consent record returned by create, get, and revoke
Connection (types.py) Provider connection embedded in a consent
KycCheckDetail (types.py) Single KYC or AML check result
KycResult (types.py) Compliance result attached to a consent
ComputeFeaturesResponse (types.py) Async feature job metadata
JobStatusResponse (types.py) Async job polling result
Score (types.py) Computed score, explanation, and evidence reference
EvidenceSnapshot (types.py) Immutable audit snapshot
TransactionListResponse (types.py) Paginated transaction collection
WebhookEvent (types.py) Parsed webhook payload
LitaError (errors.py) Base API exception
LitaAuthError (errors.py) Auth failure exception
LitaNotFoundError (errors.py) Missing resource exception
LitaRateLimitError (errors.py) Rate limit exception with retry guidance
LitaWebhookSignatureError (errors.py) Webhook signature verification failure
ConsentsResource (resources/consents.py) Consent, score, transactions, and KYC operations
EvidenceResource (resources/evidence.py) Evidence snapshot retrieval
FeaturesResource (resources/features.py) Async feature computation
StatusResource (resources/status.py) Async job polling
construct_event (webhooks.py) Webhook signature verification and parsing