Skip to Content
RiskOverview and API

Independent risk framework

Risk subjects outlive verification sessions. Attach evidence to a person, business, account or transaction, evaluate a published policy, and retain the assessment and its explanation. A policy key identifies a purpose, such as onboarding or fraud; one subject can have separate current assessments for each.

This API is independent of Korala’s predefined session fraud evaluators. It does not automatically approve identities, change account permissions or deliver payment restrictions.

Authentication and environments

Use the usual HMAC API credentials or dashboard JWT. Every resource belongs to an organization and a test/live environment. API keys are pinned to their mode; a test key cannot read or mutate live resources. Dashboard JWTs default to live; send X-Risk-Mode: test to manage test resources. OAuth assistant connections cannot use these endpoints yet.

Owner/admin JWTs are required to create/publish policies, create/revoke overrides and cancel actions. External evidence submissions require an API key authorized by a registered source. Authenticated clients can evaluate published policies and acknowledge action execution within their organization and environment.

Every mutation needs an Idempotency-Key header (1–120 letters, digits, underscores, dots, colons or hyphens). Retry an identical operation with the same key. Reusing a key with different input or a different principal returns 409. Successful retries return the same resource ID. Retrying an evaluation does not rerun its original assessment; read its state endpoint for currentness. Failed transactions do not consume the key.

Resources

All paths below are relative to /api/v1.

OperationEndpoint
Create a subjectPOST /risk/subjects
Register a journey contextPOST /risk/contexts
Attach a subject to a contextPOST /risk/contexts/{id}/subjects
List context membershipsGET /risk/contexts/{id}/subjects
Read pinned context policiesGET /risk/contexts/{id}/policies
Replace pinned context policiesPOST /risk/contexts/{id}/policies
Create a draft policy versionPOST /risk/policies
Publish a policyPOST /risk/policies/{id}/publish
Append evidencePOST /risk/subjects/{id}/evidence
Register an external evidence source (owner/admin JWT)POST /risk/sources
Replace source key bindings (owner/admin JWT)POST /risk/sources/{id}/bindings
Append context evidencePOST /risk/contexts/{contextId}/subjects/{subjectId}/evidence
Submit a context evidence batchPOST /risk/contexts/{contextId}/subjects/{subjectId}/evidence/batch
Read a context evidence receiptGET /risk/contexts/{contextId}/subjects/{subjectId}/evidence/{evidenceId}
Read a context evidence batchGET /risk/contexts/{contextId}/subjects/{subjectId}/evidence/batches/{batchId}
Evaluate a context policyPOST /risk/contexts/{contextId}/subjects/{subjectId}/assessments
Read context assessment currentnessGET /risk/contexts/{contextId}/subjects/{subjectId}/assessments/{assessmentId}/state
Enable or pause context monitoringPOST /risk/contexts/{contextId}/subjects/{subjectId}/monitoring
Read context monitoring settingsGET /risk/contexts/{contextId}/subjects/{subjectId}/monitoring
Create a policy composition (owner/admin JWT)POST /risk/compositions
Read composition configurationGET /risk/compositions/{compositionVersionId}
Read combined general stateGET /risk/subjects/{subjectId}/compositions/{compositionVersionId}
Read combined context stateGET /risk/contexts/{contextId}/subjects/{subjectId}/compositions/{compositionVersionId}
Evaluate a policyPOST /risk/subjects/{id}/assessments
Read currentness/effective decisionGET /risk/assessments/{id}/state
Record an overridePOST /risk/assessments/{id}/overrides
Revoke an overridePOST /risk/overrides/{id}/revoke
Update an actionPOST /risk/actions/{id}/transitions
List recordsGET /risk/{resource}
Read a recordGET /risk/{resource}/{id}

Resources are subjects, policies, evidence, assessments, overrides, actions, events, sources and contexts. Responses wrap the record as { id, resource, data }. Composition endpoints return their typed configuration or combined result, rather than the generic record wrapper. List responses contain items and nextOffset; follow non-null offsets for pages of at most 100 records and 1 MiB. A page can be shorter because of its byte budget; always follow nextOffset, not the item count. Evidence, assessments, overrides, actions, events and contexts support ?subjectId=.... Policies and subjects do not support that filter.

The OpenAPI schemas describe each record’s data. Assessment data includes the policy snapshot, evaluation time, sequence, evidence revision, previous assessment ID, exact input snapshots, score, band and factor/rule results.

Journey contexts

Register a context to identify a journey or resource, then attach existing risk subjects to it. One context can have several subjects, and one subject can belong to several contexts. For example, use account_access for a login journey or purchase for a purchase in your system.

Use context paths to submit journey evidence and evaluate a pinned policy for a member. Context registration alone does not establish identity or participation. Sending contextId on a risk request body or query returns 400; select the context through its URL. A context-scoped input reads evidence from that journey, while an input without a scope reads the subject’s general evidence.

Combine general and journey policies when a participation decision needs both. A general assessment can contribute to several journeys; evidence submitted for one context stays separate from another context.

Create a context with an authenticated request and an Idempotency-Key:

{ "kind": "account_access", "externalId": "access-attempt-123" }

Use a stable reference from your system, without names or document contents. kind uses 1–80 lowercase letters, digits, underscores, dots or hyphens, starting with a letter. externalId is a nonempty string of at most 200 characters. The kind/reference combination is unique within your organization and environment. A duplicate under a different request key returns 409; retry an interrupted creation with its original key. Context identity cannot be edited through this API.

Attach a subject through POST /risk/contexts/{id}/subjects:

{ "subjectId": "<existing-risk-subject-id>" }

Both resources must belong to your organization and the same test/live mode. Missing or inaccessible resources return 404. Korala records the authenticated caller; supplied ownership or actor fields cannot change that attribution. Adding an existing membership returns its original data, without another membership event. Membership represents your integration’s assertion that the user participates in this context, not proof of identity or consent.

List memberships through GET /risk/contexts/{id}/subjects. Follow nextOffset for pages of at most 100 memberships; concurrent changes can affect pagination. Use GET /risk/contexts?subjectId=... to list a subject’s contexts. Context lists also support literal, case-insensitive search on the external reference. The SDK exposes risk.createContext, risk.addContextSubject and risk.contextSubjects, alongside risk.get('contexts', id) and risk.list('contexts', query).

You can subscribe to risk.context.created and risk.context.subject_added. Apply the push integration authentication, deduplication and current state reconciliation rules. These events report registration and membership; they do not carry a risk decision.

Pin policies to a context

An owner or admin can choose the published policy versions intended for a context. For example, you can pin the eligibility policy for one sale without changing the policy chosen for another sale. Pinning a policy prepares the configuration; evaluate its members through the context assessment endpoint.

Read GET /risk/contexts/{id}/policies to obtain the current revision and policyVersionIds. New contexts start at revision 0 with no pins. Replace the complete set through POST /risk/contexts/{id}/policies, using an owner/admin session, an Idempotency-Key and this body:

{ "expectedRevision": 0, "policyVersionIds": ["11111111-1111-4111-8111-111111111111"], "reason": "Choose the policies intended for this sale" }

You can pin up to 20 published versions, with one version per policy key. The context and policies must belong to your organization and test/live environment. Publishing another version leaves these pins unchanged. Send an empty policyVersionIds list to clear the configuration. Each successful edit advances its revision, including an edit that repeats the same set under a new request key.

A stale expectedRevision returns 409. Read the current configuration and review it before issuing a new edit. Retry an interrupted request with the original key and body: the response contains that request’s committed configuration, even if someone edited the pins afterward. Read the GET endpoint for the current state. Changing the request under the same key returns 409. API keys and workspace members can read pins; only owners and admins can change them.

The SDK exposes risk.contextPolicies and risk.configureContextPolicies. Subscribe to risk.context.policies_configured to learn about edits, then read current state. The callback identifies the context and carries no assessment. Choose the components and their scopes in a composition to combine general and context assessments. Pinning alone does not approve a sale.

Subjects and evidence

Create a subject with a kind and your externalId. The combination is unique within the organization/environment. Use stable customer/account identifiers; do not put names or raw identity documents in the external ID.

Evidence is a typed scalar or a list of scalars:

{ "sourceRegistrationId": "<source-registration-id>", "fact": "monthly_usage_units", "status": "available", "value": 32, "observedAt": "2026-09-27T09:00:00Z", "expiresAt": "2026-10-27T09:00:00Z", "providerRef": "report-123" }

Observation times cannot be in the future. For unavailable or revoked evidence, value must be null. Only an available observation can have a non-null value. Evidence values are limited to strings, finite numbers, booleans and lists of those types; structured provider payloads belong in your evidence storage, referenced by providerRef.

External model signals

A client may submit a model judgment as evidence through its authenticated API key. Mark the corresponding policy input with "evidenceKind": "model_signal" and accept its registered source. An available value for this input is unusable until its evidence record includes modelProvenance:

{ "key": "semantic_signal", "type": "string", "evidenceKind": "model_signal", "acceptedSources": ["registered:<source-registration-id>"], "maxAgeSeconds": 3600 }

The input above is one entry in a policy’s inputs array. The matching evidence submission looks like this:

{ "sourceRegistrationId": "<source-registration-id>", "fact": "semantic_signal", "status": "available", "value": "attention", "observedAt": "2026-09-29T09:00:00Z", "expiresAt": "2026-09-29T10:00:00Z", "providerRef": "case-123", "modelProvenance": { "provider": "example-provider", "model": "example-model-v1", "criteriaVersion": "review-criteria-v1", "inputDigest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "runId": "run-123" } }

inputDigest is a SHA-256 digest of the exact input snapshot held by the producer; Korala stores the digest, not that snapshot. The authenticated producer asserts the model metadata. It does not prove the model ran or that its judgment is correct. Keep the source record under providerRef for a reviewer to inspect. A missing or stale signal, or one from another source, does not satisfy the input. Its provenance is retained in assessment snapshots for audit. For example, a published policy can map attention to a review decision and an investigate_signal action; automatic monitoring then reassesses when the signal changes and sends the normal risk webhook. The client still decides what to do with that action. Korala does not call a model in the background for this integration.

Register an external evidence source and authorize its submitting API keys. Include sourceRegistrationId with each external submission. Korala assigns registered:<source-registration-id> as its source identity, which remains stable when you rotate authorized keys. Native Korala session inputs use the verification sources returned by the input catalog. Read evidence sources for registration, submissions and native session ingestion. A submitted provider name does not establish trust.

New evidence supersedes the latest receipt for the same subject/fact/source. The original record remains. A later receipt with an older observation time still supersedes the previous receipt, so clients must deliberately reconcile late events before submission. Revocation or unavailability never falls back to older favourable evidence. Accepted sources that disagree make an input unresolved. New accepted evidence for a policy input makes its prior assessment stale, even when the submitted value is unchanged. Evidence for an undeclared fact or an unaccepted source leaves that assessment current. Required and supporting inputs both count, including inputs that were missing at assessment time. If a receipt used by the policy becomes unavailable, Korala requires reassessment and refuses to substitute an older value.

Resource limits

Oversized operations return 413. Limits are measured as UTF-8 JSON bytes: 64 KiB for a normalized policy request, 16 KiB for an evidence request, 256 KiB across selected evidence records (including metadata), and 512 KiB for the evaluation result. Full-record reads are capped at 768 KiB. Lists have a 1 MiB budget. These aggregate limits also apply when many small requests have accumulated evidence; a rejected assessment leaves no partial assessment/actions/audit event and does not consume its retry key.

Policies

Create a version with { key, definition }, inspect it, and publish it. Drafts and published definitions are immutable through this API; creating another version under the same key assigns the next version number. Assessments pin an explicit published policyVersionId. Publishing a new version does not silently reevaluate subjects or replace their historical policy.

The definition has these fields:

FieldMeaning
inputsRequired facts, types, accepted sources and maxAgeSeconds
applicabilityOptional groups of conditions that select which subjects the policy covers; a subject must match all conditions in at least one group
factorsNamed factors with ordered condition/point cases, first/highest match, weight and optional default points
aggregationSum or maximum of weighted factor contributions
floor, ceilingBounds applied after aggregation
bandsOrdered IDs and lower bounds, each with an effect
rulesConjunctive conditions with reasons, optional forced band and effects
missingEvidenceawaiting_evidence or review
reviewAfterSecondsAssessment freshness deadline; monitored customers are reassessed when it elapses

Conditions support scalar equality (eq), membership (in), list membership (contains), numeric gt, gte, lt, lte, and comparison with another input (eq_fact, neq_fact). For input comparisons, value names the other input key. Types must agree with the declared input. Rules contain all; use separate rules for alternative conditions. Arbitrary scripts, expressions and network lookups are not allowed.

Factor match: first selects the first matching case. highest takes the highest matched point value once, useful when an account declares multiple access methods. Weights multiply factor points before aggregation. If no case matches and there is no explicit defaultPoints, evaluation is incomplete.

Bands must start at zero and have strictly increasing lower bounds. They use inclusive lower/exclusive upper boundaries; the final band is unbounded. A score is not a probability. Do not compare scores across unrelated policies.

Effects contain a decision (none, review, restrict, reject) and an array of named actions. Decision precedence is reject, restrict, review, none. Forced bands only increase risk. Known mandatory rules still apply when other inputs are missing. An incomplete assessment has a null numeric score. none means this policy does not require a restriction; it is not KYC approval.

All policy limits and required properties are documented in the generated CreateRiskPolicyDto schema. Nested group trees, maintained country-risk tables and general arithmetic expressions are not supported in this version.

Assessments and current decisions

Assessments created before policy-specific freshness was introduced require a new assessment. Their saved results remain available as history. Enabled monitoring schedules a reassessment; clients without monitoring should request one before relying on current state.

Call the assessment endpoint with { policyVersionId, trigger }. The service evaluates persisted evidence and atomically stores its snapshot, explanation, required actions and audit event. Replaying an assessment means using its stored policy, inputs and evaluation time with the recorded evaluator version.

Historical GET always returns the original assessment. Before making a new downstream decision, call its /state endpoint. It reports current: false and effectiveDecision: reassessment_required if newer evidence arrived, a newer assessment exists for the policy key, or a freshness/review deadline passed. Refresh by explicitly creating a new assessment.

Risk changes support signed push notifications through webhooks. Enable automatic reevaluation by assigning a published policy through the monitoring endpoint below. On a notification, fetch current action/assessment state before making a new decision. Do not treat an old saved assessment or an action request as proof of current authorization.

Human decisions and action history

An owner/admin may override a current assessment with decision, a nonempty reason and an expiresAt within one year. The calculated score/band stays unchanged. Incomplete evidence cannot be overridden to none. New evidence invalidates the currentness of the assessment and the applicability of its override. Only the most recent override may apply; revoking or expiring it does not reactivate earlier overrides.

Actions start as requested. Consumers acknowledge them, carry out their own authorized operation, then report completion. Send status, expectedRevision and reason for each transition. Stale revisions return 409.

requested → acknowledged → completed │ │ └──→ failed ←─┘ │ └──→ requested (explicit retry) requested / acknowledged / failed → cancelled (owner/admin only)

Completed and cancelled actions are terminal. A new low-risk assessment does not automatically cancel earlier requirements. Each assessment can produce its own action: reconcile existing open actions for the subject before performing duplicate external work. Acknowledgements are client assertions, not independent proof that a payment system applied a restriction.

events records authenticated actors and reasons for publication, evidence changes, assessments, overrides and action transitions in the same transaction as the change. It is application-level history, not a cryptographically sealed audit log. There are no record deletion endpoints or configurable retention jobs yet; organization deletion cascades its risk data.

TypeScript client

const subject = await client.risk.createSubject( { kind: 'person', externalId: 'customer-123' }, 'customer-123-create', ); const assessment = await client.risk.assess( subject.id, { policyVersionId: publishedPolicyId, trigger: 'onboarding' }, 'customer-123-onboarding-1', ); const state = await client.risk.state(assessment.id);

Use client.risk.inMode('test') for owner/admin JWT sandbox governance and reads. It returns a separate view and leaves client.risk in its default mode. Selecting a contradictory mode with an API key returns 400; the credential continues to determine its environment.

The methods also cover policy publication, evidence ingestion, overrides, action transitions, list and get. Mutation keys are explicit so retries can reuse them. Governance methods need an owner/admin JWT; normal API keys cannot publish a policy or grant themselves override privileges.

Korala verification evidence

Link the verification session to the risk subject and select its fields from GET /risk/verification-inputs when authoring your policy. Korala reads those fields from the linked attempt and retains evidence references for reviewers. Extraction results require an approved attempt or completed, approved session. A newer attempt cannot inherit an earlier approval or favorable result. See evidence sources for source selection and policy authoring for verification bindings.

Customer compliance history

Open Risk → Customers in the dashboard, select live or test, and choose a subject. The profile shows recorded activity and assessment history. Select an event to inspect its authenticated recorder, reported occurrence, receipt time, evidence and linked assessments. Assessment details show the stored inputs and policy, score contributions, rules, required actions and current applicability.

Your integration can record activity from a form, review process or external service without moving that service into Korala:

const event = await client.risk.recordActivity(subject.id, { activityType: 'information.submitted', category: 'customer', title: 'Supporting information submitted', summary: 'The client collected the requested declaration.', occurredAt: new Date().toISOString(), reference: 'your-submission-reference', }, 'submission-record-001'); await client.risk.assess(subject.id, { policyVersionId: publishedPolicy.id, trigger: 'Review submitted information', eventIds: [event.id], }, 'submission-assessment-001');

Activity reports provide context; they do not create evidence or prove that a provider verified a claim. Submit typed facts through addEvidence or a supported adapter before evaluating them. The server records the authenticated principal; category describes the caller’s report, not an authenticated customer identity. One event can inform several assessments, and one assessment can reference up to 50 distinct events from the same subject and environment.

Use client.risk.journey(subject.id) to read up to 50 events in receipt order. Pass the returned nextCursor as the second argument for older events. Use client.risk.eventAssessments(subject.id, event.id) to inspect linked assessments; follow nextOffset for additional results. Both reads respect response byte limits. Use client.risk.list('subjects', { search: 'customer-reference' }) for a literal, case-insensitive search of external IDs.

The corresponding endpoints are:

OperationEndpoint
Record reported activityPOST /risk/subjects/{id}/activities
Read subject timelineGET /risk/subjects/{id}/journey?before={cursor}
Read linked assessmentsGET /risk/subjects/{id}/events/{eventId}/assessments?offset=0

Mutations require an Idempotency-Key. The service refuses event references or cursors belonging to another subject, organization or environment. API keys fix the environment; dashboard JWT clients can use client.risk.inMode('test').

A policy action can request information such as a source-of-funds declaration. Your workflow chooses how to collect it: your own interface, Korala capabilities, an external provider or manual review. Record requests, submissions and review outcomes separately. Completing a collection action does not approve a customer; submit the resulting evidence and request a new assessment. The framework does not automatically create forms or initiate provider requests.

Configure and operate risk in the dashboard

Risk → Policies lists policy versions in the selected test/live environment. Owners and administrators can create a version with evidence inputs, accepted sources, factor cases and weights, score bands, required actions, mandatory rules, aggregation and freshness settings. Save to validate a draft; then review and publish it. Copying a saved version creates a new draft. Saved versions are not edited in place. Integrations pin the published version ID; publication does not automatically migrate customers to it.

Risk → Review queue lists required actions across customers, oldest first. Search a customer reference, filter by policy key or task status, and select a task to inspect its originating assessment. Every status change requires a reason and the current revision. Owners/admins can cancel a task; other allowed transitions remain available to workspace members. This is an action queue: a review decision without a configured action does not create a queue entry. A newer assessment with lower risk leaves existing tasks open.

On the customer page, History type separates reported activity, assessments, evidence, required actions and overrides. Korala filters each history on the server before pagination. Assessment history has its own pagination; selecting an activity shows the assessments linked to that exact event. The original result and current applicability are displayed separately.

In assessment details, reviewers can reassess current evidence using the same policy version. An owner/admin can apply or revoke a time-limited override with a reason. Neither operation edits historical scores. Completing a source-of-funds task is not a substitute for submitting evidence and reevaluating it.

Configure push endpoints in Settings → Webhooks, choosing the Risk event group and the matching environment. See risk push integration.

Automatic reassessment

Assign one published version per customer and policy key. Publishing a new version leaves existing assignments unchanged. The customer page provides the same monitor, pause and resume controls as the API.

await korala.risk.configureMonitoring(subjectId, { policyVersionId, enabled: true, }, crypto.randomUUID()); const subscriptions = await korala.risk.monitoring(subjectId);

For a sale or another journey, configure context monitoring for that participant and policy. General and context subscriptions have separate settings.

Use POST /risk/subjects/:id/monitoring with an idempotency key and GET /risk/subjects/:id/monitoring to inspect assignments. To pause, submit the same version with enabled: false. Assigning another published version with the same policy key replaces the monitored version.

Korala processes automatic reassessments in the background and prioritizes changed subjects. Known evidence expiry, derived age changes and policy review deadlines take priority over background reconciliation. Unchanged subscriptions are eligible for reconciliation after five minutes to catch definition changes and missed updates; this interval is not a delivery guarantee. Processing backlogs and service interruptions increase latency. It reassesses after evidence changes, native verification changes, evidence expiry and reviewAfterSeconds. Korala reuses the assessment while its accepted evidence, input coverage and applicability remain unchanged, until the policy review deadline. An unrelated fact or unaccepted source update does not create another assessment. Expiry of supporting evidence still triggers a refresh of its coverage. Activity-only events do not trigger evaluation.

Known mandatory rules run with partial evidence: accepted age 15 can produce decision: reject, status: incomplete and score: null while address evidence is missing. The final numeric score requires all configured inputs. Missing or expired evidence cannot produce an unrestricted complete result.

If a policy’s applicability conditions are missing or do not match, monitoring records applicability_unknown or applicability_not_matched and produces no assessment. Inspect lastError, lastEvaluatedAt and nextCheckAt; the latter is an eligibility time, not a delivery guarantee. evaluation_failed initially retries after 30 seconds; repeated failures back off to 60, 120, 240 and then 300 seconds. Changes received during backoff remain queued. A successful check or explicit subscription reconfiguration resets the backoff. After five consecutive failures, retries use background reconciliation so an unhealthy subscription does not continually take priority; its last error remains visible. Service interruptions can delay retries.

Korala records the assessment, required actions and pending notifications together. Repeating the same background evaluation does not duplicate the assessment. A later assessment can request the same action again; consumers must reconcile existing requirements. Webhooks still have at-least-once delivery.

Continue checking current assessment state and enforcing freshness deadlines before authorizing a consequential action. Pausing monitoring does not revoke existing assessments or cancel actions. Overrides retain their own expiry; an expired override alone does not trigger an assessment or notification.

Accepting KYC before the whole session finishes

Native input bindings normally use the completed, approved linked session. An owner/admin may explicitly review a completed workflow attempt while another workflow, such as proof of address, is pending:

POST /risk/subjects/:id/verification-decisions Idempotency-Key: unique-review-command { "sessionWorkflowId": "<linked-workflow-slot-id>", "workflowRunId": "<current-completed-run-id>", "decision": "approved", "reason": "Reviewer accepted this verification attempt" }

Supported decisions are approved, rejected and revoked. This endpoint requires an owner/admin dashboard JWT. API credentials cannot impersonate a Korala verification reviewer; external providers submit evidence through their own authenticated source instead.

The decision belongs to the persisted customer, session workflow and exact run. It does not approve the overall session. A newer attempt cannot inherit it; revocation does not resurrect an earlier approval. Processing completion alone is insufficient. The native adapter still checks workflow version, tenant, mode, output provenance and freshness. An adverse or expired session prevents use of favorable native facts. Each decision appears in the customer’s audit history.

Last updated on