Consent and Evidence Management Domain
Overview
This domain defines how a partner creates a consent, lets the applicant authorize it, retrieves the consent state and receipt, and then uses that consent to access financial data and evidence-backed outputs. The common thread across the US and JP surfaces is that every downstream access path is anchored to a consent_id, and the SDKs model that consent as the primary object returned from the lifecycle calls.
Evidence enters the flow when feature computation produces an evidence_ref, which can then be dereferenced for audit and review. The Java, Node, and Python SDKs all expose consent-centric resources, while the separate consent-service container packages the runtime for consent-specific server logic as its own deployable component.
Architecture Overview
flowchart TB
subgraph SDKs [SDK Clients]
NodeSdk[Node ConsentsResource]
PythonSdk[Python ConsentsResource]
JavaSdk[Java ConsentsResource]
end
subgraph RegionalContracts [Regional API Contracts]
USDocs[US API docs and OpenAPI]
JPDocs[JP API docs and OpenAPI]
end
subgraph Runtime [Consent Service Runtime]
ConsentService[consent-service container]
end
subgraph DataSurface [Consent Scoped Data and Evidence]
ConsentData[Consent data endpoints]
FeatureCompute[Feature compute endpoint]
EvidenceLookup[Evidence lookup endpoint]
end
PartnerApp[Partner application] --> NodeSdk
PartnerApp --> PythonSdk
PartnerApp --> JavaSdk
NodeSdk --> USDocs
NodeSdk --> JPDocs
PythonSdk --> USDocs
PythonSdk --> JPDocs
JavaSdk --> USDocs
JavaSdk --> JPDocs
USDocs --> ConsentService
JPDocs --> ConsentService
USDocs --> ConsentData
JPDocs --> ConsentData
USDocs --> FeatureCompute
JPDocs --> FeatureCompute
FeatureCompute --> EvidenceLookup
ConsentService --> ConsentData
ConsentService --> FeatureCompute
Contract Differences Between Published Docs and SDKs
HTTP API Contracts
Create Consent
[!IMPORTANT] The consent lifecycle is not published as one identical wire contract everywhere. The markdown docs, OpenAPI excerpts, and SDK resources diverge in several visible places, and the SDKs follow their own serialized shapes. [!NOTE] Proven mismatches in the provided files: -
documents/us-api.mdanddocuments/jp-api.mdshow consent creation withapplicant_id,purpose,data_categories, andexpires_in_days. -documents/us-api-openapi.yamlanddocuments/jp-api-openapi.yamlrequireuserandrefresh_permissionsinCreateConsentRequest. - The OpenAPI create response isConsentResponsewithauth.link_urlandauth.link_token. - The SDKs deserialize aConsentobject withredirect_url,created_at,activated_at,expires_at,revoked_at, andconnections. - The OpenAPI revoke route isPOST /api/v1/{region}/consents/{consent_id}/revoke. - The SDKs revoke withDELETE /{region}/consents/{consent_id}. - The OpenAPI data and feature routes under/api/v1/{region}/data/...and/api/v1/{region}/features/computeuse access-token security and different response envelopes from the consent-scoped SDK methods. - The Java HTTP client parses nested error fields andretryable, while the OpenAPI error schema publishes a simplerErrorResponse.
The consent creation call starts the lifecycle. The published docs show a short consent request, while the OpenAPI schema requires a richer body; the SDK resources serialize the shorter shape.
Create Consent
{
"title": "Create Consent",
"description": "Creates a consent authorization and returns the consent object used by the SDKs",
"method": "POST",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/consents",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_API_KEY>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"applicant_id\": \"app_12821\",\n \"purpose\": \"RENTAL_SCREENING\",\n \"data_categories\": [\n \"accounts\",\n \"transactions\",\n \"income\"\n ],\n \"expires_in_days\": 30\n}",
"formData": [],
"rawBody": "",
"responses": {
"201": {
"description": "Consent created",
"body": "{\n \"consent_id\": \"cons_34921\",\n \"status\": \"PENDING\",\n \"applicant_id\": \"app_12821\",\n \"purpose\": \"RENTAL_SCREENING\",\n \"redirect_url\": \"https://api.joinlita.com/api/v1/us/consents/cons_34921/authorize\",\n \"created_at\": \"2026-03-31T12:00:00Z\",\n \"activated_at\": null,\n \"expires_at\": \"2026-04-30T12:00:00Z\",\n \"revoked_at\": null,\n \"connections\": []\n}"
},
"400": {
"description": "Bad request",
"body": "{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"The request body is invalid\"\n },\n \"request_id\": \"req_23981\"\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid partner API key\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
Get Consent
Get Consent
{
"title": "Get Consent",
"description": "Returns the current consent state and linked connections",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/consents/{consent_id}",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_API_KEY>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"value": "cons_34921",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Consent state",
"body": "{\n \"consent_id\": \"cons_34921\",\n \"status\": \"ACTIVE\",\n \"applicant_id\": \"app_12821\",\n \"purpose\": \"RENTAL_SCREENING\",\n \"redirect_url\": \"https://api.joinlita.com/api/v1/us/consents/cons_34921/authorize\",\n \"created_at\": \"2026-03-31T12:00:00Z\",\n \"activated_at\": \"2026-03-31T12:05:00Z\",\n \"expires_at\": \"2026-04-30T12:00:00Z\",\n \"revoked_at\": null,\n \"connections\": []\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid partner API key\"\n },\n \"request_id\": \"req_23981\"\n}"
},
"404": {
"description": "Not found",
"body": "{\n \"error\": {\n \"code\": \"consent_not_found\",\n \"message\": \"Consent was not found\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
Get Consent Receipt
The receipt endpoint is documented in the API specs and returns the legal disclosure record for a consent.
Get Consent Receipt
{
"title": "Get Consent Receipt",
"description": "Returns the consent receipt for audit and disclosure review",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/consents/{consent_id}/receipt",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_API_KEY>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"value": "cons_34921",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Consent receipt",
"body": "{\n \"consent_id\": \"cons_34921\",\n \"purpose\": \"RENTAL_SCREENING\",\n \"data_categories\": [\n \"accounts\",\n \"balances\",\n \"transactions\"\n ],\n \"disclosure_version\": \"2026-03\",\n \"status\": \"ACTIVE\",\n \"created_at\": \"2026-03-31T12:00:00Z\",\n \"revoked_at\": null\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid partner API key\"\n },\n \"request_id\": \"req_23981\"\n}"
},
"404": {
"description": "Not found",
"body": "{\n \"error\": {\n \"code\": \"consent_not_found\",\n \"message\": \"Consent was not found\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
Revoke Consent
Revoke Consent
{
"title": "Revoke Consent",
"description": "Revokes an active consent and returns the updated consent object",
"method": "DELETE",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/consents/{consent_id}",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_API_KEY>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"value": "cons_34921",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Consent revoked",
"body": "{\n \"consent_id\": \"cons_34921\",\n \"status\": \"REVOKED\",\n \"applicant_id\": \"app_12821\",\n \"purpose\": \"RENTAL_SCREENING\",\n \"redirect_url\": \"https://api.joinlita.com/api/v1/us/consents/cons_34921/authorize\",\n \"created_at\": \"2026-03-31T12:00:00Z\",\n \"activated_at\": \"2026-03-31T12:05:00Z\",\n \"expires_at\": \"2026-04-30T12:00:00Z\",\n \"revoked_at\": \"2026-03-31T12:10:00Z\",\n \"connections\": []\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid partner API key\"\n },\n \"request_id\": \"req_23981\"\n}"
},
"404": {
"description": "Not found",
"body": "{\n \"error\": {\n \"code\": \"consent_not_found\",\n \"message\": \"Consent was not found\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
Revoke Consent via Published API Contract
The published OpenAPI excerpt also exposes a subresource revoke route.
{
"title": "Revoke Consent via Subresource",
"description": "Revokes a consent using the published revoke subresource",
"method": "POST",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/consents/{consent_id}/revoke",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_API_KEY>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"value": "cons_34921",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Consent revoked",
"body": "{\n \"consent_id\": \"cons_34921\",\n \"status\": \"REVOKED\"\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid partner API key\"\n },\n \"request_id\": \"req_23981\"\n}"
},
"404": {
"description": "Not found",
"body": "{\n \"error\": {\n \"code\": \"consent_not_found\",\n \"message\": \"Consent was not found\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
Exchange Consent for Tokens
This step sits between authorization and consent-scoped data access.
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 <PARTNER_API_KEY>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"value": "cons_34921",
"required": true
}
],
"bodyType": "json",
"requestBody": "{\n \"authorization_code\": \"authcode_abc123\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Tokens issued",
"body": "{\n \"access_token\": \"acc_tok_9f7d0a2c\",\n \"refresh_token\": \"ref_tok_2bd1a8f4\",\n \"expires_in\": 3600,\n \"token_type\": \"Bearer\",\n \"scope\": \"accounts balances transactions income\"\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid partner API key\"\n },\n \"request_id\": \"req_23981\"\n}"
},
"404": {
"description": "Not found",
"body": "{\n \"error\": {\n \"code\": \"consent_not_found\",\n \"message\": \"Consent was not found\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
Refresh Access Token
{
"title": "Refresh Access Token",
"description": "Refreshes an access token using the stored refresh token",
"method": "POST",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/tokens/refresh",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_API_KEY>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"refresh_token\": \"ref_tok_2bd1a8f4\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Tokens refreshed",
"body": "{\n \"access_token\": \"acc_tok_9f7d0a2c\",\n \"refresh_token\": \"ref_tok_91a6b20d\",\n \"expires_in\": 3600,\n \"token_type\": \"Bearer\",\n \"scope\": \"accounts balances transactions income\"\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid partner API key\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
Introspect Token
{
"title": "Introspect Token",
"description": "Returns the active status and consent binding for a token",
"method": "POST",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/tokens/introspect",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_API_KEY>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"token\": \"acc_tok_9f7d0a2c\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Token status",
"body": "{\n \"active\": true,\n \"expires_at\": \"2026-03-31T13:00:00Z\",\n \"consent_id\": \"cons_34921\",\n \"purpose\": \"RENTAL_SCREENING\",\n \"data_categories\": [\n \"accounts\",\n \"balances\",\n \"transactions\"\n ]\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid partner API key\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
Consent Scoped Data Access
The SDKs expose consent-scoped access through the consents resource. The markdown docs also publish data access under consent-specific paths, while the OpenAPI excerpts publish regional /data/* routes under access-token security.
List Accounts
{
"title": "List Accounts",
"description": "Returns the accounts tied to the active consent",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/consents/{consent_id}/data/accounts",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"value": "cons_34921",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Account list",
"body": "{\n \"accounts\": [\n {\n \"account_id\": \"acc_88221\",\n \"name\": \"Operating Checking\",\n \"type\": \"checking\",\n \"mask\": \"1234\",\n \"institution_name\": \"Chase\"\n }\n ]\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid access token\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
List Balances
{
"title": "List Balances",
"description": "Returns balances tied to the active consent",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/consents/{consent_id}/data/balances",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"value": "cons_34921",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Balances list",
"body": "{\n \"balances\": [\n {\n \"account_id\": \"acc_88221\",\n \"available\": 2500.75,\n \"current\": 2600,\n \"currency\": \"USD\"\n }\n ]\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid access token\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
List Transactions
{
"title": "List Transactions",
"description": "Returns the consent scoped transaction feed with cursor and date filters",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/consents/{consent_id}/data/transactions",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
}
],
"queryParams": [
{
"key": "limit",
"value": "100",
"required": false
},
{
"key": "cursor",
"value": "cursor_1002",
"required": false
},
{
"key": "from_date",
"value": "2026-03-01",
"required": false
},
{
"key": "to_date",
"value": "2026-03-31",
"required": false
}
],
"pathParams": [
{
"key": "consent_id",
"value": "cons_34921",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Transaction list",
"body": "{\n \"data\": [\n {\n \"transaction_id\": \"txn_1001\",\n \"date\": \"2026-03-30\",\n \"amount\": -1200,\n \"currency\": \"USD\",\n \"description\": \"Rent payment\",\n \"category\": \"housing\",\n \"type\": \"DEBIT\"\n }\n ],\n \"next_cursor\": \"cursor_1002\",\n \"total_count\": 1\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid access token\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
Sync Transactions
{
"title": "Sync Transactions",
"description": "Returns a transaction delta payload for incremental sync",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/data/transactions/sync",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
}
],
"queryParams": [
{
"key": "cursor",
"value": "cursor_1002",
"required": false
},
{
"key": "limit",
"value": "100",
"required": false
}
],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Transaction sync",
"body": "{\n \"cursor\": \"cursor_1002\",\n \"added\": [\n {\n \"transaction_id\": \"txn_1003\",\n \"account_id\": \"acc_88221\",\n \"posted_at\": \"2026-03-31T08:00:00Z\",\n \"amount\": 85.14,\n \"currency\": \"USD\",\n \"description\": \"Payroll deposit\",\n \"category\": \"income\"\n }\n ],\n \"modified\": [],\n \"removed\": [\n {\n \"transaction_id\": \"txn_0999\"\n }\n ]\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid access token\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
Get Income Summary
{
"title": "Get Income Summary",
"description": "Returns income summary data for the active consent",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/data/income",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Income summary",
"body": "{\n \"method\": \"PROVIDER_REPORTED\",\n \"gross_monthly\": 5200,\n \"net_monthly\": 4300,\n \"currency\": \"USD\"\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid access token\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
Feature and Evidence Bridge
The feature-computation surface is the point where consent-scoped transaction data is turned into evidence-backed outputs.
Compute Features
{
"title": "Compute Features",
"description": "Triggers feature computation for the consent and returns an evidence reference",
"method": "POST",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/features/compute",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_API_KEY>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"consent_id\": \"cons_34921\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Feature compute response",
"body": "{\n \"job_id\": \"job_7788\",\n \"status\": \"PROCESSING\",\n \"consent_id\": \"cons_34921\",\n \"estimated_completion_ms\": 1500\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid partner API key\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
Get Consent Score
{
"title": "Get Consent Score",
"description": "Returns the computed score for a consent",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/consents/{consent_id}/score",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"value": "cons_34921",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Computed score",
"body": "{\n \"consent_id\": \"cons_34921\",\n \"applicant_id\": \"app_12821\",\n \"score\": 712,\n \"score_range\": {\n \"min\": 300,\n \"max\": 850\n },\n \"decision\": \"APPROVE\",\n \"score_factors\": [\n \"LOW_BALANCE_VOLATILITY\",\n \"STABLE_INCOME\"\n ],\n \"evidence_ref\": \"ev_33821\",\n \"scored_at\": \"2026-03-31T12:08:00Z\",\n \"model_version\": \"2026.03.1\"\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid access token\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
Get KYC Results
{
"title": "Get KYC Results",
"description": "Returns KYC and AML checks tied to the consent",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/api/v1/{region}/consents/{consent_id}/kyc",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<UUID>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"value": "cons_34921",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "KYC result",
"body": "{\n \"consent_id\": \"cons_34921\",\n \"status\": \"PASSED\",\n \"checks\": {\n \"identity\": {\n \"status\": \"PASSED\",\n \"method\": \"DOCUMENT_VERIFICATION\",\n \"lists_screened\": [\n \"sanctions\",\n \"pep\"\n ],\n \"risk_level\": \"LOW\"\n },\n \"sanctions\": {\n \"status\": \"PASSED\",\n \"method\": \"LIST_SCREENING\",\n \"lists_screened\": [\n \"OFAC\"\n ],\n \"risk_level\": \"LOW\"\n }\n },\n \"completed_at\": \"2026-03-31T12:06:00Z\"\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid access token\"\n },\n \"request_id\": \"req_23981\"\n}"
}
}
}
SDK Resource Surfaces
Java SDK
sdks/java/src/main/java/com/joinlita/resources/ConsentsResource.java
sdks/java/src/main/java/com/joinlita/params/ConsentCreateParams.java
sdks/java/src/main/java/com/joinlita/model/Consent.java
sdks/java/src/main/java/com/joinlita/model/Score.java
sdks/java/src/main/java/com/joinlita/model/TransactionListResponse.java
sdks/java/src/main/java/com/joinlita/model/KycResult.java
sdks/java/src/main/java/com/joinlita/resources/FeaturesResource.java
sdks/java/src/main/java/com/joinlita/resources/EvidenceResource.java
sdks/java/src/main/java/com/joinlita/Lita.java
Consents Resource
Constructor dependencies
| Type | Description |
|---|---|
HttpClient |
Shared HTTP transport used by all consent calls |
Public methods
| Method | Description |
|---|---|
create |
Sends POST consents with applicant_id, purpose, data_categories, and expires_in_days, then deserializes a Consent |
get |
Sends GET consents/{id} and returns the current Consent state |
revoke |
Sends DELETE consents/{id} and returns the revoked consent payload |
getScore |
Sends GET consents/{id}/score and returns Score |
listTransactions |
Sends GET consents/{id}/data/transactions and returns TransactionListResponse |
getKyc |
Sends GET consents/{id}/kyc and returns KycResult |
Consent Create Params
| Property | Type | Description |
|---|---|---|
applicantId |
String |
Stable partner-managed applicant identifier |
purpose |
String |
Consent purpose string |
dataCategories |
List<String> |
Granted data categories |
expiresInDays |
int |
Consent lifetime in days |
Public methods
| Method | Description |
|---|---|
getApplicantId |
Returns the applicant identifier |
getPurpose |
Returns the consent purpose |
getDataCategories |
Returns the data categories |
getExpiresInDays |
Returns the consent lifetime |
builder |
Creates a builder instance |
Consent
| Property | Type | Description |
|---|---|---|
consentId |
String |
Consent identifier |
status |
String |
Consent status |
applicantId |
String |
Partner-managed applicant identifier |
purpose |
String |
Declared consent purpose |
redirectUrl |
String |
User authorization URL returned by the service |
createdAt |
String |
Consent creation timestamp |
activatedAt |
String |
Timestamp when the consent became active |
expiresAt |
String |
Consent expiration timestamp |
revokedAt |
String |
Revocation timestamp |
connections |
List<Connection> |
Linked financial institution connections |
Score
| Property | Type | Description |
|---|---|---|
consentId |
String |
Consent identifier |
applicantId |
String |
Partner-managed applicant identifier |
score |
int |
Computed score value |
scoreRange |
Map<String, Integer> |
Minimum and maximum score bounds |
decision |
String |
Score decision |
scoreFactors |
List<String> |
Explanation codes |
evidenceRef |
String |
Evidence reference attached to the score |
scoredAt |
String |
Score timestamp |
modelVersion |
String |
Model version used for scoring |
Transaction List Params
| Property | Type | Description |
|---|---|---|
limit |
Integer |
Maximum number of transactions to return |
cursor |
String |
Pagination cursor |
fromDate |
String |
Lower bound date |
toDate |
String |
Upper bound date |
Public methods
| Method | Description |
|---|---|
getLimit |
Returns the limit |
getCursor |
Returns the cursor |
getFromDate |
Returns the lower bound date |
getToDate |
Returns the upper bound date |
builder |
Creates a builder instance |
Transaction List Response
| Property | Type | Description |
|---|---|---|
data |
List<Transaction> |
Returned transaction objects |
nextCursor |
String |
Cursor for the next page |
totalCount |
int |
Total number of transactions |
KYC Result
| Property | Type | Description |
|---|---|---|
consentId |
String |
Consent identifier |
status |
String |
KYC status |
checks |
Map<String, Map<String, Object>> |
Check results keyed by check name |
completedAt |
String |
Completion timestamp |
Evidence Resource
Constructor dependencies
| Type | Description |
|---|---|
HttpClient |
Shared HTTP transport used by the evidence lookup call |
Public methods
| Method | Description |
|---|---|
get |
Sends GET evidence/{evidence_ref} and returns EvidenceSnapshot |
Features Resource
Constructor dependencies
| Type | Description |
|---|---|
HttpClient |
Shared HTTP transport used by the feature-computation call |
Public methods
| Method | Description |
|---|---|
compute |
Sends POST features/compute with consent_id and returns ComputeFeaturesResponse |
Java Lita Entry Point
| Property | Type | Description |
|---|---|---|
consents |
ConsentsResource |
Consent lifecycle resource |
features |
FeaturesResource |
Feature computation resource |
evidence |
EvidenceResource |
Evidence snapshot resource |
status |
StatusResource |
Async job status resource |
Public methods
| Method | Description |
|---|---|
consents |
Returns the consent resource |
features |
Returns the feature resource |
evidence |
Returns the evidence resource |
status |
Returns the status resource |
builder |
Creates the client builder |
Node SDK
sdks/node/src/resources/consents.ts
sdks/node/src/types.ts
sdks/node/src/index.ts
Consents Resource
Constructor dependencies
| Type | Description |
|---|---|
HttpClient |
Shared HTTP transport used by the resource methods |
Public methods
| Method | Description |
|---|---|
create |
Sends POST consents and returns Consent |
get |
Sends GET consents/{id} and returns Consent |
revoke |
Sends DELETE consents/{id} and returns the revoked consent subset |
getScore |
Sends GET consents/{id}/score and returns Score |
listTransactions |
Sends GET consents/{id}/data/transactions and returns TransactionListResponse |
getKyc |
Sends GET consents/{id}/kyc and returns KycResult |
Consent Create Params
| Property | Type | Description |
|---|---|---|
applicant_id |
string |
Partner-managed applicant identifier |
purpose |
ConsentPurpose |
Consent purpose |
data_categories |
DataCategory[] |
Granted data categories |
expires_in_days |
number |
Consent lifetime in days |
Consent
| Property | Type | Description |
|---|---|---|
consent_id |
string |
Consent identifier |
status |
ConsentStatus |
Consent status |
applicant_id |
string |
Partner-managed applicant identifier |
purpose |
ConsentPurpose |
Declared consent purpose |
redirect_url |
string |
Authorization URL |
created_at |
string |
Creation timestamp |
activated_at |
string |
Activation timestamp |
expires_at |
string |
Expiration timestamp |
revoked_at |
string |
Revocation timestamp |
connections |
Connection[] |
Linked connections |
Score
| Property | Type | Description |
|---|---|---|
consent_id |
string |
Consent identifier |
applicant_id |
string |
Applicant identifier |
score |
number |
Computed score |
score_range |
{ min: number; max: number } |
Score bounds |
decision |
ScoreDecision |
Decision outcome |
score_factors |
string[] |
Explanation codes |
evidence_ref |
string |
Evidence reference |
scored_at |
string |
Timestamp |
model_version |
string |
Model version |
Evidence Snapshot
| Property | Type | Description |
|---|---|---|
evidence_ref |
string |
Evidence identifier |
consent_id |
string |
Consent identifier |
applicant_id |
string |
Applicant identifier |
snapshot_version |
string |
Snapshot version |
created_at |
string |
Snapshot timestamp |
score_inputs |
{ ... } |
Score input sections |
kyc_result |
{ ... } |
KYC result payload |
delinquency_bucket |
DelinquencyBucket |
Delinquency bucket |
KYC Result
| Property | Type | Description |
|---|---|---|
consent_id |
string |
Consent identifier |
status |
KycStatus |
KYC status |
checks |
{ ... } |
Check details keyed by check name |
completed_at |
string |
Completion timestamp |
Node Lita Entry Point
| Property | Type | Description |
|---|---|---|
consents |
ConsentsResource |
Consent lifecycle resource |
features |
FeaturesResource |
Feature computation resource |
evidence |
EvidenceResource |
Evidence snapshot resource |
status |
StatusResource |
Async job status resource |
Python SDK
sdks/python/lita/resources/consents.py
sdks/python/lita/types.py
Consents Resource
Constructor dependencies
| Type | Description |
|---|---|
HttpClient |
Shared HTTP transport used by the resource methods |
Public methods
| Method | Description |
|---|---|
create |
Sends POST consents and returns Consent |
get |
Sends GET consents/{id} and returns Consent |
revoke |
Sends DELETE consents/{id} and returns Consent |
get_score |
Sends GET consents/{id}/score and returns Score |
list_transactions |
Sends GET consents/{id}/data/transactions and returns TransactionListResponse |
get_kyc |
Sends GET consents/{id}/kyc and returns KycResult |
Consent
| Property | Type | Description |
|---|---|---|
consent_id |
str |
Consent identifier |
status |
ConsentStatus |
Consent status |
applicant_id |
str |
Partner-managed applicant identifier |
purpose |
ConsentPurpose |
Declared consent purpose |
expires_at |
str |
Expiration timestamp |
redirect_url |
Optional[str] |
Authorization URL |
created_at |
Optional[str] |
Creation timestamp |
activated_at |
Optional[str] |
Activation timestamp |
revoked_at |
Optional[str] |
Revocation timestamp |
connections |
List[Connection] |
Linked connections |
Score
| Property | Type | Description |
|---|---|---|
consent_id |
str |
Consent identifier |
applicant_id |
str |
Applicant identifier |
score |
int |
Computed score |
score_range |
ScoreRange |
Score bounds |
decision |
ScoreDecision |
Decision outcome |
score_factors |
List[str] |
Explanation codes |
evidence_ref |
str |
Evidence reference |
scored_at |
str |
Timestamp |
model_version |
str |
Model version |
KYC Result
| Property | Type | Description |
|---|---|---|
consent_id |
str |
Consent identifier |
status |
KycStatus |
KYC status |
checks |
Dict[str, KycCheckDetail] |
Check details keyed by name |
completed_at |
str |
Completion timestamp |
Evidence Snapshot
| Property | Type | Description |
|---|---|---|
evidence_ref |
str |
Evidence identifier |
consent_id |
str |
Consent identifier |
applicant_id |
str |
Applicant identifier |
snapshot_version |
str |
Snapshot version |
created_at |
str |
Snapshot timestamp |
score_inputs |
Dict[str, Any] |
Input features used for scoring |
kyc_result |
Dict[str, Any] |
KYC result payload |
delinquency_bucket |
DelinquencyBucket |
Delinquency bucket |
Job Status Response
| Property | Type | Description |
|---|---|---|
job_id |
str |
Async job identifier |
status |
JobStatus |
Job state |
consent_id |
str |
Consent identifier |
completed_at |
Optional[str] |
Completion timestamp |
error |
Optional[Dict[str, str]] |
Error payload |
Lifecycle Flows
Consent Creation, Authorization, and Receipt Retrieval
sequenceDiagram
participant App as Partner application
participant SDK as ConsentsResource
participant API as Regional API
participant User as User browser
App->>SDK: create
SDK->>API: POST consents
API-->>SDK: Consent with redirect URL
SDK-->>App: Consent
App-->>User: Redirect to authorization URL
User->>API: Complete authorization
App->>SDK: get or receipt
SDK->>API: GET consent or receipt
API-->>SDK: Consent state or receipt
Consent Scoped Data Access and Evidence Bridge
sequenceDiagram
participant App as Partner application
participant SDK as ConsentsResource
participant API as Regional API
participant Data as Consent scoped data
participant Feature as Feature compute
participant Evidence as Evidence lookup
App->>SDK: get
SDK->>API: GET consent
API-->>SDK: ACTIVE consent
App->>SDK: listTransactions
SDK->>API: GET consent data transactions
API-->>SDK: Transaction list
App->>SDK: getScore
SDK->>API: GET consent score
API-->>SDK: Score with evidenceRef
App->>SDK: getKyc
SDK->>API: GET consent kyc
API-->>SDK: KYC result
App->>Feature: compute features
Feature-->>App: evidence_ref
App->>Evidence: get evidence
Evidence-->>App: Evidence snapshot
Revocation and Access Termination
sequenceDiagram
participant App as Partner application
participant SDK as ConsentsResource
participant API as Regional API
App->>SDK: revoke
SDK->>API: DELETE consent
API-->>SDK: Consent with REVOKED status
App->>SDK: get
SDK->>API: GET consent
API-->>SDK: REVOKED consent
State and Error Handling
Consent Status
| State | Meaning |
|---|---|
PENDING |
Consent exists but has not been activated yet |
ACTIVE |
Consent is usable for consent-scoped access |
REVOKED |
Consent has been revoked and is no longer valid |
EXPIRED |
Consent has passed its expiration window |
The docs state that revocation immediately invalidates access tokens, connections, and refresh capability. The SDK models preserve the consent status directly on the returned Consent object.
Java Error Handling
sdks/java/src/main/java/com/joinlita/HttpClient.java turns HTTP errors into LitaException, which captures:
statusCodeerrorCoderequestIdretryable
Webhook signature validation throws LitaWebhookSignatureException when constructEvent fails the X-Lita-Signature check.
Operational Consent Service
services/consent-service/Dockerfile
The consent service is packaged as its own Node container.
| Dockerfile instruction | Effect |
|---|---|
FROM node:18-alpine |
Uses the Alpine Node 18 runtime |
WORKDIR /app |
Sets the container working directory |
COPY package.json package-lock.json ./ |
Copies package metadata first |
RUN npm ci --omit=dev |
Installs production dependencies only |
COPY src ./src |
Copies service source code |
ENV NODE_ENV=production |
Runs the service in production mode |
EXPOSE 8081 |
Publishes the service port |
CMD ["node", "src/index.js"] |
Starts the service entrypoint |
Operationally, this container fits beside the other API services named in the migration guidance, and it is deployed separately from the SDKs that call the consent endpoints.
Testing Considerations
- Verify consent creation serializes the request body shape used by the SDKs.
- Verify revoke behavior for both
DELETE /consents/{consent_id}and the documentedPOST /consents/{consent_id}/revokeroute. - Verify receipt retrieval returns the disclosure fields expected by the API docs.
- Verify transaction list parsing matches the SDK response envelope used by
TransactionListResponse. - Verify
getScoresurfacesevidence_reffor downstream evidence lookup. - Verify
constructEventrejects invalid webhook signatures.
Key Classes Reference
| Class | Responsibility |
|---|---|
ConsentsResource.java |
Java consent lifecycle client |
ConsentCreateParams.java |
Java consent creation parameters |
Consent.java |
Java consent model |
Score.java |
Java score response model |
TransactionListParams.java |
Java transaction query parameters |
TransactionListResponse.java |
Java transaction list response model |
KycResult.java |
Java KYC result model |
EvidenceResource.java |
Java evidence lookup client |
FeaturesResource.java |
Java feature computation client |
Lita.java |
Java SDK entry point |
consents.ts |
Node consent lifecycle client |
types.ts |
Node consent and evidence types |
consents.py |
Python consent lifecycle client |
types.py |
Python consent and evidence types |
Dockerfile |
Consent service container build |