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:
- Applicant — partner-assigned
applicant_id.
- Consent — purpose-scoped authorization that gates access.
- Data — normalized account, transaction, income, and behavioral inputs.
- Features — derived financial behavior vectors and risk dimensions.
- Score — normalized 300–850 score with risk band and score factors.
- 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
Consent Creation Response
| 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 |
Consent Retrieval Response
| 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 |
Revoke Consent Response
| 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
Consent and Authorization
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.
Create Consent
{
"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}"
}
}
}
Get Consent
{
"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}"
}
}
}
Revoke Consent
{
"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}"
}
}
}
Get Consent Receipt
{
"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}"
}
}
}
Revoke Consent via Receipt Surface
{
"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}"
}
}
}
Exchange Consent for Tokens
{
"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.
Revoke Consent through Regional OpenAPI
{
"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
Consent to Score Pipeline
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 |