Combine general and journey policies

Use a composition when one decision needs more than one policy. For example, Alice has a general verification policy and joins two sales. You can reuse her current general assessment in both sales while checking consent for each sale separately.

You choose the published policy versions and the scope of each component. Korala combines their current assessments and returns risk, eligibility and an explanation. Your application decides what to do with that result.

Choose what each policy covers

A context policy can read both general evidence and evidence specific to that context. Set scope: "current_context" on an input that belongs to the journey; an input without a scope reads general evidence. The component scope selects which assessment to combine, while the input scope selects which evidence the policy evaluates.

For example, a sale policy can read Alice’s general residence country and her consent to that sale. Declare the residence field as general and the consent field as current_context. Use verified residence evidence for a residence requirement, rather than the issuing country of an ID or an IP location.

Use native verification and document reuse inputs in a subject component. Context components currently support submitted facts; Korala refuses a native verification or derived reuse policy in that frame. Put shared checks in the general policy and the journey conditions in the context policy.

Set up a composition

1. Publish the general policy and the journey policy. Include explicit eligibility criteria when your application needs to determine participation.
2. Create the journey context, attach the subject, and pin the published journey policy through the context configuration.
3. Register a source that can submit the required general and context facts. Give it the applicable context kinds and API-key bindings. See evidence sources.
4. Submit the evidence and evaluate the general policy and the context policy.
5. Create a composition with an owner/admin session, then read the combined state with your integration credentials.

Create a composition through POST /api/v1/risk/compositions. Send an Idempotency-Key and the published policy IDs:

{
  "key": "general_and_sale",
  "components": [
    {
      "policyVersionId": "11111111-1111-4111-8111-111111111111",
      "scope": "subject"
    },
    {
      "policyVersionId": "22222222-2222-4222-8222-222222222222",
      "scope": "current_context"
    }
  ]
}

A composition supports 1–20 components, with one version per policy key. All policies must belong to your organization and the same test/live environment. Korala returns the composition’s id, key, version and pinned components. Save the returned ID in your integration.

Retry creation with the same key and components if you lose the response. Reordering components leaves the intent unchanged; changing a component or the composition key under the same request key returns 409. To change the policies or their scopes, create a new composition version with a new request key. Publishing another policy version does not upgrade an existing composition.

Read the result

Read a combined context decision through:

GET /api/v1/risk/contexts/{contextId}/subjects/{subjectId}/compositions/{compositionVersionId}

The subject must belong to that context. Pin each current_context component policy to the requested context. Korala refuses inaccessible resources and policies that are missing from the context configuration.

The TypeScript SDK exposes the same read:

const state = await client.risk.contextCompositionState(
  saleId,
  subjectId,
  compositionVersionId,
);
 
if (state.result.clearance) {
  // Apply your application's participation controls.
} else {
  // Present the component explanations for review or further evidence.
}

A general policy with no eligibility criteria contributes its risk findings without imposing an extra participation condition. At least one applicable policy must establish explicit eligibility for clearance. A reviewer clearing risk does not change a failed participation criterion or repair stale evidence.

Reading combined state does not evaluate a policy, create an assessment or save another combined result. Evaluate the leaf policies through their assessment endpoints. Enable monitoring for the general policy and each context policy to schedule reassessment when their inputs change. An identical assessment-command retry returns its original result. The combined-state GET uses the current state, so it can differ after a correction or expiry.

For a composition containing only subject components, use GET /api/v1/risk/subjects/{subjectId}/compositions/{compositionVersionId} or client.risk.compositionState(subjectId, compositionVersionId). Korala refuses that general read when the composition requires a context. Read the pinned configuration through GET /api/v1/risk/compositions/{compositionVersionId} or client.risk.composition(compositionVersionId).

Keep a context’s checks up to date

Alice participates in Sale A and Sale B. You can enable automatic reassessment for her Sale A policy without changing her Sale B or general account settings:

await client.risk.configureContextMonitoring(
  saleAContextId,
  aliceSubjectId,
  {
    policyVersionId: saleAPolicyVersionId,
    enabled: true,
  },
  'alice-sale-a-monitoring',
);

Pin the published policy to Sale A and add Alice as a participant first. When you correct Alice’s Sale A evidence, Korala schedules a new Sale A assessment. A policy can also use general account evidence: a correction to that evidence schedules the subscribed checks that use it.

Use the same idempotency key when you retry the same request. Choose a new key when you change the policy, context or enabled setting. Reusing the original key for changed input returns 409.

const page = await client.risk.contextMonitoring(saleAContextId, aliceSubjectId);
 
for (const setting of page.items) {
  console.log(setting.policyKey, setting.enabled, setting.lastEvaluatedAt);
}
 
if (page.nextOffset !== null) {
  const next = await client.risk.contextMonitoring(
    saleAContextId,
    aliceSubjectId,
    page.nextOffset,
  );
}

This lists settings and check timing. Read the participant’s assessment or composition state to decide whether your application can proceed. Check its currentness and effective decision; enabling monitoring does not approve Alice.

To pause a subscription, submit the same policy with enabled: false and a new idempotency key. Pausing keeps the assessment history and stops automatic reassessment for that subscription.

The HTTP routes are:

• POST /api/v1/risk/contexts/{contextId}/subjects/{subjectId}/monitoring
• GET /api/v1/risk/contexts/{contextId}/subjects/{subjectId}/monitoring?offset=0

Two sales, one person

Suppose Alice’s general policy reports no adverse risk and both sales require consent. Sale A has valid consent; Sale B records that she declined.

Check the component states to see which policy needs attention. Keep the original assessment IDs for your audit trail; a correction creates a later assessment rather than editing the original explanation.