SSC+ API reference

API version 0.1.0 · Preview

Overview

The SSC+ API. SSC+ is developed by JST Healthcare Solutions Oy.

Preview. This version is for building and testing integrations against the development environment. It may still change in ways that are not backwards compatible; changes are announced in the integration guide's change log. It is not for real patients.

Two kinds of credentials

• Tenant API key: for the Customer API (/v1/sessions), called from your own servers. Sent as Authorization: Bearer ssc_…. Issued by SSC, shown once. Never put it in a browser, an app or a phone flow.
• Session token: for the Session API (/v1/session), used by SSC's own patient clients, such as the Form in your page. Issued per session when the session is created, short-lived, and scoped to that one session.

The Session API answers browsers on any web page (CORS), so the Form can run in yours; give origin when creating the session to bind its token to your page. The Customer API does not answer browsers at all.

Errors

Every error is an RFC 9457 problem detail (application/problem+json). Branch on its code, which is stable; title and detail are for people. Quote the request_id when you ask about one. Authentication failures all look the same, by design.

Retries

Creating a session requires an Idempotency-Key header. Retrying with the same key and the same body returns the original session instead of creating a second one, for 24 hours.

Base URL

• https://api.dev.ssc-plus.com: Development (preview)

Authentication

• Tenant API key (tenantKey): Authorization: Bearer …. Your key, ssc_…, from your servers only.

Operations

Create a triage session

POST /v1/sessions

Credential: Tenant API key.

Create a session for a Form or Talk triage, and get the token its patient client uses.

Call it from your server, then hand session_token.token to the patient's browser. The tenant API key stays on your server.

Idempotency-Key is required. A retry with the same key and body returns the session the first request created, with 200 rather than 201, for 24 hours. Reusing a key with a different body is refused with 409.

Give pre_information when you already know something about the patient, such as from a pre-questionnaire. The patient is then asked only for what is missing.

Line sessions are not created here: a call creates its own session when your Audio Connector connects.

Parameter	In	Description
Idempotency-Key	header	Required. A unique value per session you intend to create, such as a UUID.

Request body: CreateSession.

Status	Meaning	Body
201	The session was created.	CreatedSession
200	A retry: the session an earlier request with the same Idempotency-Key created.	CreatedSession
400	No Idempotency-Key header (code: idempotency_key_required)	ProblemDetail
401	Missing, unknown or revoked tenant API key (code: unauthorized)	ProblemDetail
409	The Idempotency-Key was used with a different body (code: idempotency_conflict)	ProblemDetail
422	The request did not match what this operation accepts, or a symptom term is not in the vocabulary (code: invalid_request or unknown_symptom_term)	ProblemDetail

Retrieve a session and its result

GET /v1/sessions/{session_id}

Credential: Tenant API key.

Read a session: where it is, and its result once it has completed.

For Line, use the ssc_session_id the call returned to your call flow. result is present when status is completed. A session is readable for 30 days after it ends.

Only your own tenant's sessions can be read. Any other id is 404.

Parameter	In	Description
session_id	path	The session's id. For Line, the call's ssc_session_id.

Status	Meaning	Body
200	The session.	SessionView
401	Missing, unknown or revoked tenant API key (code: unauthorized)	ProblemDetail
404	No session with this id belongs to your tenant (code: session_not_found)	ProblemDetail
422	The request did not match what this operation accepts (code: invalid_request)	ProblemDetail

Check the API is up

GET /v1/health

Credential: none.

Answers ok while the API is serving. Needs no credentials.

Status	Meaning	Body
200	The API is up.	Health

Schemas

CancellationReason

Why a session ended without a result.

• abandoned: the patient left before finishing.
• expired: nothing happened for too long.
• failed: SSC could not continue.

Values: abandoned, expired, failed.

CareCode

A classification code, with the system that defines it.

Field	Type	Required	Description
system	string	yes	The code system. Example: "ICPC", "SNOMED".
code	string	yes	Example: "A98".
name	string or null	no	Example: "Terveyden ylläpito".

Channel

How the patient is triaged: web_form, voice_web, voice_tel or web_chat.

Fixed for the session.

Values: web_form, voice_web, voice_tel, web_chat.

CreateSession

A request to create a session.

Field	Type	Required	Description
channel	Channel	yes	How the patient is triaged: web_form (the Form, in a browser), voice_web (Talk, spoken in a browser), web_chat (Chat, written in a browser; in development) or voice_tel (Line, a phone call). Line sessions are created by the call itself, not with this operation. Example: "web_form".
customer_reference	string or null	no	Your own identifier for this session, returned with it. Do not put personal data here. At most 200 characters. Example: "visit-2026-0931".
patient_phone	string or null	no	The patient's phone number, when you want the session linked to it. At most 32 characters. Example: "+358401234567".
origin	string or null	no	The web page origin the patient's browser will use. When given, the session token works only from that origin. At most 200 characters. Example: "https://www.example-clinic.fi".
pre_information	PreInformationIn or null	no	What you already know about the patient, if anything.

CreatedSession

A newly created session, with the token for the patient's client.

Field	Type	Required	Description
id	string (uuid)	yes	The session's identifier. For Line, this is ssc_session_id.
channel	Channel	yes	How the patient is triaged: web_form (the Form, in a browser), voice_web (Talk, spoken in a browser), web_chat (Chat, written in a browser; in development) or voice_tel (Line, a phone call). Line sessions are created by the call itself, not with this operation.
status	SessionStatus	yes
cancellation_reason	CancellationReason or null	no	Set when status is cancelled.
customer_reference	string or null	no	Your identifier for the session. For Line, the Genesys conversation ID of the call.
created_at	string (date-time)	yes
updated_at	string (date-time)	yes
result	Result or null	no	Present once status is completed.
session_token	SessionToken	yes

FieldError

One problem with one part of a request.

Field	Type	Required	Description
location	string	yes	Where in the request: body, path, query or header, then the field, for example body.channel. Example: "body.channel".
message	string	yes	What is wrong with it.

Health

Whether the API is up.

Field	Type	Required	Description
status	string	no	Present and serving.

PatientSex

The patient's sex as the assessment uses it. other and unknown are distinct.

Values: female, male, other, unknown.

PreInformationIn

What you already know about the patient, from a pre-questionnaire or a patient system.

Every field is optional; give what you have. The patient is asked only for what is missing. Give what is wrong either as symptom_terms, exact terms from SSC's symptom vocabulary, or as complaint, the patient's own words, which SSC maps to terms and confirms with the patient.

Field	Type	Required	Description
age	integer or null	no	Example: 45.
age_unit	string	no	years, or months or days for infants.
sex	PatientSex or null	no
language	string or null	no	fi in the preview. At most 8 characters.
symptom_terms	list of string	no	Exact terms from the symptom vocabulary. An unknown term is refused with 422, code unknown_symptom_term. Example: ["kuume", "nuha"].
complaint	string or null	no	What is wrong, in the patient's own words. Personal identifiers are removed before it is stored. At most 2000 characters. Example: "Kuumetta ja nuhaa eilisestä asti.".

ProblemDetail

An error, as described by RFC 9457 (application/problem+json).

Branch on code, which is stable; title and detail are for people and their wording may change.

Field	Type	Required	Description
type	string	no	URI identifying the problem type. Example: "/problems/not-found".
title	string	yes	Short, human-readable summary of the problem type.
status	integer	yes	HTTP status code.
detail	string or null	no	Explanation specific to this occurrence.
instance	string or null	no	URI identifying this specific occurrence.
code	string or null	no	Stable machine-readable code. Safe to branch on; unlike title, its wording does not change.
request_id	string or null	no	Identifies this request in SSC's logs. Quote it when asking about an error.
errors	list of FieldError or null	no	For invalid_request: each part of the request that was wrong.

Recommendation

One care recommendation, with the findings it rests on and the plan it leads to.

Field	Type	Required	Description
urgency	string	yes	How soon, and where, the patient should be seen, in the engine's words. Example: "Vastaanotto 1-3 vrk".
reason	string or null	no	The findings this recommendation rests on.
plan	string or null	no	What is advised as a result.

Result

The outcome of a completed triage, written for the professional who sees the patient.

Everything the engine concluded that is safe to share: recommendations, classification, the summary of what the patient reported, codes, and alarming findings. How the engine scored it is not included.

Field	Type	Required	Description
recommendations	list of Recommendation	no	Most significant first.
triage_code	integer or null	no	The engine's numeric triage classification.
guidance	string or null	no	Guidance for the patient, including any emergency instruction. Present whenever the engine gave some; show it.
remotely_treatable	boolean	no	Whether the engine considers remote care suitable.
professional_groups	list of string	no	Who should see the patient. Example: ["Yleislääkäri"].
summary	string or null	no	What the patient reported, as a summary for the professional.
self_care	SelfCare or null	no	Self-care advice, when the engine gave some.
codes	list of CareCode	no
severe_symptoms	list of string	no	Alarming findings, as phrases.

SelfCare

Self-care advice for the patient, point by point, with its sources.

Field	Type	Required	Description
title	string or null	no	Example: "Itsehoito-ohjeita".
introduction	string or null	no
instructions	list of string	no	The advice, one point per item.
sources	list of Source	no

SessionStatus

Where a session is.

• in_progress: created, and the patient has not finished.
• completed: finished with a result.
• cancelled: ended without a result; cancellation_reason says why.

Values: in_progress, completed, cancelled.

SessionToken

The token the patient's client uses to join the session.

Field	Type	Required	Description
token	string	yes	Hand this to the patient's client. It is not a tenant credential.
expires_at	string (date-time)	yes	When the token stops working.

SessionView

A session and, once it has one, its result.

Field	Type	Required	Description
id	string (uuid)	yes	The session's identifier. For Line, this is ssc_session_id.
channel	Channel	yes	How the patient is triaged: web_form (the Form, in a browser), voice_web (Talk, spoken in a browser), web_chat (Chat, written in a browser; in development) or voice_tel (Line, a phone call). Line sessions are created by the call itself, not with this operation.
status	SessionStatus	yes
cancellation_reason	CancellationReason or null	no	Set when status is cancelled.
customer_reference	string or null	no	Your identifier for the session. For Line, the Genesys conversation ID of the call.
created_at	string (date-time)	yes
updated_at	string (date-time)	yes
result	Result or null	no	Present once status is completed.

Source

Where a piece of advice comes from.

Field	Type	Required	Description
title	string	yes
url	string or null	no

---

SSC+ is developed by JST Healthcare Solutions Oy. API version 0.1.0.