Dashboard Sign InKR
These docs are for v1.0. Click to read the latest docs for v3.0.

Callback

Function that delivers the analyzed results by calling the desired HTTP callback URL, if the parameter is entered in the upload and session end API at Session API, the analysis results will be delivered in the following format

1. Request

1.1 Method

POST

1.2 Header

FieldTypeDescription
x-api-keyStringAPI key used to upload data or end session
x-user-idStringThe user id that created the sleep session

1.3 Body

Field

Type

Description

callback_event

String (INFERENCE_COMPLETE,SESSION_COMPLETE)

Callback event type
INFERENCE_COMPLETE: If the analysis is completed within 5 or 20 minute increments
SESSION_COMPLETE: The entire session analysis is complete

callback_data

Callback Data Object

Callback data

1.3.1 Callback Data Object in case of INFERENCE_COMPLETE

Field

Type

Description

user_id

String

user id

session_id

String

session id

seq_num

Int

Order number of the audio data uploaded

inference_seq_num

Int

Number that converted seq_num into 5 minutes increments
e.g.) when uploading MELSPECTROGRAM, if seq_num 39, inference_seq_num is 3

stage_list

[Int]

Sleep stage results in previous 20 minutes frame
e.g.) if inference_seq_num is 6, you get back 40 values from 3 to 6

osa_stage_list

[Int]

Sleep apnea stage results in previous 20 minutes frame
e.g.) if inference_seq_num is 6, you get back 40 values from 3 to 6

1.3.2 Callback Data Object in case of SESSION_COMPLETE

FieldTypeDescription
user_idStringuser id
session_idStringsession id
sleep_dataSleep Data ObjectFull Sleep Analysis Results

1.3.3 Sleep Data Object

For a more detailed description of metrics, see Get Single Session. The nullable of the object and the internal components of objects are determined depending on the session status and the terms of the agreement.

  • whenif state == COMPLETE
    • if 2-stage sleep analysis is used: there only is 'wake' and 'sleep' stages, so time_in_rem, time_in_light, time_in_deep, rem_ratio, light_ratio, deep_ratio value will return null
    • if sleep apnea feature is not used: this feature will not be supported so, time_in_stable_breath, time_in_unstable_breath, stable_breath_ratio, unstable_breath_ratio, breathing_pattern, estimated_ahi value will return null
    • if all stages are 'wake'(never slept session): the user have not slept so, sleep_latency, sleep_time, wakeup_latency, wake_time, wake_ratio, sleep_ratio, rem_ratio, light_ratio, deep_ratio, stable_breath_ratio, unstable_breath_ratio, breathing_pattern, estimated_ahi will all return null
    • INVALID session (lasting less than 20 minutes or unanalyzable session): all nullable field values as null

Field

Type

Description

session_id

String

session id

state

String (only COMPLETE available)

Session status
COMPLETE: all sleep analysis is completed after the session end

session_start_time

String (YYYY-MM-DDThh:mm:ss+-hh:mm)

When sleep measurement began
e.g.) 2022-08-01T01:31:17+09:00 (If the requested timezone is Asia/Seoul)

session_end_time

String (YYYY-MM-DDThh:mm:ss+-hh:mm)

When the sleep measurement ended
e.g.) 2022-08-01T01:31:17+09:00 (if the requested timezone is Asia/Seoul)

sleep_stages

[Sleep Stages]

List of sleep stages

osa_stages

[OSA Stages]

List of sleep apnea stages

sleep_efficiency

float (Second decimal place of 0~1 Range)

The percentage of time you actually slept during sleep measurement

sleep_latency

int (seconds)?

The time it takes to fall asleep after the start of sleep measurement

sleep_time

String (YYYY-MM-DDThh:mm:ss+-hh:mm)?

The time you started falling asleep

wakeup_latency

int (seconds)?

The time it takes to wake up and end your sleep measurement

wake_time

String (YYYY-MM-DDThh:mm:ss+-hh:mm)?

The time you woke up

time_in_wake

int (seconds)

Time woken up in the middle of sleep

time_in_sleep_period

int (seconds)

During sleep measurement time, excluding the time it took from the start of the sleep measurement to fall asleep and the time it took from the wake to the end of the sleep measurement
(time_in_bed - sleep_latency - wakeup_latency)

time_in_sleep

int (seconds)

During sleep measurement time, the time you were actually sleeping is divided into three stages: deep, light, and rem

time_in_bed

int (seconds)

The time from the start of the sleep measurement to the end of the sleep measurement

time_in_rem

int (seconds)?

Total time the sleep stage progressed to REM

time_in_light

int (seconds)?

Total time the sleep stage progressed to Light

time_in_deep

int (seconds)?

Total time the sleep stage progressed to Deep

time_in_stable_breath

int (seconds)?

Total time in the breathing stable section

time_in_unstable_breath

int (seconds)?

Total time of breath instability

wake_ratio

float (Second decimal place of 0~1 Range)?

Rate of wake in the middle during sleep stage

sleep_ratio

float (Second decimal place of 0~1 Range)?

The percentage of time you sleep without waking up during the sleep stage

rem_ratio

float (Second decimal place of 0~1 Range)?

Rate of REM sleep during sleep stage

light_ratio

float (Second decimal place of 0~1 Range)?

Rate of Light sleep during sleep stage

deep_ratio

float (Second decimal place of 0~1 Range)?

Rate of deep sleep during sleep stage

stable_breath_ratio

float (Second decimal place of 0~1 Range)?

The percentage of time that was a breathing stable section during the sleep stage

unstable_breath_ratio

float (Second decimal place of 0~1 Range)?

The percentage of time during the sleep stage that there was a breathing instability section

breathing_pattern

String (VERY_STABLE,STABLE,UNSTABLE,VERY_UNSTABLE)?

Stages of respiratory instability

VERY_STABLE: Very stable
STABLE: Stable
UNSTABLE: Unstable
VERY_UNSTABLE: Very Unstable

estimated_ahi

float (Second decimal place of 0~1 Range)?

Values for determining respiratory instability levels