Sessions

Sessions orchestrate multiple workflows into a single verification or onboarding case. Use sessions when you need to collect and verify multiple documents sequentially, attach related participants to the same case, or combine document workflows with review and provider-backed checks.

Key Concepts

Session configurations: Reusable blueprints that define which workflows, bindings, verification settings, and defaults a session uses.
Sequential execution: Workflows run in order. The user must complete workflow 1 before starting workflow 2.
Participants: Sessions can include a subject plus related parties such as beneficial owners, controllers, directors, or representatives.
Cross-workflow data flow: Output from earlier workflows is available as input to later ones (e.g., validate POA name matches ID name).
Checks and risk: Sessions can include provider-backed check workflows and native risk scoring before final resolution.
Resolution: Sessions can be auto-resolved (approved/rejected) based on validation results, or manually resolved by a partner.
End-user access: Each session gets a unique access token that your frontend can turn into the collection URL for end-users.

Session Configurations

Before creating sessions, set up a configuration that defines the session blueprint. Configurations are org-scoped and reusable.


import { KoralaClient } from '@korala/api-client';
 
const korala = new KoralaClient({
  apiKeyId: 'your-api-key-id',
  apiSecret: 'your-api-secret',
});
 
// Create a configuration
const config = await korala.sessions.createConfiguration({
  name: 'KYB Standard',
  slug: 'kyb-standard',
  description: 'Business onboarding with participant-aware verification',
  workflowBindings: [
    {
      workflowSlug: 'id-document',
      participantRoles: ['representative'],
      outputKey: 'representative_id',
    },
    {
      workflowSlug: 'proof-of-address',
      participantRoles: ['representative'],
      outputKey: 'representative_poa',
    },
    {
      workflowSlug: 'pep-check',
      participantRoles: ['beneficial_owner'],
      outputKey: 'ubo_pep_check',
    },
  ],
  subjectKind: 'business',
  isVerification: true,
  autoResolve: false,
  finalManualReviewRequired: true,
  defaultExpiresInMinutes: 1440,
  defaultRedirectUrl: 'https://yourapp.com/verification/complete',
});

Configuration Options

Option	Type	Default	Description
`name`	string	required	Display name
`slug`	string	required	URL-safe identifier (unique per org)
`workflowSlugs`	string[]	—	Ordered list of workflow slugs for simple sequential sessions
`workflowBindings`	object[]	—	Participant-aware workflow definitions with per-step context and output keys
`subjectKind`	`individual \	business`	`individual`
`isVerification`	boolean	`true`	Enable resolution (approved/rejected)
`autoResolve`	boolean	`true`	Auto-resolve based on validation results
`finalManualReviewRequired`	boolean	`false`	Force partner review before final resolution
`defaultExpiresInMinutes`	number	`1440`	Default session expiration
`defaultRedirectUrl`	string	—	Default redirect after completion

Managing Configurations


// List all configurations
const configs = await korala.sessions.listConfigurations();
 
// Get a specific configuration
const config = await korala.sessions.getConfiguration('kyc-standard');
 
// Update a configuration
await korala.sessions.updateConfiguration('kyc-standard', {
  defaultExpiresInMinutes: 2880,
});
 
// Delete a configuration
await korala.sessions.deleteConfiguration('kyc-standard');

Creating a Session

Sessions are always created from a configuration:


const session = await korala.sessions.create({
  externalUserId: 'org_abc123',
  configurationSlug: 'kyb-standard',
  participants: [
    { role: 'subject', displayName: 'Acme Corp' },
    { role: 'beneficial_owner', displayName: 'Jane Smith' },
    { role: 'representative', displayName: 'John Smith' },
  ],
  context: {
    partnerName: 'Acme Corp',
    applicationType: 'merchant_onboarding',
  },
  metadata: {
    applicationId: 'app_001',
  },
  // Override config defaults if needed
  expiresInMinutes: 720,
  redirectUrl: 'https://yourapp.com/custom-redirect',
});
 
// Share the access URL with the end-user
const accessUrl = `https://yourapp.korala.ai/v/${session.accessToken}`;

Use the session detail endpoint when you need full case state, including participants, workflow instances, checks, and risk summaries.

Session Lifecycle


created → in_progress → completed (+ auto-resolve)
                      → pending_review → completed
                      → expired
                      → failed

Status	Description
`created`	Session created, user hasn’t started yet
`in_progress`	User is actively completing workflows
`pending_review`	A workflow is paused for human review
`completed`	All workflows finished successfully
`expired`	Session expired before completion
`failed`	A workflow failed with no retries remaining

Resolution

When all workflows complete, the session may auto-resolve if enabled in the configuration and nothing requires manual review:

Approved: All workflows passed validation
Rejected: One or more workflows failed validation

For KYB or other review-heavy flows, the session can move into pending_review until a partner makes the final decision.

Partners can override the resolution at any time:


await korala.sessions.resolve(sessionId, {
  resolution: 'approved',
  reason: 'Manually verified after review',
});

Listing Sessions


const sessions = await korala.sessions.list({
  externalUserId: 'usr_abc123',
  status: 'completed',
  page: 1,
  limit: 10,
});

Session Webhooks

Subscribe to these events in your webhook configuration:

Event	Description
`session_completed`	All workflows in the session finished
`session_expired`	Session expired before completion
`session_failed`	Session failed (no retries remaining)
`session_resolved`	Resolution set (auto or manual)
`session_workflow_completed`	Individual workflow within session completed
`session_workflow_failed`	Individual workflow within session failed

Resubmission

If a workflow fails or needs to be redone, request resubmission:


await korala.sessions.resubmit(sessionId, sessionWorkflowId);

This resets the workflow and all subsequent workflows (since their input data may be invalidated).

If downstream checks or risk summaries depended on the resubmitted workflow, those results are cleared and recomputed from the updated evidence.