Consent and Evidence Management Domain

Overview

This domain covers two related workflows: immutable evidence retrieval for audits and regulatory review, and asynchronous job status polling for long-running processing. The evidence path centers on the evidence_ref identifier returned by scoring workflows, while the status path exposes the live lifecycle of background jobs so partners can wait for completion when webhooks are not practical.

Across the US and JP API surfaces, the documentation and SDKs treat evidence as a permanent audit artifact. The retained snapshot is meant to be stored alongside the partner’s own decision record, and the status endpoint is the fallback for monitoring async work until a job reaches COMPLETE or FAILED.

Retention and Audit Model

[!IMPORTANT] Store the evidence_ref with the internal decision record. The docs call it the primary reference for audits, disputes, adverse action notices, regulatory review, and decision replay.

Lita documents evidence snapshots as immutable and audit-ready:

  • Created at the moment of scoring.
  • Retrievable for the full 7-year retention period.
  • Available even after consent revocation.
  • Retained alongside consent records and access logs.
  • Not subject to artificial expiration in the US and JP API docs.

The audit-facing usage is consistent across the documented surfaces:

  • docs/docs-api.md calls evidence_ref the permanent immutable audit record for an assessment event.
  • documents/us-api.md and documents/jp-api.md state that Lita retains consent records, access logs, and evidence snapshots.
  • The SDK docstrings for evidence retrieval describe the endpoint as suitable for audit trails, adverse action notices, and regulatory responses.

Async Status Polling Model

Async work is exposed through a dedicated job status endpoint. The docs describe polling as a fallback pattern and recommend webhooks whenever possible.

Polling guidance documented in the repository:

  • Prefer webhooks over polling.
  • Poll GET /{region}/status/{job_id} only when webhook delivery is not feasible.
  • Keep polling under 2 requests/second per job ID.
  • Treat PROCESSING, COMPLETE, and FAILED as the job states.
  • Stop polling once the job reaches a terminal state.

Architecture Overview

flowchart TB
    subgraph SDKs [Official SDKs]
        NodeEvidence[Node EvidenceResource]
        NodeStatus[Node StatusResource]
        PythonEvidence[Python EvidenceResource]
        PythonStatus[Python StatusResource]
        JavaEvidence[Java EvidenceResource]
        JavaStatus[Java StatusResource]
    end

    subgraph Transport [HTTP Transport]
        JavaHttp[Java HttpClient]
        SharedHttp[SDK HttpClient]
    end

    subgraph API [Lita API]
        EvidenceApi[Evidence Snapshot Endpoint]
        StatusApi[Async Job Status Endpoint]
    end

    AuditStore[Audit Records]
    WorkflowEngine[Long Running Workflows]

    NodeEvidence --> SharedHttp
    NodeStatus --> SharedHttp
    PythonEvidence --> SharedHttp
    PythonStatus --> SharedHttp
    JavaEvidence --> JavaHttp
    JavaStatus --> JavaHttp

    SharedHttp --> EvidenceApi
    SharedHttp --> StatusApi
    JavaHttp --> EvidenceApi
    JavaHttp --> StatusApi

    EvidenceApi --> AuditStore
    StatusApi --> WorkflowEngine

The SDKs are thin wrappers over the REST API. They share one transport concern: inject authentication, add a traceable request ID, and deserialize the response into the language-specific model.

Evidence and Status API Endpoints

Retrieve Evidence Snapshot

{
    "title": "Retrieve Evidence Snapshot",
    "description": "Retrieves the immutable evidence snapshot by evidence reference. The snapshot is retained for the full 7-year retention period and remains available after consent revocation.",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/evidence/{evidence_ref}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<request-id>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "region",
            "type": "string",
            "required": true
        },
        {
            "key": "evidence_ref",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Immutable evidence snapshot",
            "body": "{\n    \"evidence_ref\": \"ev_5sKjL2mN8pQr\",\n    \"consent_id\": \"con_8kXpL9mR2nQv\",\n    \"applicant_id\": \"app_clean\",\n    \"snapshot_version\": \"1.2.0\",\n    \"created_at\": \"2026-03-31T09:05:12Z\",\n    \"score_inputs\": {\n        \"payment_behavior\": {\n            \"payments_observed\": 36,\n            \"avg_payment_delay_days\": 0,\n            \"late_payment_count_30d_plus\": 0\n        },\n        \"income\": {\n            \"monthly_net_income\": 5200,\n            \"income_stability_score\": 0.96\n        },\n        \"obligations\": {\n            \"total_monthly_obligations\": 1150,\n            \"obligation_to_income_ratio\": 0.22\n        },\n        \"cashflow\": {\n            \"net_cashflow\": 3250,\n            \"cashflow_volatility\": 0.12\n        }\n    },\n    \"kyc_result\": {\n        \"status\": \"VERIFIED\",\n        \"checks\": [\n            \"identity\",\n            \"sanctions\",\n            \"pep\",\n            \"aml\"\n        ]\n    },\n    \"delinquency_bucket\": \"CURRENT\"\n}"
        }
    }
}

Get Async Job Status

{
    "title": "Get Async Job Status",
    "description": "Polls the status of an asynchronous processing job. The endpoint is rate-limited to 2 requests per second per job ID and should be used only when webhooks are not feasible.",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/{region}/status/{job_id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<request-id>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "region",
            "type": "string",
            "required": true
        },
        {
            "key": "job_id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Current job status",
            "body": "{\n    \"job_id\": \"job_7tYuI8oP3qRs\",\n    \"status\": \"PROCESSING\",\n    \"consent_id\": \"con_8kXpL9mR2nQv\"\n}"
        }
    }
}

Feature Flows

Evidence Retrieval for Audit Review

sequenceDiagram
    participant Partner as Partner Service
    participant SDK as Evidence Resource
    participant Http as Http Client
    participant API as Lita API
    participant Store as Audit Store

    Partner->>SDK: get evidenceRef
    SDK->>Http: GET evidence evidenceRef
    Http->>API: GET /{region}/evidence/{evidence_ref}
    API-->>Http: EvidenceSnapshot
    Http-->>SDK: EvidenceSnapshot
    SDK-->>Partner: Immutable audit payload
    Partner->>Store: Persist evidenceRef and snapshot

This flow supports audit review, adverse action notices, regulatory response, disputes, and decision replay. The evidence snapshot is the stable record that ties a business decision to the exact inputs used at scoring time.

Async Status Polling for Long Running Workflows

sequenceDiagram
    participant Workflow as Partner Workflow
    participant SDK as Status Resource
    participant Http as Http Client
    participant API as Lita API

    Workflow->>SDK: get jobId
    SDK->>Http: GET status jobId
    Http->>API: GET /{region}/status/{job_id}
    API-->>Http: JobStatusResponse
    Http-->>SDK: JobStatusResponse
    SDK-->>Workflow: PROCESSING

    loop Until terminal status
        Workflow->>SDK: get jobId
        SDK->>Http: GET status jobId
        Http->>API: GET /{region}/status/{job_id}
        API-->>Http: JobStatusResponse
        Http-->>SDK: JobStatusResponse
        SDK-->>Workflow: COMPLETE or FAILED
    end

This flow is the documented fallback when a webhook-driven workflow is not available. The rate limit is per job ID, so the polling loop must stay within the documented ceiling.

SDK Surfaces

HTTP Transport

Java HTTP Client

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

Constructor dependencies

Type Description
String apiKey Bearer token injected into the Authorization header
String region Region prefix used to build /{region}/... paths
String baseUrl API root, defaulting to https://api.joinlita.com/api/v1
Duration timeout Request timeout, defaulting to 30 seconds
boolean sandbox Switches the region prefix to the sandbox path variant

Properties

Property Type Description
DEFAULT_BASE_URL String Default API base URL constant
apiKey String Stored API key used for request auth
regionPrefix String Resolved region path, including sandbox suffix when enabled
baseUrl String Normalized base URL with trailing slash removed
httpClient java.net.http.HttpClient Underlying transport client
MAPPER ObjectMapper Shared JSON mapper used for request and response processing

Methods

Method Description
get Executes a GET request and deserializes the response
post Executes a JSON POST request and deserializes the response
delete Executes a DELETE request and deserializes the response
baseRequest Builds a request with auth, request ID, and timeout
execute Sends the request and converts success or error responses

[!NOTE] baseRequest sends X-Request-Id as req- plus a UUID. The documented header requirement calls for a UUID v4 value, so Java SDK requests carry a prefixed trace value rather than a bare UUID string.

The transport layer is the place where auth and traceability are added before any endpoint call. On non-2xx responses, execute parses the error envelope and throws a Java exception with the HTTP status, error code, message, request ID, and retryability flag.

Java SDK

Evidence Resource

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

Constructor dependencies

Type Description
HttpClient Shared transport used for authenticated GET calls

Properties

Property Type Description
http HttpClient Injected transport instance

Methods

Method Description
get Retrieves an immutable evidence snapshot by evidence_ref

Status Resource

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

Constructor dependencies

Type Description
HttpClient Shared transport used for authenticated GET calls

Properties

Property Type Description
http HttpClient Injected transport instance

Methods

Method Description
get Polls the current status of an async processing job

Evidence Snapshot

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

Properties

Property Type Description
evidenceRef String Immutable evidence reference
consentId String Consent associated with the snapshot
applicantId String Applicant identifier
snapshotVersion String Snapshot schema or model version
createdAt String ISO 8601 creation timestamp
scoreInputs Map<String, Object> Raw score input payload, including feature groups
kycResult Map<String, Object> Compliance result payload
delinquencyBucket String Payment status bucket used for the assessment

The Java model accepts arbitrary nested maps for scoreInputs and kycResult, which matches the evidence payload pattern used by the API examples.

Job Status Response

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

Properties

Property Type Description
jobId String Async job identifier
status String Current job state
consentId String Consent associated with the job
completedAt String Completion timestamp, when available
error Map<String, String> Error payload returned for failed jobs

Node SDK

Evidence Resource

sdks/node/src/resources/evidence.ts

Constructor dependencies

Type Description
HttpClient Shared transport used for authenticated GET calls

Properties

Property Type Description
http HttpClient Injected transport instance

Methods

Method Description
get Retrieves an immutable evidence snapshot by evidence_ref

Status Resource

sdks/node/src/resources/status.ts

Constructor dependencies

Type Description
HttpClient Shared transport used for authenticated GET calls

Properties

Property Type Description
http HttpClient Injected transport instance

Methods

Method Description
get Polls the current status of an async processing job

Evidence Snapshot

sdks/node/src/types.ts

Properties

Property Type Description
evidence_ref string Immutable evidence reference
consent_id string Consent associated with the snapshot
applicant_id string Applicant identifier
snapshot_version string Snapshot schema or model version
created_at string ISO 8601 creation timestamp
score_inputs { payment_behavior?: { payments_observed: number; avg_payment_delay_days: number; late_payment_count_30d_plus: number; }; income?: { monthly_net_income: number; income_stability_score: number; }; obligations?: { total_monthly_obligations: number; obligation_to_income_ratio: number; }; } Structured evidence inputs captured at scoring time
kyc_result { status: KycStatus; checks: string[]; } KYC and compliance result payload
delinquency_bucket DelinquencyBucket Payment status classification

Job Status Response

[!NOTE] The Node evidence snapshot type models score_inputs without the cashflow branch that appears in the documented evidence payload. The Node KycStatus and DelinquencyBucket literal sets also differ from the values shown in the API docs. Treat the wire payload as the source of truth when consuming evidence snapshots.

sdks/node/src/types.ts

Properties

Property Type Description
job_id string Async job identifier
status JobStatus Current job state
consent_id string Consent associated with the job
completed_at string Completion timestamp, when available
error { code: string; message: string } Error payload returned for failed jobs

Enumerations

  • JobStatus: PROCESSING, COMPLETE, FAILED
  • DelinquencyBucket: CURRENT, 30_DPD, 60_DPD, 90_PLUS_DPD, CHARGE_OFF, WRITE_OFF
  • KycStatus: PASSED, REVIEW, FAILED, PENDING

Python SDK

Evidence Resource

sdks/python/lita/resources/evidence.py

Constructor dependencies

Type Description
HttpClient Shared transport used for authenticated GET calls

Properties

Property Type Description
_http HttpClient Injected transport instance

Methods

Method Description
get Retrieves an immutable evidence snapshot by evidence_ref

Status Resource

sdks/python/lita/resources/status.py

Constructor dependencies

Type Description
HttpClient Shared transport used for authenticated GET calls

Properties

Property Type Description
_http HttpClient Injected transport instance

Methods

Method Description
get Polls the current status of an async processing job

Evidence Snapshot

sdks/python/lita/types.py

Properties

Property Type Description
evidence_ref str Immutable evidence reference
consent_id str Consent associated with the snapshot
applicant_id str Applicant identifier
snapshot_version str Snapshot schema or model version
created_at str ISO 8601 creation timestamp
score_inputs Dict[str, Any] Structured evidence inputs captured at scoring time
kyc_result Dict[str, Any] KYC and compliance result payload
delinquency_bucket DelinquencyBucket Payment status classification

Job Status Response

sdks/python/lita/types.py

Properties

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 returned for failed jobs

State Management

Job Status Lifecycle

The job status payload uses a simple terminal-state model:

Status Meaning
PROCESSING The async job is still running
COMPLETE The job finished successfully
FAILED The job ended with an error

Status polling should continue only while the job is PROCESSING. Once a terminal state is returned, the workflow should stop polling and either proceed with downstream work or surface the failure.

Evidence Lifecycle

The evidence snapshot is immutable after creation:

  • It is created at scoring time.
  • It is identified by evidence_ref.
  • It is retained for the documented 7-year period.
  • It remains retrievable after consent revocation.
  • It is the audit artifact partners store with internal decision records.

Error Handling

The SDKs and docs expose the following failure patterns for this domain:

  • not_found
  • forbidden
  • rate_limited
  • score_not_ready
  • processing_error

The Java transport turns non-2xx responses into exceptions by parsing the API error envelope. That response parsing preserves the server error code, message, request ID, and retryability flag for audit and support workflows.

For status polling, rate_limited is the critical operational error because the endpoint is explicitly capped at 2 requests/second per job ID. For evidence retrieval, not_found and forbidden are the documented access failures.

Dependencies

  • HttpClient transport in the Java SDK and the equivalent transport abstractions in Node and Python.
  • Authorization bearer authentication.
  • X-Request-Id trace header.
  • Region-scoped paths for us and jp.
  • Evidence storage in the partner’s audit record or decision store.
  • Webhooks as the preferred async notification mechanism, with polling used as a fallback.

The retention model is shared across the documented US and JP API surfaces, and the evidence endpoint is designed to remain useful after the original consent is no longer active.

Testing Considerations

Key scenarios covered by this section:

  • Retrieve an evidence snapshot by evidence_ref.
  • Confirm the snapshot payload includes the stored consent and applicant IDs.
  • Validate that polling the status endpoint returns PROCESSING before completion and a terminal state afterward.
  • Verify polling stays within the documented per-job rate limit.
  • Verify evidence remains retrievable after consent revocation.
  • Verify failed status responses surface error details.
  • Verify SDK deserialization matches the response shape for evidence and job status payloads.

Key Classes Reference

Class Location Responsibility
EvidenceResource EvidenceResource.java Retrieves immutable evidence snapshots
StatusResource StatusResource.java Polls async job status
EvidenceSnapshot EvidenceSnapshot.java Models the evidence snapshot payload
JobStatusResponse JobStatusResponse.java Models the async job status payload
HttpClient HttpClient.java Adds auth, request IDs, and deserializes transport responses
EvidenceResource evidence.ts Node evidence retrieval client
StatusResource status.ts Node async status polling client
EvidenceSnapshot types.ts Node evidence snapshot type
JobStatusResponse types.ts Node async job status type
EvidenceResource evidence.py Python evidence retrieval client
StatusResource status.py Python async status polling client
EvidenceSnapshot types.py Python evidence snapshot type
JobStatusResponse types.py Python async job status type