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
Consent purpose rules
[!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_SCREENINGLENDING_UNDERWRITINGEMPLOYMENT_SCREENINGACCOUNT_OPENINGINCOME_VERIFICATIONFRAUD_PREVENTIONPERSONAL_FINANCEGENERAL_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_screeningIDENTITY_BASIC,ACCOUNTS,BALANCES,TRANSACTIONS,INCOME,EMPLOYMENT,CASHFLOW_FEATURES,DEVICE_RISK,WATCHLIST_SCREENINGpayment_behavior,obligations
normalizeDataCategory normalizes these values to the service enum, and maps:
payment_behavior→cashflow_featuresobligations→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:
tenantIdconsentIdpurposedataCategoriesscope
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/scorePOST /api/v1/jp/decisions/replayGET /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
Consent creation and token exchange
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
Consent revocation and refresh token invalidation
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
Consent and connection lifecycle
| 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/scorereturnsreasons, whiledocuments/jp-api-openapi.yamldefinesreason_codes. The response shape used by clients generated from OpenAPI does not match the implementation. [!NOTE]GET /api/v1/jp/consents/:consentId/data/transactionsreturns{ data, next_cursor, total_count }, while the documentedTransactionListschema uses{ transactions }. This affects generated SDKs and contract tests. [!NOTE]POST /api/v1/jp/consentsacceptsrefresh_permissionsas optional and also acceptsappi_provision, while the OpenAPI request schema marksrefresh_permissionsas required and the documented response shape usesauth.link_urlandauth.link_tokeninstead ofauthorization_urlandredirect_url. [!NOTE]GET /api/v1/jp/data/transactions/syncchecksbalancesscope throughensureCategory(request, reply, "balances"). The handler name and path indicate transaction sync, but the category gate is for balances.
revokeJpConsentsets consent status toREVOKED, connection status toDISCONNECTED, and deletes refresh tokens.refreshJpAccessTokenincrements or creates the daily refresh counter and can flip connection status toREAUTH_REQUIRED.touchJpConnectionupdateslastRefreshedAtand restoresDEGRADEDconnections toACTIVE.createJpConsentseedsaccountsByConsentwith 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
Consent and token lifecycle
Create Consent
{
"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}"
}
}
}
Get Consent
{
"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}"
}
}
}
Get Consent Authorization
{
"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}"
}
}
}
Get Consent Receipt
{
"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}"
}
}
}
Exchange Consent for Tokens
{
"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}"
}
}
}
Consent-scoped access-token surface
List Consent Accounts
{
"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}"
}
}
}
List Consent Balances
{
"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}"
}
}
}
List Consent Transactions
{
"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}"
}
}
}
Get Consent Income Summary
{
"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}"
}
}
}
Compute Consent Features
{
"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}"
}
}
}
Revoke Consent
{
"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.activatedis emitted after token exchangeconnection.createdis emitted after token exchangeconnection.degradedis emitted when a stale connection is detected or when evidence/scoring work encounters a degraded connectionconnection.refreshedis emitted aftertouchJpConnectionconnection.reauth_requiredis emitted on refresh limit exhaustiondecision.completedis emitted after score retrieval or replayconsent.revokedis emitted after revocationfeatures.computedis 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 |