Sessions

Create a new session

post/api/v1/sessions

Request

  • Base URL: https://api.korala.ai
  • URL: https://api.korala.ai/api/v1/sessions
  • Auth: one of:
    • API key in header X-API-Key
    • bearer (a scheme the document does not define)

Headers

X-Korala-Mode'live' | 'test'

Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.

Request body

originContextIdstring

Registered risk context that initiated this session. Requires subjectId and context membership. Origin does not restrict evidence reuse or enable context evaluation.

subjectIdstring

Korala risk subject ID. Must match externalUserId, customer type, organization and environment.

externalUserIdstring required

Partner's user identifier

configurationSlugstring required

Slug of the session configuration to use

contextobject

Session-level context data available to all workflows (e.g., user profile data)

metadataobject

Arbitrary metadata attached to the session

expiresInMinutesnumber

Session expiration in minutes from creation (default: 1440 = 24h)

redirectUrlstring

URL to redirect the user after session completion

Example request

{
  "externalUserId": "usr_abc123",
  "configurationSlug": "kyc-standard",
  "expiresInMinutes": 1440,
  "redirectUrl": "https://partner.com/verification/complete"
}

Response

originContextIdstring nullable

Registered originating risk context; null when none was linked. This association does not determine evidence applicability.

subjectIdstring nullable

Explicitly linked Korala risk subject ID; null for unlinked sessions.

sandboxboolean required

Persisted execution mode: true for test data

idstring required
organizationIdstring required
externalUserIdstring required
subjectKind'individual' | 'business' required
finalManualReviewRequiredboolean required
accessTokenstring required

Access token for end-user access

status'created' | 'in_progress' | 'pending_review' | 'completed' | 'expired' | 'failed' required
resolution'approved' | 'rejected'
resolutionReasonstring nullable
resolvedAtstring date-time nullable
resolvedBystring nullable
riskScorenumber nullable
riskLevel'low' | 'medium' | 'high'
eventVersionnumber required

Grows with each change announced by a session webhook; compare it with the webhook's data.version. The higher number is the newer state; numbers may skip.

metadataobject nullable
contextobject nullable
accumulatedDataobject nullable
expiresAtstring date-time nullable
redirectUrlstring nullable
startedAtstring date-time nullable
completedAtstring date-time nullable
createdAtstring date-time required
updatedAtstring date-time required

Example response

{
  "decision": {
    "rulesVersion": "korala-decisions-v3",
    "reasonCodesVersion": "korala-reasons-v1"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.