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. |
Consent-Scoped Retrieval
Java Consents Resource
Note: The Java
EvidenceSnapshotmodel keepsscore_inputsandkyc_resultas generic maps, while the Node and Python SDKs expose structured fields forscore_inputsandkyc_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. |
Create 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}"
}
}
}
Get Consent
{
"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}"
}
}
}
Revoke Consent
{
"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}"
}
}
}
Get Consent Score with Evidence Ref
{
"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}"
}
}
}
List Consent Transactions
{
"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}"
}
}
}
Get Consent KYC Results
{
"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}"
}
}
}
Consent and Retrieval Contracts
Java Consent
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. |
Node 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. |
Python 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:
revokeis typed differently across SDKs. The Node SDK narrows the return value toconsent_id,status, andrevoked_at, while the Java and Python SDKs deserialize the fullConsentpayload. 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_OPENINGDataCategory:transactions,income,payment_behavior,obligations,employmentConsentStatus:PENDING,ACTIVE,REVOKED,EXPIREDTransactionType:DEBIT,CREDITKycStatus:PASSED,REVIEW,FAILED,PENDINGDelinquencyBucket:CURRENT,30_DPD,60_DPD,90_PLUS_DPD,CHARGE_OFF,WRITE_OFFScoreDecision: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
- The caller retrieves the score for a consent.
- The score payload includes
evidence_ref. - The caller uses
evidence_refto fetch the immutable evidence snapshot. - The evidence snapshot can then be stored or cited in audit, dispute, and regulatory workflows.
Consent Transaction Listing Flow
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
- The caller supplies
consent_idand optional pagination filters. - The transport serializes
limit,cursor,from_date, andto_dateonly when present. - The response returns
data,next_cursor, andtotal_countfor cursor-based paging.
Consent KYC Retrieval Flow
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
- The caller retrieves KYC or AML results using the same consent scope.
- The response includes the overall status and named check results.
- The payload can be joined with evidence or transaction history through the same
consent_id.
State and Contract Shapes
Retrieval Anchors
evidence_refanchors immutable evidence retrieval.consent_idanchors access scope for transactions and KYC.snapshot_versiondistinguishes retained evidence snapshots over time.next_cursoradvances transaction pagination without changing the consent scope.
Result Semantics
EvidenceSnapshotis immutable after creation and is explicitly retained for 7 years from creation in the Java and Node documentation comments.Scoreties model output to bothconsent_idandevidence_ref.KycResult.checksis a named object keyed by check name in Node and Python, and a map in Java.TransactionListResponse.datais the page payload;total_countreflects 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
LitaErrorcapturesstatus,code,requestId, andretryable.LitaAuthErroris thrown for401and403.LitaNotFoundErroris thrown for404.LitaRateLimitErroris thrown for429and includesRetry-Afterwhen present.LitaWebhookSignatureErroris 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, anderror.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:
KycResultis strictly typed in Node and Python, but Java keeps thecheckspayload as a nested map. The same endpoint is consumed in all three SDKs, but Java callers must resolve named checks dynamically. Note:TransactionListParamsuses snake_case keys in Node and camelCase builder methods in Java. The serialized query parameters still becomelimit,cursor,from_date, andto_dateon the wire.
HttpClientin all SDKs is the shared dependency for consent and evidence retrieval.- Node uses
fetch,AbortController, andrandomUUIDfor request execution and timeout control. - Java uses
java.net.http.HttpClientplus Jackson for response mapping. - Python resource classes consume the shared
HttpClientand build typed dataclass instances from raw payloads. LitaClientOptionsandLita.Buildercontrol 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. |