Consent and Evidence Management Domain

Overview

This domain exposes the SDK surfaces used to trace a scored decision back to its immutable evidence, then follow the consent that authorized downstream data access. The central anchor is evidence_ref, which is returned from score retrieval and then used to fetch an immutable evidence snapshot for audit, dispute handling, adverse action support, and regulatory response workflows.

It also exposes consent-scoped retrieval for transaction history and KYC results. Those responses are tied to consent_id, so callers can retrieve the exact data set that was authorized for a given consent, while evidence_ref preserves the immutable scoring snapshot associated with that consented decision.

Architecture Overview

flowchart TB
    subgraph ClientSurface [SDK Client Surface]
        JavaLita[Lita Java SDK]
        NodeLita[Lita Node SDK]
        PythonResources[Python Resource Classes]
    end

    subgraph ResourceLayer [Consent and Evidence Resources]
        JavaConsents[ConsentsResource Java]
        JavaEvidence[EvidenceResource Java]
        NodeConsents[ConsentsResource Node]
        NodeEvidence[EvidenceResource Node]
        PythonConsents[ConsentsResource Python]
        PythonEvidence[EvidenceResource Python]
    end

    subgraph TransportLayer [HTTP Transport]
        JavaHttp[HttpClient Java]
        NodeHttp[HttpClient Node]
        PythonHttp[HttpClient Python]
    end

    subgraph ContractLayer [Response and Query Contracts]
        EvidenceSnapshot[EvidenceSnapshot]
        Score[Score]
        Transaction[Transaction]
        TransactionListResponse[TransactionListResponse]
        TransactionListParams[TransactionListParams]
        KycResult[KycResult]
    end

    LitaApi[Lita API region scoped routes]

    JavaLita --> JavaConsents
    JavaLita --> JavaEvidence
    NodeLita --> NodeConsents
    NodeLita --> NodeEvidence
    PythonResources --> PythonConsents
    PythonResources --> PythonEvidence

    JavaConsents --> JavaHttp
    JavaEvidence --> JavaHttp
    NodeConsents --> NodeHttp
    NodeEvidence --> NodeHttp
    PythonConsents --> PythonHttp
    PythonEvidence --> PythonHttp

    JavaHttp --> LitaApi
    NodeHttp --> LitaApi
    PythonHttp --> LitaApi

    JavaEvidence --> EvidenceSnapshot
    JavaConsents --> Score
    JavaConsents --> TransactionListResponse
    JavaConsents --> KycResult
    NodeEvidence --> EvidenceSnapshot
    NodeConsents --> Score
    NodeConsents --> TransactionListResponse
    NodeConsents --> KycResult
    PythonEvidence --> EvidenceSnapshot
    PythonConsents --> Score
    PythonConsents --> TransactionListResponse
    PythonConsents --> KycResult

SDK Client Entry Point

Java Lita Client

sdks/java/src/main/java/com/joinlita/Lita.java

Properties

Property Type Description
consents ConsentsResource Shared consent resource facade backed by one HttpClient.
features FeaturesResource Feature computation facade exposed by the same client.
evidence EvidenceResource Immutable evidence snapshot facade.
status StatusResource Async job status polling facade exposed by the same client.

Constructor Dependencies

Type Description
Builder Collects API key, region, base URL, timeout, and sandbox mode before creating the client.
HttpClient Shared transport created once and injected into every resource facade.

Public Methods

Method Description
consents Returns the shared ConsentsResource.
features Returns the shared FeaturesResource.
evidence Returns the shared EvidenceResource.
status Returns the shared StatusResource.
builder Creates a new Builder instance.

Builder Configuration

sdks/java/src/main/java/com/joinlita/Lita.java

Property Type Description
apiKey String API key required by the transport.
region String Target region, us or jp.
baseUrl String Optional override for the API base URL.
timeout Duration Optional request timeout, defaulting to 30 seconds.
sandbox boolean Routes requests through the sandbox path when enabled.

Builder Methods

Method Description
apiKey Sets the API key.
region Sets the target region.
sandbox Enables or disables sandbox routing.
baseUrl Overrides the base URL.
timeout Overrides the request timeout.
build Creates the configured Lita client.

Node Lita Client

sdks/node/src/index.ts

Properties

Property Type Description
consents ConsentsResource Consent resource facade wired to the shared HTTP client.
features FeaturesResource Feature computation facade wired to the shared HTTP client.
evidence EvidenceResource Evidence snapshot facade wired to the shared HTTP client.
status StatusResource Async status facade wired to the shared HTTP client.

Constructor Dependencies

Type Description
LitaClientOptions API key, region, sandbox flag, base URL override, and timeout.
HttpClient Shared transport created from LitaClientOptions.

Public Methods

Method Description
constructor Creates one HttpClient and injects it into all resource facades.

Node HTTP Transport

sdks/node/src/client.ts

Properties

Property Type Description
apiKey string Bearer token value used in every request.
regionPrefix string Region routing prefix, with sandbox appended when enabled.
baseUrl string Normalized base URL with trailing slash removed.
timeout number Abort timeout in milliseconds.

Public Methods

Method Description
get Sends a GET request and appends serialized query parameters.
post Sends a POST request with a JSON body.
delete Sends a DELETE request.

Request Headers Injected by the Transport

Header Value
Authorization Bearer <apiKey>
X-Request-Id req-<uuid>
Content-Type application/json for requests that include a body

Python Resource Clients

sdks/python/lita/resources/evidence.py

sdks/python/lita/resources/consents.py

Constructor Dependencies

Type Description
HttpClient Shared transport injected into each resource class.

Evidence Snapshot Retrieval

Java Evidence Resource

sdks/java/src/main/java/com/joinlita/resources/EvidenceResource.java

Properties

Property Type Description
http HttpClient Shared HTTP transport for evidence retrieval.

Constructor Dependencies

Type Description
HttpClient Executes the region-scoped GET request and maps the response into EvidenceSnapshot.

Public Methods

Method Description
get Retrieves an immutable evidence snapshot by evidence_ref.

Node Evidence Resource

sdks/node/src/resources/evidence.ts

Properties

Property Type Description
http HttpClient Shared HTTP transport for evidence retrieval.

Constructor Dependencies

Type Description
HttpClient Executes the region-scoped GET request and deserializes the response into EvidenceSnapshot.

Public Methods

Method Description
get Retrieves an immutable evidence snapshot by evidence_ref.

Python Evidence Resource

sdks/python/lita/resources/evidence.py

Properties

Property Type Description
_http HttpClient Shared HTTP transport for evidence retrieval.

Constructor Dependencies

Type Description
HttpClient Executes the region-scoped GET request and builds an EvidenceSnapshot dataclass.

Public Methods

Method Description
get Retrieves an immutable evidence snapshot by evidence_ref.

Retrieve Immutable Evidence Snapshot

{
    "title": "Retrieve Immutable Evidence Snapshot",
    "description": "Fetches a retained evidence snapshot using the evidence_ref returned from scoring. The snapshot is used for audit trails, adverse action notices, dispute handling, and regulatory responses.",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/evidence/{evidence_ref}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "evidence_ref",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Immutable evidence snapshot",
            "body": "{\n    \"evidence_ref\": \"evd_01J8R2J2R7G4Q5E7M6P9N1K2L3\",\n    \"consent_id\": \"con_01J8R2H9QK7A8B6C5D4E3F2G1H\",\n    \"applicant_id\": \"app_demo_001\",\n    \"snapshot_version\": \"v1\",\n    \"created_at\": \"2025-01-15T10:22:31Z\",\n    \"score_inputs\": {\n        \"payment_behavior\": {\n            \"payments_observed\": 24,\n            \"avg_payment_delay_days\": 2,\n            \"late_payment_count_30d_plus\": 1\n        },\n        \"income\": {\n            \"monthly_net_income\": 6200,\n            \"income_stability_score\": 88\n        },\n        \"obligations\": {\n            \"total_monthly_obligations\": 1850,\n            \"obligation_to_income_ratio\": 0.298\n        }\n    },\n    \"kyc_result\": {\n        \"status\": \"PASSED\",\n        \"checks\": [\n            \"identity\",\n            \"sanctions\",\n            \"pep\",\n            \"aml\"\n        ]\n    },\n    \"delinquency_bucket\": \"CURRENT\"\n}"
        }
    }
}

Evidence Snapshot Model

Java Evidence Snapshot

sdks/java/src/main/java/com/joinlita/model/EvidenceSnapshot.java

Property Type Description
evidenceRef String Immutable reference returned by scoring and used to retrieve the snapshot.
consentId String Consent that authorized the data used to build the snapshot.
applicantId String Applicant tied to the snapshot.
snapshotVersion String Version identifier for the retained evidence payload.
createdAt String Snapshot creation timestamp.
scoreInputs Map<String, Object> Unstructured score input payload captured at scoring time.
kycResult Map<String, Object> Unstructured KYC payload captured at scoring time.
delinquencyBucket String Delinquency classification attached to the snapshot.

Node Evidence Snapshot

sdks/node/src/types.ts

Property Type Description
evidence_ref string Immutable evidence anchor returned by score retrieval.
consent_id string Consent that scoped the underlying data access.
applicant_id string Applicant identifier.
snapshot_version string Snapshot version tag.
created_at string Snapshot creation timestamp.
score_inputs.payment_behavior.payments_observed number Count of observed payments.
score_inputs.payment_behavior.avg_payment_delay_days number Average payment delay in days.
score_inputs.payment_behavior.late_payment_count_30d_plus number Count of late payments past 30 days.
score_inputs.income.monthly_net_income number Monthly net income captured for scoring.
score_inputs.income.income_stability_score number Income stability score.
score_inputs.obligations.total_monthly_obligations number Total monthly obligations.
score_inputs.obligations.obligation_to_income_ratio number Obligation-to-income ratio.
kyc_result.status KycStatus Summary status of the KYC result.
kyc_result.checks string[] Names of checks associated with the evidence snapshot.
delinquency_bucket DelinquencyBucket Delinquency classification.

Python Evidence Snapshot

sdks/python/lita/types.py

Property Type Description
evidence_ref str Immutable evidence anchor.
consent_id str Consent that authorized the data access.
applicant_id str Applicant identifier.
snapshot_version str Version identifier.
created_at str Snapshot creation timestamp.
score_inputs Dict[str, Any] Snapshot score input payload.
kyc_result Dict[str, Any] Snapshot KYC payload.
delinquency_bucket DelinquencyBucket Delinquency classification.

Java Consents Resource

Note: The Java EvidenceSnapshot model keeps score_inputs and kyc_result as generic maps, while the Node and Python SDKs expose structured fields for score_inputs and kyc_result. The HTTP payload is the same, but Java callers must inspect nested keys dynamically.

sdks/java/src/main/java/com/joinlita/resources/ConsentsResource.java

Properties

Property Type Description
http HttpClient Shared HTTP transport for consent-backed retrieval and lifecycle operations.

Constructor Dependencies

Type Description
HttpClient Executes consent, score, transaction, and KYC requests.

Public Methods

Method Description
create Creates a consent and returns the consent payload.
get Retrieves the current consent state.
revoke Revokes an active consent.
getScore Retrieves the computed score for a consent and exposes evidence_ref.
listTransactions Lists paginated transactions for a consent.
getKyc Retrieves KYC and AML check results for a consent.

Node Consents Resource

sdks/node/src/resources/consents.ts

Properties

Property Type Description
http HttpClient Shared HTTP transport for consent-backed retrieval and lifecycle operations.

Constructor Dependencies

Type Description
HttpClient Executes consent, score, transaction, and KYC requests.

Public Methods

Method Description
create Creates a consent and returns the consent payload.
get Retrieves the current consent state.
revoke Revokes an active consent and returns the narrowed revoke payload.
getScore Retrieves the computed score for a consent and exposes evidence_ref.
listTransactions Lists paginated transactions for a consent.
getKyc Retrieves KYC and AML check results for a consent.

Python Consents Resource

sdks/python/lita/resources/consents.py

Properties

Property Type Description
_http HttpClient Shared HTTP transport for consent-backed retrieval and lifecycle operations.

Constructor Dependencies

Type Description
HttpClient Executes consent, score, transaction, and KYC requests.

Public Methods

Method Description
create Creates a consent and returns the consent payload.
get Retrieves the current consent state.
revoke Revokes an active consent.
get_score Retrieves the computed score for a consent and exposes evidence_ref.
list_transactions Lists paginated transactions for a consent.
get_kyc Retrieves KYC and AML check results for a consent.
{
    "title": "Create Consent",
    "description": "Creates a consent record that scopes downstream transaction and KYC retrieval.",
    "method": "POST",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/consents",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "application/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": "Consent record",
            "body": "{\n    \"consent_id\": \"con_01J8R2H9QK7A8B6C5D4E3F2G1H\",\n    \"status\": \"ACTIVE\",\n    \"applicant_id\": \"app_demo_001\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"redirect_url\": \"https://example.com/consent/redirect\",\n    \"created_at\": \"2025-01-15T10:00:00Z\",\n    \"activated_at\": \"2025-01-15T10:05:00Z\",\n    \"expires_at\": \"2025-02-14T10:05:00Z\",\n    \"revoked_at\": null,\n    \"connections\": [\n        {\n            \"connection_id\": \"conn_01J8R2K1R9Z9Q2X4Y6W8E0A1B2\",\n            \"provider\": \"bank_x\",\n            \"status\": \"ACTIVE\"\n        }\n    ]\n}"
        }
    }
}
{
    "title": "Get Consent",
    "description": "Fetches the current consent state for lifecycle-aware retrieval and access control checks.",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/consents/{consent_id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent record",
            "body": "{\n    \"consent_id\": \"con_01J8R2H9QK7A8B6C5D4E3F2G1H\",\n    \"status\": \"ACTIVE\",\n    \"applicant_id\": \"app_demo_001\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"redirect_url\": \"https://example.com/consent/redirect\",\n    \"created_at\": \"2025-01-15T10:00:00Z\",\n    \"activated_at\": \"2025-01-15T10:05:00Z\",\n    \"expires_at\": \"2025-02-14T10:05:00Z\",\n    \"revoked_at\": null,\n    \"connections\": [\n        {\n            \"connection_id\": \"conn_01J8R2K1R9Z9Q2X4Y6W8E0A1B2\",\n            \"provider\": \"bank_x\",\n            \"status\": \"ACTIVE\"\n        }\n    ]\n}"
        }
    }
}
{
    "title": "Revoke Consent",
    "description": "Revokes an active consent and terminates downstream access tied to that consent.",
    "method": "DELETE",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/consents/{consent_id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Revoked consent record",
            "body": "{\n    \"consent_id\": \"con_01J8R2H9QK7A8B6C5D4E3F2G1H\",\n    \"status\": \"REVOKED\",\n    \"applicant_id\": \"app_demo_001\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"redirect_url\": \"https://example.com/consent/redirect\",\n    \"created_at\": \"2025-01-15T10:00:00Z\",\n    \"activated_at\": \"2025-01-15T10:05:00Z\",\n    \"expires_at\": \"2025-02-14T10:05:00Z\",\n    \"revoked_at\": \"2025-01-20T09:30:00Z\",\n    \"connections\": [\n        {\n            \"connection_id\": \"conn_01J8R2K1R9Z9Q2X4Y6W8E0A1B2\",\n            \"provider\": \"bank_x\",\n            \"status\": \"REVOKED\"\n        }\n    ]\n}"
        }
    }
}
{
    "title": "Get Consent Score with Evidence Ref",
    "description": "Retrieves the computed score for a consent. The returned evidence_ref anchors the immutable evidence snapshot used by audit, dispute, and regulatory flows.",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/consents/{consent_id}/score",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Computed score and evidence anchor",
            "body": "{\n    \"consent_id\": \"con_01J8R2H9QK7A8B6C5D4E3F2G1H\",\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        \"stable_income\",\n        \"low_obligation_ratio\",\n        \"on_time_payments\"\n    ],\n    \"evidence_ref\": \"evd_01J8R2J2R7G4Q5E7M6P9N1K2L3\",\n    \"scored_at\": \"2025-01-15T10:22:31Z\",\n    \"model_version\": \"2025.01\"\n}"
        }
    }
}
{
    "title": "List Consent Transactions",
    "description": "Lists paginated transactions authorized by the consent, with optional limit, cursor, from_date, and to_date filters.",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/consents/{consent_id}/data/transactions",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "limit",
            "value": "100",
            "required": false
        },
        {
            "key": "cursor",
            "value": "txn_cursor_001",
            "required": false
        },
        {
            "key": "from_date",
            "value": "2025-01-01",
            "required": false
        },
        {
            "key": "to_date",
            "value": "2025-01-31",
            "required": false
        }
    ],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Paginated transaction list",
            "body": "{\n    \"data\": [\n        {\n            \"transaction_id\": \"txn_01J8R2M0A1B2C3D4E5F6G7H8I9\",\n            \"date\": \"2025-01-12\",\n            \"amount\": 128.45,\n            \"currency\": \"USD\",\n            \"description\": \"Card purchase\",\n            \"category\": \"card_payment\",\n            \"type\": \"DEBIT\"\n        }\n    ],\n    \"next_cursor\": \"txn_cursor_002\",\n    \"total_count\": 143\n}"
        }
    }
}
{
    "title": "Get Consent KYC Results",
    "description": "Retrieves KYC and AML compliance check results for the consent, including named check details when present.",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/consents/{consent_id}/kyc",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "KYC result",
            "body": "{\n    \"consent_id\": \"con_01J8R2H9QK7A8B6C5D4E3F2G1H\",\n    \"status\": \"PASSED\",\n    \"checks\": {\n        \"identity\": {\n            \"status\": \"PASSED\",\n            \"method\": \"document\",\n            \"lists_screened\": [\n                \"government_id\"\n            ],\n            \"risk_level\": \"LOW\"\n        },\n        \"sanctions\": {\n            \"status\": \"PASSED\",\n            \"method\": \"screening\",\n            \"lists_screened\": [\n                \"ofac\"\n            ],\n            \"risk_level\": \"LOW\"\n        },\n        \"pep\": {\n            \"status\": \"PASSED\",\n            \"method\": \"screening\",\n            \"lists_screened\": [\n                \"pep_global\"\n            ],\n            \"risk_level\": \"LOW\"\n        },\n        \"aml\": {\n            \"status\": \"PASSED\",\n            \"method\": \"monitoring\",\n            \"lists_screened\": [\n                \"aml_watchlist\"\n            ],\n            \"risk_level\": \"LOW\"\n        }\n    },\n    \"completed_at\": \"2025-01-15T10:20:00Z\"\n}"
        }
    }
}

sdks/java/src/main/java/com/joinlita/model/Consent.java

Property Type Description
consentId String Consent identifier.
status String Consent state.
applicantId String Applicant identifier.
purpose String Consent purpose.
redirectUrl String Redirect URL returned when the consent flow is created.
createdAt String Creation timestamp.
activatedAt String Activation timestamp.
expiresAt String Expiration timestamp.
revokedAt String Revocation timestamp.
connections List<Connection> Linked connections associated with the consent.

sdks/node/src/types.ts

Property Type Description
consent_id string Consent identifier.
status ConsentStatus Consent state.
applicant_id string Applicant identifier.
purpose ConsentPurpose Consent purpose.
redirect_url string Redirect URL returned by consent creation.
created_at string Creation timestamp.
activated_at string Activation timestamp.
expires_at string Expiration timestamp.
revoked_at string Revocation timestamp.
connections Connection[] Linked connections associated with the consent.

sdks/python/lita/types.py

Property Type Description
consent_id str Consent identifier.
status ConsentStatus Consent state.
applicant_id str Applicant identifier.
purpose ConsentPurpose Consent purpose.
expires_at str Expiration timestamp.
redirect_url Optional[str] Redirect URL returned by consent creation.
created_at Optional[str] Creation timestamp.
activated_at Optional[str] Activation timestamp.
revoked_at Optional[str] Revocation timestamp.
connections List[Connection] Linked connections associated with the consent.

Score

Note: revoke is typed differently across SDKs. The Node SDK narrows the return value to consent_id, status, and revoked_at, while the Java and Python SDKs deserialize the full Consent payload. The DELETE path is the same, but client expectations differ.

sdks/java/src/main/java/com/joinlita/model/Score.java

sdks/node/src/types.ts

sdks/python/lita/types.py

Property Type Description
consent_id / consentId string / String Consent that produced the score.
applicant_id / applicantId string / String Applicant identifier.
score number / int Computed score value.
score_range / scoreRange object / Map<String, Integer> / ScoreRange Score bounds for the model output.
decision ScoreDecision / String Scoring decision.
score_factors / scoreFactors string[] / List<String> Drivers used by the score model.
evidence_ref / evidenceRef string / String Immutable anchor for evidence retrieval.
scored_at / scoredAt string / String Scoring timestamp.
model_version / modelVersion string / String Score model version.

Transaction

sdks/java/src/main/java/com/joinlita/model/Transaction.java

sdks/node/src/types.ts

sdks/python/lita/types.py

Property Type Description
transaction_id / transactionId string / String Transaction identifier.
date string Transaction date.
amount number / double / float Transaction amount.
currency string ISO currency code.
description string Transaction description.
category string Transaction category.
type TransactionType / String Transaction direction.

Transaction List Response

sdks/java/src/main/java/com/joinlita/model/TransactionListResponse.java

sdks/node/src/types.ts

sdks/python/lita/types.py

Property Type Description
data Transaction[] / List<Transaction> Page of transaction records.
next_cursor / nextCursor `string \ null/String/Optional[str]`
total_count / totalCount number / int Total number of transactions available.

Transaction List Params

sdks/java/src/main/java/com/joinlita/params/TransactionListParams.java

sdks/node/src/types.ts

Property Type Description
limit number / Integer Maximum number of transactions to return.
cursor string / String Pagination cursor.
from_date / fromDate string / String ISO 8601 start date filter.
to_date / toDate string / String ISO 8601 end date filter.

KYC Check Detail

sdks/node/src/types.ts

sdks/python/lita/types.py

Property Type Description
status KycStatus Status of the named check.
method string / Optional[str] Check method used.
lists_screened string[] / Optional[List[str]] Lists screened by the check.
risk_level string / Optional[str] Risk classification returned by the check.

KYC Result

sdks/java/src/main/java/com/joinlita/model/KycResult.java

sdks/node/src/types.ts

sdks/python/lita/types.py

Property Type Description
consent_id / consentId string / String Consent tied to the KYC result.
status KycStatus / String Overall KYC status.
checks Record<string, KycCheckDetail> / Map<String, Map<String, Object>> / Dict[str, KycCheckDetail] Named check results.
completed_at / completedAt string / String Completion timestamp.

KYC and Evidence State Enums

  • ConsentPurpose: RENTAL_SCREENING, LENDING_UNDERWRITING, EMPLOYMENT_SCREENING, ACCOUNT_OPENING
  • DataCategory: transactions, income, payment_behavior, obligations, employment
  • ConsentStatus: PENDING, ACTIVE, REVOKED, EXPIRED
  • TransactionType: DEBIT, CREDIT
  • KycStatus: PASSED, REVIEW, FAILED, PENDING
  • DelinquencyBucket: CURRENT, 30_DPD, 60_DPD, 90_PLUS_DPD, CHARGE_OFF, WRITE_OFF
  • ScoreDecision: APPROVE, REVIEW, DECLINE, INSUFFICIENT_DATA

Feature Flows

Score to Evidence Snapshot Retrieval

sequenceDiagram
    participant C as SDK Consumer
    participant R as ConsentsResource
    participant H as HttpClient
    participant A as Lita API
    participant E as EvidenceResource

    C->>R: getScore consentId
    R->>H: GET consents consentId score
    H->>A: Authorization and X Request Id
    A-->>H: Score with evidence ref
    H-->>R: Score
    R-->>C: Score

    C->>E: get evidenceRef
    E->>H: GET evidence evidenceRef
    H->>A: Authorization and X Request Id
    A-->>H: EvidenceSnapshot
    H-->>E: EvidenceSnapshot
    E-->>C: EvidenceSnapshot
  1. The caller retrieves the score for a consent.
  2. The score payload includes evidence_ref.
  3. The caller uses evidence_ref to fetch the immutable evidence snapshot.
  4. The evidence snapshot can then be stored or cited in audit, dispute, and regulatory workflows.
sequenceDiagram
    participant C as SDK Consumer
    participant R as ConsentsResource
    participant H as HttpClient
    participant A as Lita API

    C->>R: listTransactions consentId params
    R->>H: GET consents consentId data transactions
    H->>A: Authorization and X Request Id
    A-->>H: TransactionListResponse
    H-->>R: TransactionListResponse
    R-->>C: TransactionListResponse
  1. The caller supplies consent_id and optional pagination filters.
  2. The transport serializes limit, cursor, from_date, and to_date only when present.
  3. The response returns data, next_cursor, and total_count for cursor-based paging.
sequenceDiagram
    participant C as SDK Consumer
    participant R as ConsentsResource
    participant H as HttpClient
    participant A as Lita API

    C->>R: getKyc consentId
    R->>H: GET consents consentId kyc
    H->>A: Authorization and X Request Id
    A-->>H: KycResult
    H-->>R: KycResult
    R-->>C: KycResult
  1. The caller retrieves KYC or AML results using the same consent scope.
  2. The response includes the overall status and named check results.
  3. The payload can be joined with evidence or transaction history through the same consent_id.

State and Contract Shapes

Retrieval Anchors

  • evidence_ref anchors immutable evidence retrieval.
  • consent_id anchors access scope for transactions and KYC.
  • snapshot_version distinguishes retained evidence snapshots over time.
  • next_cursor advances transaction pagination without changing the consent scope.

Result Semantics

  • EvidenceSnapshot is immutable after creation and is explicitly retained for 7 years from creation in the Java and Node documentation comments.
  • Score ties model output to both consent_id and evidence_ref.
  • KycResult.checks is a named object keyed by check name in Node and Python, and a map in Java.
  • TransactionListResponse.data is the page payload; total_count reflects the full set available to the consent.

Error Handling

The SDK transports convert non-2xx responses into typed exceptions that preserve the response body fields exposed by the API. The transport surfaces the machine-readable error code, request ID, and retryability flag so callers can bind failures to a specific request.

Node Error Mapping

sdks/node/src/errors.ts

sdks/node/src/client.ts

  • LitaError captures status, code, requestId, and retryable.
  • LitaAuthError is thrown for 401 and 403.
  • LitaNotFoundError is thrown for 404.
  • LitaRateLimitError is thrown for 429 and includes Retry-After when present.
  • LitaWebhookSignatureError is thrown by webhook signature verification helpers, not by retrieval endpoints.

Java Error Mapping

sdks/java/src/main/java/com/joinlita/LitaException.java

sdks/java/src/main/java/com/joinlita/HttpClient.java

  • Non-2xx responses are deserialized into error.code, error.message, error.request_id, and error.retryable.
  • Those fields are passed into LitaException.
  • The exception preserves the HTTP status code and request ID for support and audit correlation.

Cross-SDK Contract Differences

Dependencies

Note: KycResult is strictly typed in Node and Python, but Java keeps the checks payload as a nested map. The same endpoint is consumed in all three SDKs, but Java callers must resolve named checks dynamically. Note: TransactionListParams uses snake_case keys in Node and camelCase builder methods in Java. The serialized query parameters still become limit, cursor, from_date, and to_date on the wire.

  • HttpClient in all SDKs is the shared dependency for consent and evidence retrieval.
  • Node uses fetch, AbortController, and randomUUID for request execution and timeout control.
  • Java uses java.net.http.HttpClient plus Jackson for response mapping.
  • Python resource classes consume the shared HttpClient and build typed dataclass instances from raw payloads.
  • LitaClientOptions and Lita.Builder control region routing and sandbox prefixing, which directly affects the final URL path.

Key Classes Reference

Class Responsibility
Lita.java SDK entry point that wires consent, evidence, feature, and status resources through one HTTP transport.
EvidenceResource.java Retrieves immutable evidence snapshots by evidence_ref.
ConsentsResource.java Retrieves consent-scoped score, transaction, and KYC data, plus consent lifecycle records.
EvidenceSnapshot.java Represents the retained snapshot returned by evidence retrieval.
Score.java Represents scoring output and the evidence_ref anchor.
Transaction.java Represents one consent-scoped transaction record.
TransactionListResponse.java Represents a paginated transaction response.
KycResult.java Represents the KYC result payload returned for a consent.
TransactionListParams.java Encapsulates transaction list filters and pagination inputs.
Consent.java Represents consent lifecycle state and linked connections.
ConsentCreateParams.java Captures the fields required to create a consent.
index.ts Node SDK entry point that exposes the Lita class and resource facades.
evidence.ts Node evidence retrieval resource.
consents.ts Node consent-backed retrieval resource.
types.ts Node contract definitions for evidence, score, transactions, and KYC.
evidence.py Python evidence retrieval resource.
consents.py Python consent-backed retrieval resource.
types.py Python contract definitions for evidence, score, transactions, and KYC.