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_refwith 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.mdcallsevidence_refthe permanent immutable audit record for an assessment event.documents/us-api.mdanddocuments/jp-api.mdstate 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, andFAILEDas 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]
baseRequestsendsX-Request-Idasreq-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_inputswithout thecashflowbranch that appears in the documented evidence payload. The NodeKycStatusandDelinquencyBucketliteral 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,FAILEDDelinquencyBucket:CURRENT,30_DPD,60_DPD,90_PLUS_DPD,CHARGE_OFF,WRITE_OFFKycStatus: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_foundforbiddenrate_limitedscore_not_readyprocessing_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
HttpClienttransport in the Java SDK and the equivalent transport abstractions in Node and Python.Authorizationbearer authentication.X-Request-Idtrace header.- Region-scoped paths for
usandjp. - 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
PROCESSINGbefore 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 |