Regional Data Gateways DOMAIN - JP API service internals and Japan-specific contract differences

Overview

The JP API is the Japan-specific regional data gateway under /api/v1/jp. It handles consent creation and revocation, consent authorization and token exchange, access-token backed account and transaction retrieval, JP cashflow evidence generation, and partner-scoring orchestration. The service is built around explicit consent scope, tenant scoping, and audit-oriented records stored through Prisma/PostgreSQL.

The JP surface is distinct from the US surface in both payload semantics and path conventions. It returns JPY-denominated balances, transactions, and income summaries, tags evidence snapshots with JP_CASHFLOW_V1, and carries JP-specific consent purpose and data category rules, including alias normalization for Japan-focused open-banking flows.

Architecture Overview

flowchart LR
    subgraph RouteLayer[JP Route Layer]
        JPRoutes[jpRoutes plugin]
        Guards[Auth and scope guards]
        WebhookEmit[emitWebhook]
    end

    subgraph ServiceLayer[JP Service Layer]
        JPAPI[jp-api service]
        ConsentLogic[Consent and token logic]
        EvidenceLogic[Evidence snapshot logic]
        KeyLogic[JWT key logic]
    end

    subgraph PersistenceLayer[Persistence Layer]
        Prisma[(Prisma PostgreSQL)]
        JPConsent[jpConsent]
        JPConnection[jpConnection]
        JPEvidence[jpEvidenceSnapshot]
        JPRefreshToken[jpRefreshToken]
        JPRefreshCounter[jpRefreshCounter]
    end

    subgraph ExternalIntegrations[External Integrations]
        PartnerScoring[Partner scoring service]
        WebhookQueue[Webhook delivery queue]
    end

    JPRoutes --> Guards
    JPRoutes --> ConsentLogic
    JPRoutes --> EvidenceLogic
    JPRoutes --> KeyLogic
    JPRoutes --> WebhookEmit

    Guards --> JPAPI
    ConsentLogic --> Prisma
    EvidenceLogic --> Prisma
    KeyLogic --> Prisma

    Prisma --> JPConsent
    Prisma --> JPConnection
    Prisma --> JPEvidence
    Prisma --> JPRefreshToken
    Prisma --> JPRefreshCounter

    WebhookEmit --> WebhookQueue
    JPRoutes --> PartnerScoring
    JPAPI --> PartnerScoring

JP Contract Surface

[!NOTE] The published JP contract files and the implementation diverge in several places: consent creation request and response shapes, consent-scoped transaction list shape, decision replay response field names, and the category check used by transaction sync. Those differences are documented below where they are provable from the code.

apps/api/src/routes/jp/index.ts

apps/api/src/services/jp-api.ts

purposeSchema accepts the following values at the route layer:

  • RENTAL_SCREENING
  • LENDING_UNDERWRITING
  • EMPLOYMENT_SCREENING
  • ACCOUNT_OPENING
  • INCOME_VERIFICATION
  • FRAUD_PREVENTION
  • PERSONAL_FINANCE
  • GENERAL_PERSONAL_FINANCE

normalizePurpose maps GENERAL_PERSONAL_FINANCE to PERSONAL_FINANCE before persistence.

Data category rules

apps/api/src/routes/jp/index.ts

apps/api/src/services/jp-api.ts

dataCategorySchema accepts lower-case JP category values and upper-case aliases:

  • identity_basic, accounts, balances, transactions, income, employment, cashflow_features, device_risk, watchlist_screening
  • IDENTITY_BASIC, ACCOUNTS, BALANCES, TRANSACTIONS, INCOME, EMPLOYMENT, CASHFLOW_FEATURES, DEVICE_RISK, WATCHLIST_SCREENING
  • payment_behavior, obligations

normalizeDataCategory normalizes these values to the service enum, and maps:

  • payment_behavior → cashflow_features
  • obligations → cashflow_features

JWT issuer and token semantics

[!NOTE] The route layer accepts payment_behavior, obligations, and upper-case aliases, while the service enum stores normalized lower-case category values. That normalization is part of the JP-specific contract.

apps/api/src/services/jp-api.ts

Item Value Meaning
TOKEN_ISSUER lita-jp-api Issuer required on JP access tokens
TOKEN_AUDIENCE lita-jp-clients Audience required on JP access tokens
ACCESS_TOKEN_TTL_MS 15 * 60 * 1000 Access token lifetime is 15 minutes
CONSENT_TTL_MS 90 * 24 * 60 * 60 * 1000 Default consent lifetime is 90 days
PRIVATE_KEY_PEM process.env.JP_JWT_PRIVATE_KEY Optional configured signing key
PUBLIC_KEY_PEM process.env.JP_JWT_PUBLIC_KEY Optional configured verification key

Token payloads created by exchangeJpConsentToken and refreshJpAccessToken include:

  • tenantId
  • consentId
  • purpose
  • dataCategories
  • scope

The token is signed with RS256, includes jti, and is verified against issuer and audience before use.

JP_CASHFLOW_V1 evidence typing

apps/api/src/services/jp-api.ts

Type Meaning
JpEvidenceSnapshot.featureSet Always JP_CASHFLOW_V1
JpEvidenceSnapshot.features Record<string, number> cashflow feature bag
createJpEvidenceSnapshot Persists the evidence snapshot in jpEvidenceSnapshot
getJpEvidenceSnapshot Loads a snapshot by evidenceRef
getLatestJpEvidenceSnapshotByConsent Loads the newest snapshot for a consent

Evidence snapshots are used by:

  • GET /api/v1/jp/consents/:consentId/score
  • POST /api/v1/jp/decisions/replay
  • GET /api/v1/jp/evidence/:evidenceRef

Japan path conventions

apps/api/src/routes/jp/index.ts

documents/jp-api.md

documents/jp-api-openapi.yaml

The JP implementation uses three path families:

  • Consent lifecycle and partner operations: /api/v1/jp/consents/...
  • Access-token data surfaces: /api/v1/jp/data/...
  • Consent-scoped access-token data surfaces: /api/v1/jp/consents/:consentId/data/...

Feature and score paths are split between:

  • /api/v1/jp/features/compute
  • /api/v1/jp/consents/:consentId/features/compute
  • /api/v1/jp/consents/:consentId/score

Token paths use:

  • /api/v1/jp/consents/:consentId/token
  • /api/v1/jp/tokens/refresh
  • /api/v1/jp/tokens/introspect

Component Structure

JP Routes

apps/api/src/routes/jp/index.ts

jpRoutes is the Fastify plugin that exposes the JP HTTP surface. It wires partner-auth routes, access-token routes, webhook emission, connection freshness handling, scoring orchestration, and consent lifecycle transitions.

Public endpoint methods

Method Description
POST /api/v1/jp/consents Creates a JP consent and returns an authorization URL
GET /api/v1/jp/consents/:consentId Returns consent state and connection list
GET /api/v1/jp/consents/:consentId/authorize Returns the authorization code handoff payload
GET /api/v1/jp/consents/:consentId/receipt Returns the consent receipt
POST /api/v1/jp/consents/:consentId/token Exchanges a consent for access and refresh tokens
POST /api/v1/jp/tokens/refresh Refreshes an access token
POST /api/v1/jp/tokens/introspect Introspects a token
GET /api/v1/jp/data/accounts Lists accounts using an access token
GET /api/v1/jp/data/balances Lists balances using an access token
GET /api/v1/jp/data/transactions Lists transactions using an access token
GET /api/v1/jp/data/transactions/sync Returns a transaction sync payload
GET /api/v1/jp/data/income Returns an income summary using an access token
POST /api/v1/jp/features/compute Computes JP cashflow features in partner-auth or access-token mode
GET /api/v1/jp/consents/:consentId/data/accounts Lists accounts for a consent-bound access token
GET /api/v1/jp/consents/:consentId/data/balances Lists balances for a consent-bound access token
GET /api/v1/jp/consents/:consentId/data/transactions Lists transactions with date and cursor pagination
GET /api/v1/jp/consents/:consentId/data/income Returns income for a consent-bound access token
GET /api/v1/jp/consents/:consentId/features/compute Computes and stores JP cashflow evidence
GET /api/v1/jp/evidence/:evidenceRef Retrieves an evidence snapshot
GET /api/v1/jp/consents/:consentId/score Returns a partner-scoring result from the latest evidence snapshot
POST /api/v1/jp/consents/:consentId/score Replays a decision from an evidence snapshot
GET /api/v1/jp/consents/:consentId/kyc Returns KYC and AML check status
GET /api/v1/jp/status/:jobId Returns the in-memory feature compute job status
DELETE /api/v1/jp/consents/:consentId Revokes a consent

Route guards and helpers

Helper Purpose
requirePartnerAuth Rejects requests when request.jpAccess is already present
requireAccessToken Rejects requests when request.jpAccess is missing
ensurePurpose Compares x-purpose against request.jpAccess.purpose when the header is present
ensureCategory Requires the requested data category to exist in request.jpAccess.dataCategories
normalizePurpose Maps GENERAL_PERSONAL_FINANCE to PERSONAL_FINANCE
normalizeDataCategory Normalizes route input and maps payment_behavior and obligations to cashflow_features
emitWebhook Loads tenant webhook endpoints and enqueues webhook deliveries
ensureConnection Checks connection state, refresh age, and re-authentication requirements

JP Service Module

apps/api/src/services/jp-api.ts

jp-api.ts contains JP-specific persistence, token, evidence, and consent logic.

Exported types

Type Values or properties
JpConsentPurpose RENTAL_SCREENING, LENDING_UNDERWRITING, EMPLOYMENT_SCREENING, ACCOUNT_OPENING, INCOME_VERIFICATION, FRAUD_PREVENTION, PERSONAL_FINANCE
JpDataCategory identity_basic, accounts, balances, transactions, income, employment, cashflow_features, device_risk, watchlist_screening
JpConnectionStatus ACTIVE, REAUTH_REQUIRED, DEGRADED, DISCONNECTED
JpConsentStatus PENDING_USER_ACTION, ACTIVE, REVOKED

Object type properties

Type Property Type Description
JpRefreshPermissions enabled boolean Enables or disables refreshes
JpRefreshPermissions max_refresh_per_day number Daily refresh ceiling
JpEvidenceSnapshot evidenceRef string Snapshot identifier
JpEvidenceSnapshot consentId string Consent identifier
JpEvidenceSnapshot computedAt Date Snapshot timestamp
JpEvidenceSnapshot featureSet "JP_CASHFLOW_V1" Fixed feature set tag
JpEvidenceSnapshot features Record<string, number> Derived cashflow feature bag
JpAccessContext consentId string Consent identifier
JpAccessContext tenantId string Tenant identifier
JpAccessContext purpose JpConsentPurpose Consent purpose
JpAccessContext dataCategories JpDataCategory[] Authorized data categories

Public service methods

Method Description
createJpConsent Creates consent, initial connection, and sample account data
getJpConsent Loads a consent by ID and tenant
revokeJpConsent Revokes a consent, disconnects connections, and deletes refresh tokens
exchangeJpConsentToken Activates a consent and issues tokens
refreshJpAccessToken Refreshes an access token and enforces daily refresh limits
introspectJpToken Verifies token activity and returns consent metadata
verifyJpAccessToken Verifies a JP access token and returns a JpAccessContext
getJpAccounts Returns cached or generated sample account data
createJpEvidenceSnapshot Persists a JP_CASHFLOW_V1 evidence snapshot
getJpEvidenceSnapshot Loads an evidence snapshot by evidenceRef
getLatestJpEvidenceSnapshotByConsent Loads the newest evidence snapshot for a consent
getJpConsentConnectionStatus Loads the first connection for a consent
updateJpConnectionStatus Updates a connection status and optional re-auth URL
touchJpConnection Updates lastRefreshedAt and restores DEGRADED to ACTIVE

Internal helpers and state

Helper or state Purpose
ensureGeneratedKeys Generates an in-process RSA key pair when env keys are missing
getGeneratedPublicKeyPem Returns the generated public key PEM
getPublicKey Imports the configured or generated public key for verification
getRefreshCounterKey Produces the daily refresh counter key
buildSampleAccountData Creates the default JP account, balance, transaction, and income bundle
accountsByConsent In-memory Map<string, AccountData> seeded on consent creation
generatedPrivateKeyPem In-memory fallback private key PEM
generatedPublicKeyPem In-memory fallback public key PEM
privateKeyPromise Memoized jose import for the private key
publicKeyPromise Memoized jose import for the public key

Feature Flows

sequenceDiagram
    participant P as Partner
    participant R as jpRoutes
    participant S as jp-api service
    participant DB as Prisma PostgreSQL
    participant W as Webhook queue

    P->>R: POST /api/v1/jp/consents
    R->>R: requirePartnerAuth
    R->>S: createJpConsent
    S->>DB: create jpConsent
    S->>DB: create jpConnection
    S-->>R: consent with status PENDING_USER_ACTION
    R-->>P: authorization_url and consent_id

    P->>R: POST /api/v1/jp/consents/:consentId/token
    R->>R: requirePartnerAuth
    R->>S: exchangeJpConsentToken
    S->>DB: update jpConsent to ACTIVE
    S->>DB: create jpRefreshToken
    S-->>R: access_token and refresh_token
    R->>W: consent.activated
    R->>W: connection.created
    R-->>P: token response

Access-token data retrieval and connection refresh

sequenceDiagram
    participant A as Client with access token
    participant R as jpRoutes
    participant G as Guards
    participant S as jp-api service
    participant DB as Prisma PostgreSQL
    participant W as Webhook queue

    A->>R: GET /api/v1/jp/data/accounts
    R->>G: requireAccessToken
    R->>G: ensurePurpose and ensureCategory
    R->>S: getJpConsentConnectionStatus
    S->>DB: read jpConnection
    S-->>R: connection record
    R->>S: touchJpConnection
    S->>DB: update jpConnection lastRefreshedAt
    R->>S: getJpAccounts
    S-->>R: account bundle
    R->>W: connection.refreshed
    R-->>A: accounts response

Evidence computation and scoring

sequenceDiagram
    participant P as Partner
    participant R as jpRoutes
    participant S as jp-api service
    participant DB as Prisma PostgreSQL
    participant X as Partner scoring service
    participant W as Webhook queue

    P->>R: GET /api/v1/jp/consents/:consentId/features/compute
    R->>R: requireAccessToken
    R->>R: ensurePurpose and ensureCategory
    R->>S: getJpAccounts
    S-->>R: transactions balances income
    R->>S: createJpEvidenceSnapshot
    S->>DB: insert jpEvidenceSnapshot
    S-->>R: evidenceRef and features
    R-->>P: evidence_ref and features

    P->>R: GET /api/v1/jp/consents/:consentId/score
    R->>R: requirePartnerAuth
    R->>S: getLatestJpEvidenceSnapshotByConsent
    S->>DB: read latest jpEvidenceSnapshot
    R->>X: fetchScoringDecision
    X-->>R: decision and reasons
    R->>W: decision.completed
    R-->>P: score payload
sequenceDiagram
    participant P as Partner
    participant R as jpRoutes
    participant S as jp-api service
    participant DB as Prisma PostgreSQL
    participant W as Webhook queue

    P->>R: DELETE /api/v1/jp/consents/:consentId
    R->>R: requirePartnerAuth
    R->>S: revokeJpConsent
    S->>DB: update jpConsent to REVOKED
    S->>DB: update jpConnection to DISCONNECTED
    S->>DB: delete jpRefreshToken rows
    S-->>R: revoked consent
    R->>W: consent.revoked
    R-->>P: revoked response

State Management

State family Values How the code uses them
Consent status PENDING_USER_ACTION, ACTIVE, REVOKED Stored in jpConsent and updated by create, token exchange, and revoke
Consent response status PENDING, ACTIVE, REVOKED, EXPIRED Computed by GET /api/v1/jp/consents/:consentId from stored status and expiry time
Connection status ACTIVE, REAUTH_REQUIRED, DEGRADED, DISCONNECTED Stored in jpConnection and updated by refresh, stale checks, and revoke
Job status PROCESSING, COMPLETE, FAILED Stored in the in-memory jpJobStore
Evidence feature set JP_CASHFLOW_V1 Stored in jpEvidenceSnapshot and returned by evidence helpers
stateDiagram-v2
    [*] --> PENDING_USER_ACTION
    PENDING_USER_ACTION --> ACTIVE: exchangeJpConsentToken
    ACTIVE --> REVOKED: revokeJpConsent

    [*] --> ACTIVE
    ACTIVE --> DEGRADED: ensureConnection stale
    DEGRADED --> ACTIVE: touchJpConnection
    ACTIVE --> REAUTH_REQUIRED: refresh limit exceeded
    REAUTH_REQUIRED --> ACTIVE: exchangeJpConsentToken
    ACTIVE --> DISCONNECTED: revokeJpConsent

Error Handling

The JP routes use structured sendError responses with an error object containing code, message, request_id, and retryable. Runtime checks happen before the data handler executes.

Guard and service error paths

Condition Error code Status
Access token missing ACCESS_TOKEN_REQUIRED 401
Partner token present on partner-auth endpoint TOKEN_NOT_ALLOWED 401
Consent ID mismatch with access token CONSENT_MISMATCH 403
Purpose header mismatch PURPOSE_NOT_ALLOWED 403
Category missing from token scope CATEGORY_NOT_ALLOWED 403
Consent not found not_found or CONSENT_NOT_FOUND 404
Connection not found CONNECTION_NOT_FOUND 404
Re-authentication required REAUTH_REQUIRED 409
Consent not active consent_not_active 422
Evidence not ready score_not_ready 422
Provider unavailable PROVIDER_UNAVAILABLE 502
Legal restriction on score replay LEGAL_RESTRICTION 400
Refresh limit exceeded REFRESH_LIMIT_EXCEEDED 400
Consent revoked during refresh CONSENT_REVOKED 401

Proven contract discrepancies

Caching and Persistence

In-memory state and database-backed state

Store Type Key Used by Lifecycle
accountsByConsent Map<string, AccountData> consentId getJpAccounts Seeded in createJpConsent and read by account, balance, transaction, income, and feature endpoints
jpJobStore Map<string, JpJobRecord> jobId GET /api/v1/jp/status/:jobId Written by the partner-auth compute path
jpConsent Prisma table consentId Consent and token endpoints Stores purpose, categories, expiry, and status
jpConnection Prisma table connectionId and consentId Connection freshness and data access Updated by touchJpConnection, updateJpConnectionStatus, and revoke
jpEvidenceSnapshot Prisma table evidenceRef and consentId Evidence and scoring Stores JP_CASHFLOW_V1 snapshots
jpRefreshToken Prisma table refresh_token Refresh flow Deleted on revoke
jpRefreshCounter Prisma table consentId + date Refresh flow Enforces per-day refresh limits

Key invalidation and update points

[!NOTE] POST /api/v1/jp/consents/:consentId/score returns reasons, while documents/jp-api-openapi.yaml defines reason_codes. The response shape used by clients generated from OpenAPI does not match the implementation. [!NOTE] GET /api/v1/jp/consents/:consentId/data/transactions returns { data, next_cursor, total_count }, while the documented TransactionList schema uses { transactions }. This affects generated SDKs and contract tests. [!NOTE] POST /api/v1/jp/consents accepts refresh_permissions as optional and also accepts appi_provision, while the OpenAPI request schema marks refresh_permissions as required and the documented response shape uses auth.link_url and auth.link_token instead of authorization_url and redirect_url. [!NOTE] GET /api/v1/jp/data/transactions/sync checks balances scope through ensureCategory(request, reply, "balances"). The handler name and path indicate transaction sync, but the category gate is for balances.

  • revokeJpConsent sets consent status to REVOKED, connection status to DISCONNECTED, and deletes refresh tokens.
  • refreshJpAccessToken increments or creates the daily refresh counter and can flip connection status to REAUTH_REQUIRED.
  • touchJpConnection updates lastRefreshedAt and restores DEGRADED connections to ACTIVE.
  • createJpConsent seeds accountsByConsent with sample JP data.

Dependencies

Runtime packages and services

Dependency Role
fastify Route plugin and request lifecycle
zod Request and response schema validation
jose RS256 JWT signing and verification
node:crypto RSA key generation and request identifiers
@lita/db Prisma client access to JP consent, connection, evidence, and refresh tables
@lita/webhooks Tenant webhook endpoint lookup and delivery enqueueing
../../services/partner-scoring.js Partner scoring integration used by score and replay endpoints

Environment variables

Variable Used by Purpose
JP_JWT_PRIVATE_KEY jp-api.ts Optional signing key
JP_JWT_PUBLIC_KEY jp-api.ts Optional verification key
API_PUBLIC_BASE_URL createJpConsent, refreshJpAccessToken Builds authorization and re-auth URLs
SCORING_CALLBACK_URL score endpoints Fallback partner scoring destination

Testing Considerations

Scenario What to verify
Consent creation GENERAL_PERSONAL_FINANCE normalizes to PERSONAL_FINANCE, and category aliases normalize correctly
Consent token exchange JWT contains the JP issuer and audience, and activation emits the consent and connection webhook events
Access-token data access requireAccessToken, purpose check, category check, and consent ID match all run before data is returned
Connection freshness Stale active connections become DEGRADED and emit connection.degraded
Refresh limits Exceeding the daily refresh ceiling returns REFRESH_LIMIT_EXCEEDED and sets re-auth requirements
Evidence generation createJpEvidenceSnapshot persists JP_CASHFLOW_V1 and returns the stored snapshot fields
Score replay reasons is returned by the implementation even though the OpenAPI contract names reason_codes
Revocation Refresh tokens are deleted and the consent status is returned as REVOKED
Transaction list shape Consent-scoped transaction lists return data, next_cursor, and total_count

API Integration

{
    "title": "Create Consent",
    "description": "Creates a JP consent authorization and returns the authorization URL",
    "method": "POST",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <PARTNER_API_KEY>",
            "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        \"balances\",\n        \"transactions\",\n        \"income\",\n        \"cashflow_features\"\n    ],\n    \"expires_in_days\": 30,\n    \"refresh_permissions\": {\n        \"enabled\": true,\n        \"max_refresh_per_day\": 8\n    },\n    \"user\": {\n        \"country\": \"JP\"\n    },\n    \"appi_provision\": {\n        \"provider\": \"appi\",\n        \"policy_id\": \"jp-rental-screening-v1\"\n    }\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "201": {
            "description": "Consent created",
            "body": "{\n    \"consent_id\": \"cons_34921\",\n    \"authorization_url\": \"https://api.joinlita.com/api/v1/jp/consents/cons_34921/authorize\",\n    \"redirect_url\": \"https://api.joinlita.com/api/v1/jp/consents/cons_34921/authorize\",\n    \"status\": \"PENDING\",\n    \"expires_at\": \"2026-04-30T12:00:00.000Z\"\n}"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{\n    \"error\": {\n        \"code\": \"TOKEN_NOT_ALLOWED\",\n        \"message\": \"Partner token required\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Get Consent",
    "description": "Returns consent state and the current connection list",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <PARTNER_API_KEY>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "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    \"activated_at\": \"2026-04-01T09:15:00.000Z\",\n    \"expires_at\": \"2026-04-30T12:00:00.000Z\",\n    \"connections\": [\n        {\n            \"connection_id\": \"conn_81d9f4\",\n            \"provider\": \"Financial Provider\",\n            \"status\": \"ACTIVE\"\n        }\n    ]\n}"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{\n    \"error\": {\n        \"code\": \"TOKEN_NOT_ALLOWED\",\n        \"message\": \"Partner token required\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        },
        "404": {
            "description": "Not found",
            "body": "{\n    \"error\": {\n        \"code\": \"not_found\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Get Consent Authorization",
    "description": "Returns the authorization code handoff payload for a consent",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/authorize",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_34921",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Authorization complete",
            "body": "{\n    \"consent_id\": \"cons_34921\",\n    \"purpose\": \"RENTAL_SCREENING\",\n    \"data_categories\": [\n        \"accounts\",\n        \"balances\",\n        \"transactions\",\n        \"income\",\n        \"cashflow_features\"\n    ],\n    \"status\": \"PENDING_USER_ACTION\",\n    \"authorization_code\": \"ok\",\n    \"message\": \"Authorization complete. Exchange this code for an access token via POST /consents/:consentId/token\"\n}"
        },
        "404": {
            "description": "Not found",
            "body": "{\n    \"error\": {\n        \"code\": \"consent_not_found\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        },
        "409": {
            "description": "Conflict",
            "body": "{\n    \"error\": {\n        \"code\": \"consent_revoked\",\n        \"message\": \"Consent is no longer valid\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Get Consent Receipt",
    "description": "Returns the consent receipt with disclosure and provisioning data",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/receipt",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <PARTNER_API_KEY>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "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        \"income\",\n        \"cashflow_features\"\n    ],\n    \"disclosure_version\": \"jp-v1\",\n    \"status\": \"ACTIVE\",\n    \"created_at\": \"2026-04-01T09:00:00.000Z\",\n    \"revoked_at\": null,\n    \"appi_provision\": {\n        \"provider\": \"appi\",\n        \"policy_id\": \"jp-rental-screening-v1\"\n    }\n}"
        },
        "404": {
            "description": "Not found",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_NOT_FOUND\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Exchange Consent for Tokens",
    "description": "Activates a consent and issues an access token and refresh token",
    "method": "POST",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/token",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <PARTNER_API_KEY>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_34921",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"authorization_code\": \"ok\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Tokens issued",
            "body": "{\n    \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.JP_ACCESS_TOKEN_SIGNATURE\",\n    \"refresh_token\": \"rtk_5f8b9d3f2a\",\n    \"expires_in\": 900,\n    \"token_type\": \"Bearer\",\n    \"scope\": \"accounts balances transactions income cashflow_features\"\n}"
        },
        "404": {
            "description": "Not found",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_NOT_FOUND\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Refresh Access Token

{
    "title": "Refresh Access Token",
    "description": "Refreshes a JP access token using a refresh token",
    "method": "POST",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/tokens/refresh",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <PARTNER_API_KEY>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"refresh_token\": \"rtk_5f8b9d3f2a\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Tokens refreshed",
            "body": "{\n    \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.JP_REFRESHED_ACCESS_TOKEN\",\n    \"refresh_token\": \"rtk_9a2f7bb4c1\",\n    \"expires_in\": 900,\n    \"token_type\": \"Bearer\",\n    \"scope\": \"accounts balances transactions income cashflow_features\"\n}"
        },
        "400": {
            "description": "Refresh not allowed",
            "body": "{\n    \"error\": {\n        \"code\": \"REFRESH_LIMIT_EXCEEDED\",\n        \"message\": \"Refresh not allowed\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        },
        "401": {
            "description": "Consent revoked or invalid refresh token",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_REVOKED\",\n        \"message\": \"Refresh not allowed\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Introspect Token

{
    "title": "Introspect Token",
    "description": "Returns token activity and consent metadata",
    "method": "POST",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/tokens/introspect",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <PARTNER_API_KEY>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.JP_ACCESS_TOKEN_SIGNATURE\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Token status",
            "body": "{\n    \"active\": true,\n    \"expires_at\": \"2026-04-01T09:30:00.000Z\",\n    \"consent_id\": \"cons_34921\",\n    \"purpose\": \"RENTAL_SCREENING\",\n    \"data_categories\": [\n        \"accounts\",\n        \"balances\",\n        \"transactions\",\n        \"income\",\n        \"cashflow_features\"\n    ]\n}"
        }
    }
}

Global access-token data surface

List Accounts

{
    "title": "List Accounts",
    "description": "Lists JPY account records using an access token",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/data/accounts",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <ACCESS_TOKEN>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Account list",
            "body": "{\n    \"accounts\": [\n        {\n            \"account_id\": \"jp_acct_cons_34921\",\n            \"name\": \"Everyday Checking\",\n            \"type\": \"checking\",\n            \"mask\": \"9876\",\n            \"institution\": \"JP Example Bank\"\n        }\n    ]\n}"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

List Balances

{
    "title": "List Balances",
    "description": "Lists JPY balances using an access token",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/data/balances",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <ACCESS_TOKEN>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Balances list",
            "body": "{\n    \"balances\": [\n        {\n            \"account_id\": \"jp_acct_cons_34921\",\n            \"available\": 320000,\n            \"current\": 352000,\n            \"currency\": \"JPY\"\n        }\n    ]\n}"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

List Transactions

{
    "title": "List Transactions",
    "description": "Lists JPY transactions using an access token",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/data/transactions",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <ACCESS_TOKEN>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "from",
            "value": "2026-03-01",
            "required": false
        },
        {
            "key": "to",
            "value": "2026-03-31",
            "required": false
        },
        {
            "key": "start_date",
            "value": "2026-03-01",
            "required": false
        },
        {
            "key": "end_date",
            "value": "2026-03-31",
            "required": false
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Transaction list",
            "body": "{\n    \"transactions\": [\n        {\n            \"transaction_id\": \"jp_txn_cons_34921_1\",\n            \"account_id\": \"jp_acct_cons_34921\",\n            \"posted_at\": \"2026-03-31T08:15:00.000Z\",\n            \"amount\": -12450,\n            \"currency\": \"JPY\",\n            \"description\": \"Transit\",\n            \"category\": \"TRANSPORTATION\"\n        }\n    ]\n}"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Sync Transactions

{
    "title": "Sync Transactions",
    "description": "Returns a transaction sync payload for incremental ingestion",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/data/transactions/sync",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <ACCESS_TOKEN>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "cursor",
            "value": "cur_0",
            "required": false
        },
        {
            "key": "limit",
            "value": "100",
            "required": false
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Transaction sync",
            "body": "{\n    \"cursor\": \"cur_100\",\n    \"added\": [\n        {\n            \"transaction_id\": \"jp_txn_cons_34921_2\",\n            \"account_id\": \"jp_acct_cons_34921\",\n            \"posted_at\": \"2026-03-30T08:15:00.000Z\",\n            \"amount\": 420000,\n            \"currency\": \"JPY\",\n            \"description\": \"Payroll\",\n            \"category\": \"INCOME\"\n        }\n    ],\n    \"modified\": [],\n    \"removed\": [\n        {\n            \"transaction_id\": \"jp_txn_cons_34921_1\"\n        }\n    ]\n}"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get Income Summary

{
    "title": "Get Income Summary",
    "description": "Returns a JPY income summary using an access token",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/data/income",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <ACCESS_TOKEN>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Income summary",
            "body": "{\n    \"method\": \"INFERRED\",\n    \"gross_monthly\": 420000,\n    \"net_monthly\": 356000,\n    \"currency\": \"JPY\"\n}"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Compute Cashflow Features

{
    "title": "Compute Cashflow Features",
    "description": "Computes JP cashflow features. When consent_id is supplied the handler runs in partner-auth mode and returns 202. Without consent_id the access-token path returns 200.",
    "method": "POST",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/features/compute",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <PARTNER_API_KEY>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"consent_id\": \"cons_34921\",\n    \"feature_set\": \"JP_CASHFLOW_V1\",\n    \"as_of\": \"2026-03-31\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "202": {
            "description": "Feature job accepted",
            "body": "{\n    \"job_id\": \"job_8f2b9d7f3a1c\",\n    \"status\": \"PROCESSING\",\n    \"consent_id\": \"cons_34921\",\n    \"estimated_completion_ms\": 0\n}"
        },
        "200": {
            "description": "Feature compute response",
            "body": "{\n    \"evidence_ref\": \"ev_33821\",\n    \"features\": {\n        \"monthly_income\": 420000,\n        \"avg_balance\": 352000,\n        \"overdraft_count\": 0,\n        \"cashflow_surplus\": 407550,\n        \"cashflow_inflow\": 420000,\n        \"cashflow_outflow\": 12450,\n        \"cashflow_net\": 407550\n    }\n}"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        },
        "403": {
            "description": "Forbidden",
            "body": "{\n    \"error\": {\n        \"code\": \"CATEGORY_NOT_ALLOWED\",\n        \"message\": \"cashflow_features not permitted by consent\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "List Consent Accounts",
    "description": "Lists accounts for a consent-bound access token",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/data/accounts",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <ACCESS_TOKEN>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_34921",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Account list",
            "body": "{\n    \"accounts\": [\n        {\n            \"account_id\": \"jp_acct_cons_34921\",\n            \"name\": \"Everyday Checking\",\n            \"type\": \"checking\",\n            \"mask\": \"9876\",\n            \"institution\": \"JP Example Bank\"\n        }\n    ]\n}"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "List Consent Balances",
    "description": "Lists balances for a consent-bound access token",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/data/balances",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <ACCESS_TOKEN>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_34921",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Balances list",
            "body": "{\n    \"balances\": [\n        {\n            \"account_id\": \"jp_acct_cons_34921\",\n            \"available\": 320000,\n            \"current\": 352000,\n            \"currency\": \"JPY\"\n        }\n    ]\n}"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "List Consent Transactions",
    "description": "Lists transactions with date range and cursor pagination for a consent-bound access token",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/data/transactions",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <ACCESS_TOKEN>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "from",
            "value": "2026-03-01",
            "required": false
        },
        {
            "key": "to",
            "value": "2026-03-31",
            "required": false
        },
        {
            "key": "start_date",
            "value": "2026-03-01",
            "required": false
        },
        {
            "key": "end_date",
            "value": "2026-03-31",
            "required": false
        },
        {
            "key": "from_date",
            "value": "2026-03-01",
            "required": false
        },
        {
            "key": "to_date",
            "value": "2026-03-31",
            "required": false
        },
        {
            "key": "limit",
            "value": "50",
            "required": false
        },
        {
            "key": "cursor",
            "value": "cur_0",
            "required": false
        }
    ],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_34921",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Transaction list",
            "body": "{\n    \"data\": [\n        {\n            \"transaction_id\": \"jp_txn_cons_34921_1\",\n            \"date\": \"2026-03-31\",\n            \"amount\": -12450,\n            \"currency\": \"JPY\",\n            \"description\": \"Transit\",\n            \"category\": \"TRANSPORTATION\",\n            \"type\": \"DEBIT\"\n        }\n    ],\n    \"next_cursor\": \"cur_50\",\n    \"total_count\": 2\n}"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Get Consent Income Summary",
    "description": "Returns an income summary for a consent-bound access token",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/data/income",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <ACCESS_TOKEN>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_34921",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Income summary",
            "body": "{\n    \"method\": \"INFERRED\",\n    \"gross_monthly\": 420000,\n    \"net_monthly\": 356000,\n    \"currency\": \"JPY\"\n}"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Compute Consent Features",
    "description": "Computes and stores JP cashflow evidence for a consent-bound access token",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/features/compute",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <ACCESS_TOKEN>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_34921",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Feature compute response",
            "body": "{\n    \"evidence_ref\": \"ev_33821\",\n    \"features\": {\n        \"monthly_income\": 420000,\n        \"avg_balance\": 352000,\n        \"overdraft_count\": 0,\n        \"cashflow_surplus\": 407550,\n        \"cashflow_inflow\": 420000,\n        \"cashflow_outflow\": 12450,\n        \"cashflow_net\": 407550\n    }\n}"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{\n    \"error\": {\n        \"code\": \"ACCESS_TOKEN_REQUIRED\",\n        \"message\": \"Access token required\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Evidence and decision surface

Get Evidence Snapshot

{
    "title": "Get Evidence Snapshot",
    "description": "Retrieves an immutable JP evidence snapshot",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/evidence/:evidenceRef",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <PARTNER_API_KEY>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "evidenceRef",
            "value": "ev_33821",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Evidence snapshot",
            "body": "{\n    \"evidence_ref\": \"ev_33821\",\n    \"consent_id\": \"cons_34921\",\n    \"applicant_id\": \"app_12821\",\n    \"snapshot_version\": \"1.2.0\",\n    \"created_at\": \"2026-03-31T09:30:00.000Z\",\n    \"score_inputs\": {\n        \"payment_behavior\": {\n            \"payments_observed\": 4200,\n            \"avg_payment_delay_days\": 0,\n            \"late_payment_count_30d_plus\": 0\n        },\n        \"income\": {\n            \"monthly_net_income\": 356000,\n            \"income_stability_score\": 0.96\n        },\n        \"obligations\": {\n            \"total_monthly_obligations\": 106800,\n            \"obligation_to_income_ratio\": 0.3\n        }\n    },\n    \"kyc_result\": {\n        \"status\": \"PASSED\",\n        \"checks\": [\n            \"identity\",\n            \"sanctions\",\n            \"pep\"\n        ]\n    },\n    \"delinquency_bucket\": \"CURRENT\",\n    \"features\": {\n        \"monthly_income\": 420000,\n        \"avg_balance\": 352000,\n        \"overdraft_count\": 0,\n        \"cashflow_surplus\": 407550,\n        \"cashflow_inflow\": 420000,\n        \"cashflow_outflow\": 12450,\n        \"cashflow_net\": 407550\n    }\n}"
        },
        "404": {
            "description": "Not found",
            "body": "{\n    \"error\": {\n        \"code\": \"not_found\",\n        \"message\": \"Evidence snapshot not found\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get Score

{
    "title": "Get Score",
    "description": "Returns the partner scoring result for the latest JP evidence snapshot",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/score",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <PARTNER_API_KEY>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_34921",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Score response",
            "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    ],\n    \"evidence_ref\": \"ev_33821\",\n    \"scored_at\": \"2026-03-31T09:31:00.000Z\",\n    \"model_version\": \"1.2.0\"\n}"
        },
        "404": {
            "description": "Not found",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_NOT_FOUND\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        },
        "422": {
            "description": "Not ready",
            "body": "{\n    \"error\": {\n        \"code\": \"score_not_ready\",\n        \"message\": \"Feature computation has not completed. Wait for score.completed webhook.\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        },
        "502": {
            "description": "Provider unavailable",
            "body": "{\n    \"error\": {\n        \"code\": \"provider_unavailable\",\n        \"message\": \"Scoring provider error\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": true\n    }\n}"
        }
    }
}

Replay Decision

{
    "title": "Replay Decision",
    "description": "Replays a partner decision from an evidence snapshot",
    "method": "POST",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/decisions/replay",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <PARTNER_API_KEY>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"evidence_ref\": \"ev_33821\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Decision replayed",
            "body": "{\n    \"evidence_ref\": \"ev_33821\",\n    \"decision\": \"APPROVE\",\n    \"reasons\": [\n        \"LOW_BALANCE_VOLATILITY\"\n    ]\n}"
        },
        "404": {
            "description": "Not found",
            "body": "{\n    \"error\": {\n        \"code\": \"EVIDENCE_NOT_FOUND\",\n        \"message\": \"Evidence not found\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get KYC Status

{
    "title": "Get KYC Status",
    "description": "Returns KYC and AML results for a consent",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/kyc",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <PARTNER_API_KEY>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_34921",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "KYC status",
            "body": "{\n    \"consent_id\": \"cons_34921\",\n    \"status\": \"PASSED\",\n    \"checks\": {\n        \"identity\": {\n            \"status\": \"PASSED\",\n            \"method\": \"document_biometric\"\n        },\n        \"sanctions\": {\n            \"status\": \"PASSED\",\n            \"lists_screened\": [\n                \"OFAC\",\n                \"UN\",\n                \"EU\"\n            ]\n        },\n        \"pep\": {\n            \"status\": \"PASSED\"\n        },\n        \"aml\": {\n            \"status\": \"PASSED\",\n            \"risk_level\": \"LOW\"\n        }\n    },\n    \"completed_at\": \"2026-03-31T09:30:00.000Z\"\n}"
        },
        "404": {
            "description": "Not found",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_NOT_FOUND\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        },
        "422": {
            "description": "Not ready",
            "body": "{\n    \"error\": {\n        \"code\": \"consent_not_active\",\n        \"message\": \"KYC checks are run during feature computation. Activate the consent first.\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Get Job Status

{
    "title": "Get Job Status",
    "description": "Returns the in-memory feature compute job status",
    "method": "GET",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/status/:jobId",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <PARTNER_API_KEY>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "jobId",
            "value": "job_8f2b9d7f3a1c",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Job status",
            "body": "{\n    \"job_id\": \"job_8f2b9d7f3a1c\",\n    \"status\": \"COMPLETE\",\n    \"consent_id\": \"cons_34921\",\n    \"completed_at\": \"2026-03-31T09:30:05.000Z\",\n    \"error\": null\n}"
        },
        "404": {
            "description": "Not found",
            "body": "{\n    \"error\": {\n        \"code\": \"not_found\",\n        \"message\": \"Job not found\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}
{
    "title": "Revoke Consent",
    "description": "Revokes a consent and disconnects its refresh capability",
    "method": "DELETE",
    "baseUrl": "<JpApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <PARTNER_API_KEY>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "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    \"revoked_at\": \"2026-03-31T09:45:00.000Z\"\n}"
        },
        "404": {
            "description": "Not found",
            "body": "{\n    \"error\": {\n        \"code\": \"CONSENT_NOT_FOUND\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_23981\",\n        \"retryable\": false\n    }\n}"
        }
    }
}

Webhook Delivery Service

apps/api/src/routes/jp/index.ts

The route module uses the webhook delivery layer through listWebhookEndpoints and enqueueWebhookDelivery.

Function Role in JP flows
listWebhookEndpoints Resolves tenant webhook endpoints before delivery
enqueueWebhookDelivery Queues signed delivery work per endpoint

Webhook event flow

  • consent.activated is emitted after token exchange
  • connection.created is emitted after token exchange
  • connection.degraded is emitted when a stale connection is detected or when evidence/scoring work encounters a degraded connection
  • connection.refreshed is emitted after touchJpConnection
  • connection.reauth_required is emitted on refresh limit exhaustion
  • decision.completed is emitted after score retrieval or replay
  • consent.revoked is emitted after revocation
  • features.computed is emitted by the partner-auth compute path

Logging and Error Telemetry

apps/api/src/routes/jp/index.ts

The JP route module logs webhook enqueue failures and scoring callback failures using reply.log.error.

Log site Trigger
emitWebhook Webhook endpoint lookup or enqueue failure
GET /api/v1/jp/consents/:consentId/score Scoring callback exception
POST /api/v1/jp/decisions/replay Scoring callback exception

Key Classes Reference

Class Responsibility
jp-api.ts JP consent, token, evidence, and connection internals
index.ts JP HTTP routes, guards, webhooks, scoring, and response shaping
jp-api.md JP narrative contract, JP-specific semantics, and endpoint summaries
jp-api-openapi.yaml JP OpenAPI contract, request and response schemas, and security schemes