Architecture and Runtime Foundations - Contract-first documentation and regional specifications

Overview

The external contract layer in Dwilar/lita-api is defined by five documentation artifacts: docs/docs-api.md, documents/us-api.md, documents/jp-api.md, documents/us-api-openapi.yaml, and documents/jp-api-openapi.yaml. Together they define how partners authenticate, how consent is created and revoked, how data is retrieved, and how feature, score, evidence, and compliance artifacts are exposed by region.

The contract is explicitly pipeline-driven: Applicant → Consent → Data → Features → Score → Evidence. The prose reference describes the canonical partner flow and the immutable audit trail, while the regional documents and OpenAPI files pin the concrete US and JP surfaces used for client generation, endpoint parity checks, and regional examples.

Architecture Overview

flowchart TD
    subgraph ContractDocs [Contract Docs]
        DocsApi[docs docs-api md]
        USDoc[documents us-api md]
        JPDoc[documents jp-api md]
    end

    subgraph OpenAPIArtifacts [OpenAPI Artifacts]
        USOAS[documents us-api-openapi yaml]
        JPOAS[documents jp-api-openapi yaml]
    end

    subgraph RegionalSurfaces [Regional API Surfaces]
        USRegion[US region]
        JPRegion[JP region]
    end

    subgraph Pipeline [Canonical Pipeline]
        Applicant[Applicant]
        Consent[Consent]
        Data[Data]
        Features[Features]
        Score[Score]
        Evidence[Evidence]
    end

    DocsApi --> USDoc
    DocsApi --> JPDoc
    USDoc --> USOAS
    JPDoc --> JPOAS
    USOAS --> USRegion
    JPOAS --> JPRegion

    Applicant --> Consent
    Consent --> Data
    Data --> Features
    Features --> Score
    Score --> Evidence

Contract Layer Roles

Artifact Role Region Scope What It Defines
docs/docs-api.md Canonical developer reference us, jp Global pipeline, auth, idempotency, rate limits, error envelope, webhooks, SDK examples, and the region-parameterized REST contract
documents/us-api.md US regional prose spec us US-facing examples, consent flow, data retrieval, feature computation, and partner scoring callback
documents/jp-api.md Japan regional prose spec jp JP-facing examples, consent flow, data retrieval, feature computation, and partner scoring callback
documents/us-api-openapi.yaml US machine-readable contract us Concrete routes, bearer security schemes, schemas, and response models for US tooling
documents/jp-api-openapi.yaml Japan machine-readable contract jp Concrete routes, bearer security schemes, schemas, and response models for JP tooling

Canonical Processing Pipeline

[!NOTE] docs/docs-api.md states that all endpoints and schemas are identical across regions, but documents/us-api-openapi.yaml and documents/jp-api-openapi.yaml add concrete routes such as /receipt, /token, /tokens/refresh, /tokens/introspect, /data/accounts, /data/balances, /data/transactions/sync, and /decisions/replay. The prose reference and the machine-readable region specs therefore do not describe a single identical path set. [!NOTE] docs/docs-api.md requires X-Request-Id on every request, while the OpenAPI artifacts only model bearer authentication through partnerAuth and accessToken. Generated clients from the OpenAPI files need an additional header policy to preserve the documented tracing and idempotency behavior.

The published contract uses the same lifecycle vocabulary across all regions:

  1. Applicant — partner-assigned applicant_id.
  2. Consent — purpose-scoped authorization that gates access.
  3. Data — normalized account, transaction, income, and behavioral inputs.
  4. Features — derived financial behavior vectors and risk dimensions.
  5. Score — normalized 300–850 score with risk band and score factors.
  6. Evidence — immutable audit snapshot tied to the score event through evidence_ref.
Stage Primary Identifier Contracted Output
Applicant applicant_id Stable partner-owned identity
Consent consent_id Authorization state and region-scoped access rights
Data consent_id or token Transactions, balances, income, and other normalized financial records
Features consent_id Computed feature vector or async feature job
Score consent_id Score, risk band, score factors, and model version
Evidence evidence_ref Immutable audit record, score inputs, and compliance context

Contract Schemas

Global Reference Models

Derived from docs/docs-api.md

Property Type Description
consent_id string Consent identifier returned after creation
status string Consent state such as PENDING
applicant_id string Partner-assigned applicant identifier
purpose string Declared purpose
redirect_url string Hosted consent completion URL
created_at string Creation timestamp
expires_at string Consent expiration timestamp
Property Type Description
consent_id string Consent identifier
status string Current consent state
applicant_id string Partner-assigned applicant identifier
purpose string Declared purpose
activated_at string Activation timestamp
expires_at string Expiration timestamp
connections array Linked financial connections

Connection

Property Type Description
connection_id string Linked connection identifier
provider string Financial institution or provider name
status string Connection state

Async Feature Job Response

Property Type Description
job_id string Asynchronous processing job identifier
status string Job state such as PROCESSING
consent_id string Consent the job belongs to
estimated_completion_ms number Estimated completion time

Score Response

Property Type Description
consent_id string Consent identifier
applicant_id string Partner-assigned applicant identifier
score number Normalized score
score_range object min and max score bounds
risk_band string Qualitative risk band
score_factors array Human-readable score factors
evidence_ref string Immutable evidence reference
scored_at string Score timestamp
model_version string Scoring model version

Feature Vector Response

Property Type Description
consent_id string Consent identifier
applicant_id string Partner-assigned applicant identifier
features object Computed feature vector
computed_at string Feature computation timestamp
feature_version string Feature model version

Risk Profile Response

Property Type Description
consent_id string Consent identifier
applicant_id string Partner-assigned applicant identifier
risk_profile object Human-readable structured risk summary
generated_at string Generation timestamp

Evidence Snapshot Response

Property Type Description
evidence_ref string Immutable evidence snapshot identifier
consent_id string Consent identifier
applicant_id string Partner-assigned applicant identifier
snapshot_version string Snapshot version
created_at string Snapshot creation timestamp
score_inputs object Feature inputs used in scoring
kyc_result object Compliance screening result
delinquency_bucket string Payment status bucket

KYC Response

Property Type Description
consent_id string Consent identifier
status string Overall KYC status
checks object Identity, sanctions, PEP, and AML results
completed_at string Completion timestamp

Transactions Response

Property Type Description
data array Normalized transaction records
next_cursor string Pagination cursor
total_count number Total record count

Job Status Response

Property Type Description
job_id string Async job identifier
status string Job state
consent_id string Consent identifier
completed_at string Completion timestamp
Property Type Description
consent_id string Consent identifier
status string Revocation state
revoked_at string Revocation timestamp

OpenAPI Models

Derived from documents/us-api-openapi.yaml and documents/jp-api-openapi.yaml

CreateConsentRequest

Property Type Description
user object Requesting user envelope
user.country string Country code
purpose string Consent purpose
data_categories array[string] Requested data categories
refresh_permissions object Refresh policy
refresh_permissions.enabled boolean Refresh enablement flag
refresh_permissions.max_refresh_per_day integer Daily refresh limit

ConsentResponse

Property Type Description
consent_id string Consent identifier
status string Consent status
expires_at string Expiration timestamp
auth object Authorization details
auth.link_url string Hosted authorization URL
auth.link_token string Authorization token

ConsentReceipt

Property Type Description
consent_id string Consent identifier
purpose string Purpose
data_categories array[string] Granted categories
disclosure_version string Disclosure version
status string Consent status
created_at string Creation timestamp
revoked_at string Revocation timestamp, nullable

ConsentRevoked

Property Type Description
consent_id string Consent identifier
status string Expected REVOKED

TokenExchangeRequest

Property Type Description
authorization_code string Consent authorization code

TokenExchangeResponse

Property Type Description
access_token string Access token
refresh_token string Refresh token
expires_in integer Token lifetime in seconds
token_type string Token type
scope string Granted scope

TokenRefreshRequest

Property Type Description
refresh_token string Refresh token

TokenIntrospectRequest

Property Type Description
token string Token to introspect

TokenIntrospectResponse

Property Type Description
active boolean Whether the token is active
expires_at string Expiration timestamp
consent_id string Consent identifier
purpose string Purpose
data_categories array[string] Granted categories

AccountList

Property Type Description
accounts array Account records

Account

Property Type Description
account_id string Account identifier
name string Account name
type string Account type
mask string Account mask
institution_name string Institution name

BalanceList

Property Type Description
balances array Balance records

Balance

Property Type Description
account_id string Account identifier
available number Available balance
current number Current balance
currency string Currency code

TransactionList

Property Type Description
transactions array Transaction records

Transaction

Property Type Description
transaction_id string Transaction identifier
account_id string Account identifier
posted_at string Posting timestamp
amount number Transaction amount
currency string Currency code
description string Transaction description
category string Transaction category

TransactionSync

Property Type Description
cursor string Sync cursor
added array Added transactions
modified array Modified transactions
removed array Removed transaction identifiers

IncomeSummary

Property Type Description
method string PROVIDER_REPORTED or INFERRED
gross_monthly number Gross monthly income
net_monthly number Net monthly income
currency string Currency code

FeatureComputeRequest

Property Type Description
feature_set string Requested feature set
as_of string As-of date

FeatureComputeResponse

Property Type Description
feature_set string Computed feature set
computed_at string Computation timestamp
evidence_ref string Evidence reference
features object Numeric feature map

DecisionReplayRequest

Property Type Description
evidence_ref string Evidence reference

DecisionReplayResponse

Property Type Description
evidence_ref string Evidence reference
decision string Decision output
reason_codes array[string] Decision reason codes

ErrorResponse

Property Type Description
error object Error envelope
error.code string Machine-readable error code
error.message string Human-readable error message
request_id string Trace identifier

Endpoint Reference

The consent lifecycle is the shared entry point for the contract. docs/docs-api.md defines the canonical consent flow, while the regional prose specs and OpenAPI artifacts expose region-specific examples and machine-readable shapes.

{
    "title": "Create Consent",
    "description": "Creates a new consent record for an applicant and returns a hosted redirect URL",
    "method": "POST",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/consents",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"applicant_id\": \"app_clean\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"data_categories\": [\n        \"transactions\",\n        \"income\",\n        \"payment_behavior\"\n    ],\n    \"expires_in_days\": 30\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "201": {
            "description": "Consent created",
            "body": "{\n    \"consent_id\": \"con_8kXpL9mR2nQv\",\n    \"status\": \"PENDING\",\n    \"applicant_id\": \"app_clean\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"redirect_url\": \"https://connect.joinlita.com/flow/con_8kXpL9mR2nQv\",\n    \"created_at\": \"2026-03-31T09:00:00Z\",\n    \"expires_at\": \"2026-04-30T09:00:00Z\"\n}"
        }
    }
}
{
    "title": "Get Consent",
    "description": "Retrieves the current state of a consent record, including linked connections",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/consents/{id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        },
        {
            "name": "id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent state",
            "body": "{\n    \"consent_id\": \"con_8kXpL9mR2nQv\",\n    \"status\": \"ACTIVE\",\n    \"applicant_id\": \"app_clean\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"activated_at\": \"2026-03-31T09:01:40Z\",\n    \"expires_at\": \"2026-04-30T09:01:40Z\",\n    \"connections\": [\n        {\n            \"connection_id\": \"cnx_4rTvW5xY6zAb\",\n            \"provider\": \"Mizuho Bank\",\n            \"status\": \"ACTIVE\"\n        }\n    ]\n}"
        }
    }
}
{
    "title": "Revoke Consent",
    "description": "Revokes an active consent and immediately terminates future data access",
    "method": "DELETE",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/consents/{id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        },
        {
            "name": "id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent revoked",
            "body": "{\n    \"consent_id\": \"con_8kXpL9mR2nQv\",\n    \"status\": \"REVOKED\",\n    \"revoked_at\": \"2026-03-31T10:22:00Z\"\n}"
        }
    }
}
{
    "title": "Get Consent Receipt",
    "description": "Returns a consent receipt for the region-specific consent authorization flow",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/consents/{consent_id}/receipt",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        },
        {
            "name": "consent_id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent receipt",
            "body": "{\n    \"consent_id\": \"con_8kXpL9mR2nQv\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"data_categories\": [\n        \"transactions\",\n        \"income\",\n        \"payment_behavior\"\n    ],\n    \"disclosure_version\": \"1.2.0\",\n    \"status\": \"ACTIVE\",\n    \"created_at\": \"2026-03-31T09:00:00Z\",\n    \"revoked_at\": null\n}"
        }
    }
}
{
    "title": "Revoke Consent via Receipt Surface",
    "description": "Revokes a consent using the regional OpenAPI route",
    "method": "POST",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/consents/{consent_id}/revoke",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        },
        {
            "name": "consent_id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "[]",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent revoked",
            "body": "{\n    \"consent_id\": \"con_8kXpL9mR2nQv\",\n    \"status\": \"REVOKED\"\n}"
        }
    }
}
{
    "title": "Exchange Consent for Tokens",
    "description": "Exchanges a consent authorization code for access and refresh tokens",
    "method": "POST",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/consents/{consent_id}/token",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        },
        {
            "name": "consent_id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"authorization_code\": \"auth_code_9f1e2d3c\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Tokens issued",
            "body": "{\n    \"access_token\": \"acc_tok_7MZrN8pQ\",\n    \"refresh_token\": \"ref_tok_6KJdL5mN\",\n    \"expires_in\": 3600,\n    \"token_type\": \"Bearer\",\n    \"scope\": \"read:consents read:data write:features\"\n}"
        }
    }
}

Refresh Access Token

{
    "title": "Refresh Access Token",
    "description": "Refreshes an access token using a refresh token",
    "method": "POST",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/tokens/refresh",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"refresh_token\": \"ref_tok_6KJdL5mN\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Tokens refreshed",
            "body": "{\n    \"access_token\": \"acc_tok_7MZrN8pQ\",\n    \"refresh_token\": \"ref_tok_6KJdL5mN\",\n    \"expires_in\": 3600,\n    \"token_type\": \"Bearer\",\n    \"scope\": \"read:consents read:data write:features\"\n}"
        }
    }
}

Introspect Token

{
    "title": "Introspect Token",
    "description": "Returns token activity and associated consent metadata",
    "method": "POST",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/tokens/introspect",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"token\": \"acc_tok_7MZrN8pQ\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Token status",
            "body": "{\n    \"active\": true,\n    \"expires_at\": \"2026-03-31T10:00:00Z\",\n    \"consent_id\": \"con_8kXpL9mR2nQv\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"data_categories\": [\n        \"transactions\",\n        \"income\",\n        \"payment_behavior\"\n    ]\n}"
        }
    }
}

Data Surfaces

The regional OpenAPI artifacts expose the data plane as direct resource endpoints. documents/us-api.md and documents/jp-api.md describe the same data families with localized examples.

List Accounts

{
    "title": "List Accounts",
    "description": "Returns normalized financial accounts for the active access token",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/data/accounts",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Account list",
            "body": "{\n    \"accounts\": [\n        {\n            \"account_id\": \"acc_88221\",\n            \"name\": \"Checking Account\",\n            \"type\": \"checking\",\n            \"mask\": \"1234\",\n            \"institution_name\": \"Chase\"\n        }\n    ]\n}"
        }
    }
}

List Balances

{
    "title": "List Balances",
    "description": "Returns balances for the active access token",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/data/balances",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Balances list",
            "body": "{\n    \"balances\": [\n        {\n            \"account_id\": \"acc_88221\",\n            \"available\": 3200.75,\n            \"current\": 3400.75,\n            \"currency\": \"USD\"\n        }\n    ]\n}"
        }
    }
}

List Transactions

{
    "title": "List Transactions",
    "description": "Returns transactions for a date range",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/data/transactions",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "name": "start_date",
            "type": "string",
            "required": false
        },
        {
            "name": "end_date",
            "type": "string",
            "required": false
        }
    ],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Transaction list",
            "body": "{\n    \"transactions\": [\n        {\n            \"transaction_id\": \"txn_aB3cD4eF5g\",\n            \"account_id\": \"acc_88221\",\n            \"posted_at\": \"2026-03-01T09:00:00Z\",\n            \"amount\": -1200,\n            \"currency\": \"USD\",\n            \"description\": \"RENT PAYMENT\",\n            \"category\": \"HOUSING\"\n        }\n    ]\n}"
        }
    }
}

Sync Transactions

{
    "title": "Sync Transactions",
    "description": "Returns transaction delta sets for incremental sync",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/data/transactions/sync",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "name": "cursor",
            "type": "string",
            "required": false
        },
        {
            "name": "limit",
            "type": "integer",
            "required": false
        }
    ],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Transaction sync",
            "body": "{\n    \"cursor\": \"cur_2kLm3nOp\",\n    \"added\": [\n        {\n            \"transaction_id\": \"txn_aB3cD4eF5g\",\n            \"account_id\": \"acc_88221\",\n            \"posted_at\": \"2026-03-01T09:00:00Z\",\n            \"amount\": -1200,\n            \"currency\": \"USD\",\n            \"description\": \"RENT PAYMENT\",\n            \"category\": \"HOUSING\"\n        }\n    ],\n    \"modified\": [],\n    \"removed\": [\n        {\n            \"transaction_id\": \"txn_xY1z2aB3c\"\n        }\n    ]\n}"
        }
    }
}

Get Income Summary

{
    "title": "Get Income Summary",
    "description": "Returns provider-reported or inferred income values",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/data/income",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Income summary",
            "body": "{\n    \"method\": \"PROVIDER_REPORTED\",\n    \"gross_monthly\": 6200,\n    \"net_monthly\": 5200,\n    \"currency\": \"USD\"\n}"
        }
    }
}

Features, Scores, and Async Jobs

These endpoints represent the feature computation and score retrieval side of the canonical pipeline. The global reference uses consent-scoped paths, while the region OpenAPI files add a direct feature-compute surface and a job-status poller.

Compute Features

{
    "title": "Compute Features",
    "description": "Triggers the asynchronous feature computation pipeline for an active consent",
    "method": "POST",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/features/compute",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"consent_id\": \"con_8kXpL9mR2nQv\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "202": {
            "description": "Feature job accepted",
            "body": "{\n    \"job_id\": \"job_7tYuI8oP3qRs\",\n    \"status\": \"PROCESSING\",\n    \"consent_id\": \"con_8kXpL9mR2nQv\",\n    \"estimated_completion_ms\": 4500\n}"
        }
    }
}

Get Async Job Status

{
    "title": "Get Async Job Status",
    "description": "Polls an asynchronous processing job",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/status/{job_id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        },
        {
            "name": "job_id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Job status",
            "body": "{\n    \"job_id\": \"job_7tYuI8oP3qRs\",\n    \"status\": \"COMPLETE\",\n    \"consent_id\": \"con_8kXpL9mR2nQv\",\n    \"completed_at\": \"2026-03-31T09:05:12Z\"\n}"
        }
    }
}

Get Score

{
    "title": "Get Score",
    "description": "Returns the computed score, risk band, score factors, and evidence reference",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/consents/{id}/score",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        },
        {
            "name": "id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Score response",
            "body": "{\n    \"consent_id\": \"con_8kXpL9mR2nQv\",\n    \"applicant_id\": \"app_clean\",\n    \"score\": 820,\n    \"score_range\": {\n        \"min\": 300,\n        \"max\": 850\n    },\n    \"risk_band\": \"VERY_LOW_RISK\",\n    \"score_factors\": [\n        \"NO_DELINQUENCIES\",\n        \"HIGH_INCOME_STABILITY\",\n        \"LOW_OBLIGATION_RATIO\"\n    ],\n    \"evidence_ref\": \"ev_5sKjL2mN8pQr\",\n    \"scored_at\": \"2026-03-31T09:05:12Z\",\n    \"model_version\": \"1.2.0\"\n}"
        }
    }
}

Get Features

{
    "title": "Get Features",
    "description": "Returns the computed financial behavior feature vector for an assessed consent",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/consents/{id}/features",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        },
        {
            "name": "id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Feature response",
            "body": "{\n    \"consent_id\": \"con_8kXpL9mR2nQv\",\n    \"applicant_id\": \"app_clean\",\n    \"features\": {\n        \"monthly_net_income\": 5200,\n        \"total_monthly_obligations\": 1150,\n        \"obligation_to_income_ratio\": 0.22,\n        \"net_cashflow\": 3250,\n        \"income_stability_score\": 0.96,\n        \"cashflow_volatility\": 0.12,\n        \"late_payment_count_30d_plus\": 0,\n        \"late_payment_count_60d_plus\": 0,\n        \"late_payment_count_90d_plus\": 0,\n        \"delinquency_bucket\": \"CURRENT\"\n    },\n    \"computed_at\": \"2026-03-31T09:04:53Z\",\n    \"feature_version\": \"1.2.0\"\n}"
        }
    }
}

Get Risk Profile

{
    "title": "Get Risk Profile",
    "description": "Returns a structured human-readable financial behavior summary",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/consents/{id}/risk-profile",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        },
        {
            "name": "id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Risk profile",
            "body": "{\n    \"consent_id\": \"con_8kXpL9mR2nQv\",\n    \"applicant_id\": \"app_clean\",\n    \"risk_profile\": {\n        \"payment_behavior\": {\n            \"status\": \"CURRENT\",\n            \"late_payments_30d\": 0,\n            \"late_payments_60d\": 0,\n            \"late_payments_90d\": 0\n        },\n        \"income\": {\n            \"monthly_income\": 5200,\n            \"stability\": \"HIGH\"\n        },\n        \"obligations\": {\n            \"total_monthly_obligations\": 1150,\n            \"obligation_to_income_ratio\": 0.22\n        },\n        \"cashflow\": {\n            \"net_cashflow\": 3250,\n            \"volatility\": \"LOW\"\n        }\n    },\n    \"generated_at\": \"2026-03-31T09:05:00Z\"\n}"
        }
    }
}

Retrieve Evidence Snapshot

{
    "title": "Retrieve Evidence Snapshot",
    "description": "Retrieves the immutable evidence snapshot by reference",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/evidence/{evidence_ref}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        },
        {
            "name": "evidence_ref",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "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}"
        }
    }
}

Compliance and Audit Surfaces

The contract treats compliance as part of the assessment pipeline rather than a separate afterthought. KYC and AML results are exposed independently of the score.

Get KYC AML Status

{
    "title": "Get KYC AML Status",
    "description": "Returns the full compliance screening results including identity verification, sanctions, PEP, and AML checks",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/consents/{id}/kyc",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        },
        {
            "name": "id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "KYC response",
            "body": "{\n    \"consent_id\": \"con_8kXpL9mR2nQv\",\n    \"status\": \"VERIFIED\",\n    \"checks\": {\n        \"identity\": {\n            \"status\": \"VERIFIED\",\n            \"method\": \"document_biometric\"\n        },\n        \"sanctions\": {\n            \"status\": \"CLEAR\",\n            \"lists_screened\": [\n                \"OFAC\",\n                \"UN\",\n                \"EU\"\n            ]\n        },\n        \"pep\": {\n            \"status\": \"CLEAR\"\n        },\n        \"aml\": {\n            \"status\": \"CLEAR\",\n            \"risk_level\": \"LOW\"\n        }\n    },\n    \"completed_at\": \"2026-03-31T09:04:20Z\"\n}"
        }
    }
}

Regional OpenAPI-Only Surfaces

These routes appear in the region-specific OpenAPI files and are part of the machine-readable contract layer.

{
    "title": "Revoke Consent through Regional OpenAPI",
    "description": "Revokes consent using the OpenAPI route exposed by the regional spec",
    "method": "POST",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/consents/{consent_id}/revoke",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        },
        {
            "name": "consent_id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "[]",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent revoked",
            "body": "{\n    \"consent_id\": \"con_8kXpL9mR2nQv\",\n    \"status\": \"REVOKED\"\n}"
        }
    }
}

Submit Partner Score Callback

{
    "title": "Submit Partner Score Callback",
    "description": "Lita sends the evidence payload to the partner-hosted scoring endpoint",
    "method": "POST",
    "baseUrl": "<PartnerSystemBaseUrl>",
    "endpoint": "/api/lita/v1/score",
    "headers": [],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"request_id\": \"req_23981\",\n    \"applicant_id\": \"app_8823\",\n    \"consent_id\": \"cons_2312\",\n    \"evidence_ref\": \"ev_33821\",\n    \"purpose\": \"RENTAL_SCREENING\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Partner decision",
            "body": "{\n    \"score\": 712,\n    \"decision\": \"APPROVE\",\n    \"approved_limit\": 400000,\n    \"reasons\": [\n        \"LOW_BALANCE_VOLATILITY\"\n    ]\n}"
        }
    }
}

Sync Transactions via OpenAPI

{
    "title": "Sync Transactions via OpenAPI",
    "description": "Returns incremental transaction changes for the active token",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/{region}/data/transactions/sync",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<uuid>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "name": "cursor",
            "type": "string",
            "required": false
        },
        {
            "name": "limit",
            "type": "integer",
            "required": false
        }
    ],
    "pathParams": [
        {
            "name": "region",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Transaction sync response",
            "body": "{\n    \"cursor\": \"cur_2kLm3nOp\",\n    \"added\": [\n        {\n            \"transaction_id\": \"txn_aB3cD4eF5g\",\n            \"account_id\": \"acc_88221\",\n            \"posted_at\": \"2026-03-01T09:00:00Z\",\n            \"amount\": -1200,\n            \"currency\": \"USD\",\n            \"description\": \"RENT PAYMENT\",\n            \"category\": \"HOUSING\"\n        }\n    ],\n    \"modified\": [],\n    \"removed\": [\n        {\n            \"transaction_id\": \"txn_xY1z2aB3c\"\n        }\n    ]\n}"
        }
    }
}

Feature Flows

sequenceDiagram
    participant Partner as Partner System
    participant Docs as Contract Docs
    participant Lita as Lita API
    participant Applicant as Applicant
    participant Webhook as Partner Webhook

    Partner->>Docs: Read docs docs-api md and regional spec
    Partner->>Lita: POST /api/v1/region/consents
    Lita-->>Partner: consent_id and redirect_url
    Partner->>Applicant: Redirect to hosted consent flow
    Applicant->>Lita: Complete authorization
    Lita-->>Webhook: consent activated event
    Partner->>Lita: POST /api/v1/region/features/compute
    Lita-->>Partner: job_id and processing status
    Lita-->>Webhook: features computed event
    Lita-->>Webhook: score completed event
    Partner->>Lita: GET /api/v1/region/consents/id/score
    Lita-->>Partner: score and evidence_ref
    Partner->>Lita: GET /api/v1/region/evidence/evidence_ref
    Lita-->>Partner: immutable evidence snapshot

Regional Data Retrieval Flow

sequenceDiagram
    participant Partner as Partner System
    participant Lita as Lita API
    participant Provider as Financial Provider

    Partner->>Lita: POST /api/v1/region/consents/id/token
    Lita-->>Partner: access_token and refresh_token
    Partner->>Lita: GET /api/v1/region/data/accounts
    Lita-->>Provider: fetch accounts
    Provider-->>Lita: normalized accounts
    Lita-->>Partner: accounts
    Partner->>Lita: GET /api/v1/region/data/transactions
    Lita-->>Provider: fetch transactions
    Provider-->>Lita: normalized transactions
    Lita-->>Partner: transactions

Webhooks and Delivery Contract

The webhook contract is part of the external runtime foundation even though its destination is partner-owned. The documented event types are consent.activated, consent.expired, consent.revoked, data.updated, features.computed, score.completed, and kyc.updated.

The webhook payload includes event_id, event_type, created_at, region, and a data object containing at least consent_id, applicant_id, and evidence_ref for score-related events. Each request carries X-Lita-Signature, an HMAC-SHA256 signature over the raw request body.

Webhook Field Type Description
event_id string Unique webhook event identifier
event_type string Event name
created_at string Event timestamp
region string Region identifier
data object Event payload
data.consent_id string Consent identifier
data.applicant_id string Applicant identifier
data.evidence_ref string Evidence reference when applicable
Delivery Rule Value
Signature header X-Lita-Signature
Signature format sha256=<hex_digest>
Retry window 5 attempts
Retry delays Immediate, +30 seconds, +5 minutes, +30 minutes, +2 hours
Failure result Event marked undeliverable

Regional Specification Split

The three prose documents divide the same domain into one global reference and two regional examples:

  • docs/docs-api.md defines the canonical lifecycle and the shared external contract language.
  • documents/us-api.md anchors the United States surface with US-specific examples and partner-hosted scoring.
  • documents/jp-api.md anchors the Japan surface with JP-specific examples and partner-hosted scoring.
  • documents/us-api-openapi.yaml and documents/jp-api-openapi.yaml make the US and JP contracts machine-readable for tooling, SDK generation, and schema validation.

The contract shape is intentionally region-aware at the path level and region-neutral at the lifecycle level. The same consent-to-evidence pipeline appears everywhere, but the artifact set does not describe one single identical path map.

Error Handling

The prose reference defines a stable error envelope:

{
  "error": {
    "code": "consent_not_active",
    "message": "The consent is in PENDING status. Wait for activation before requesting a score.",
    "request_id": "req-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "retryable": false
  }
}
Field Type Description
code string Machine-readable error identifier
message string Human-readable explanation
request_id string Trace identifier
retryable boolean Retry suitability
Error Code HTTP Retryable Meaning
invalid_request 400 No Request body is malformed or missing required data
unauthorized 401 No API key is missing or invalid
forbidden 403 No Key lacks permission
not_found 404 No Resource is absent in the region
consent_not_active 422 No Consent is PENDING or EXPIRED
consent_revoked 422 No Consent has been revoked
consent_expired 422 No Consent window elapsed
score_not_ready 422 No Computation still in progress
insufficient_data 422 No Fewer than 90 days of transaction history
kyc_failed 422 No Compliance block
rate_limited 429 Yes Too many requests
provider_unavailable 503 Yes Upstream provider failure
processing_error 500 Yes Internal pipeline failure

Authentication and Idempotency

The documented runtime contract requires bearer authentication and tracing for every request.

Header Required Purpose
Authorization Yes Bearer token authentication
X-Request-Id Yes Trace ID and idempotency key for mutating requests
Content-Type POST and PUT only JSON payload marker

Mutating requests that are retried with the same X-Request-Id return the original result rather than executing twice. The documented idempotent operations are POST /{region}/consents, POST /{region}/features/compute, and DELETE /{region}/consents/{id}.

Key Classes Reference

Class Responsibility
docs/docs-api.md Canonical global API reference for the consent-to-evidence pipeline
documents/us-api.md US regional prose contract and examples
documents/jp-api.md Japan regional prose contract and examples
documents/us-api-openapi.yaml US machine-readable contract and schemas
documents/jp-api-openapi.yaml Japan machine-readable contract and schemas