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

[!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.md and documents/jp-api.md show consent creation with applicant_id, purpose, data_categories, and expires_in_days. - documents/us-api-openapi.yaml and documents/jp-api-openapi.yaml require user and refresh_permissions in CreateConsentRequest. - The OpenAPI create response is ConsentResponse with auth.link_url and auth.link_token. - The SDKs deserialize a Consent object with redirect_url, created_at, activated_at, expires_at, revoked_at, and connections. - The OpenAPI revoke route is POST /api/v1/{region}/consents/{consent_id}/revoke. - The SDKs revoke with DELETE /{region}/consents/{consent_id}. - The OpenAPI data and feature routes under /api/v1/{region}/data/... and /api/v1/{region}/features/compute use access-token security and different response envelopes from the consent-scoped SDK methods. - The Java HTTP client parses nested error fields and retryable, while the OpenAPI error schema publishes a simpler ErrorResponse.

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.

{
    "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}"
        }
    }
}
{
    "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}"
        }
    }
}

The receipt endpoint is documented in the API specs and returns the legal disclosure record for a consent.

{
    "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}"
        }
    }
}
{
    "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}"
        }
    }
}

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}"
        }
    }
}

This step sits between authorization and consent-scoped data access.

{
    "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}"
        }
    }
}

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}"
        }
    }
}
{
    "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
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
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
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
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
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

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
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

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:

  • statusCode
  • errorCode
  • requestId
  • retryable

Webhook signature validation throws LitaWebhookSignatureException when constructEvent fails the X-Lita-Signature check.

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 documented POST /consents/{consent_id}/revoke route.
  • 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 getScore surfaces evidence_ref for downstream evidence lookup.
  • Verify constructEvent rejects 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