API

Quick Start Guide for the Immersion API

August 2021

© 2021 Immersion Neuroscience Inc. All Rights Reserved. Confidential.

 Immersion API
Integrate simple collection & Immersion scores into your application

• There are 2 steps to building a simple Immersion app:

• Collect data: using a sensor device of your choosing, capture real-time

heart rate data and send to the Immersion API servers every second.

• Get Results: Query the Immersion API servers as often as needed to get
immersion and psychological safety scores for any time interval.

• Immersion uses a basic JSON and REST API that should be simple to
integrate into any application.

© 2021 Immersion Neuroscience Inc. All Rights Reserved. Confidential.

 Immersion API
Authentication is handled in HTTPS headers

• Authentication is handled with a standard “Authorization” header and Bearer

token.

• This token is unique to your account and must be safe guarded by your
developers and not shared.

• Unauthorized use of your token through negligence or misuse will result in

the API being disabled for your account.

• Your Authorization Token and Base URL will be provided by Immersion

during your Api Onboarding cal

© 2021 Immersion Neuroscience Inc. All Rights Reserved. Confidential.

 Immersion API
Identi ers are important

• When you send cardiac data to the Immersion API, you will include an
identi er that represents the person being measured from your system.

• This identi er must be unique to each person and should include a reference
to your company.

• Example: “mycompany-98765-1234”

• Identi ers MUST be lowercase and never include unicode, or spaces

• This identi er will be used to send data, and query for results on an individual
level.

© 2021 Immersion Neuroscience Inc. All Rights Reserved. Confidential.

fi
fi
fi
fi
fi
 Individual Measurements

© 2021 Immersion Neuroscience Inc. All Rights Reserved. Confidential.

 Submitting Cardiac Data
Send heart data to Immersion for real-time processing

ACTION PUT

URL https://{base_url}/device-ingestion/v2/devices/measurements/{identifier}

HEADERS Accept: application/json

Authorization: {auth_token}

PATH ARGUMENTS {base-url} : This was provided to you during API Onboarding
{identifier} : A unique 10-100 character string that you can use to identify this
individual. This must be unique to you and must be lowercase.
Example: mycompany-123456789
Do not include spaces, unicode, or high ascii characters.

QUERY STRING Not Applicable

© 2021 Immersion Neuroscience Inc. All Rights Reserved. Confidential.

 Submitting Cardiac Data

Send heart data to Immersion for real-time processing
{ • ALL FIELDS ARE REQUIRED
BODY "identifier": "scott1234", • Identi er MUST match the identi er in the URL path
"device_type": "AW", • Identi er must be a string
"measurements": [ • Device_Type is a 2 character string that represents the type of device being used to collect
{
cardiac data.
"time_stamp": 1639146802,
"heart_rate": 75 • Measurements is an array of time stamped heart rate data
} • You MUST include at least one object in the measurement array.
] • You MAY include up to 1,000 measurement in a single PUT
} • Timestamp is a 10 digit epoch time stamp representing the number of seconds since Jan 1,
1970.
• Timestamp MUST be seconds and NOT milliseconds.
• Heart_rate is the current Beats per Minute as reported by the individuals sensor

RESULT HTTP 200 and “Success”or “Failure” as a string

© 2021 Immersion Neuroscience Inc. All Rights Reserved. Confidential.

fi
fi

fi

 Immersion Results
Real-time Immersion score results

ACTION GET

URL https://{base_url}/index/v2/index/immersion/{identifier}?from_epoch={timestamp}&to_epoch={timestamp}

HEADERS Accept: application/json

Authorization: {auth_token}

PATH ARGUMENTS {base-url} : This was provided to you during API Onboarding
{identifier} : A unique 10-100 character string that you can use to identify this
individual. This must be unique to you and must be lowercase.
Example: mycompany-123456789
Do not include spaces, unicode, or high ascii characters.

© 2021 Immersion Neuroscience Inc. All Rights Reserved. Confidential.

 Immersion Results
Real-time Immersion score results
?from_epoch={timestamp} • ALL FIELDS ARE REQUIRED
QUERY STRING &to_epoch={timestamp} • from_epoch is a 10 digit timestamp that represent when you would like to begin calculation
• to_epoch is a 10 digit timestamp that represent when you would like to end calculation
• Immersion will calculate the Immersion score for the period of time between the
from_epoch and to_epoch
• You may make this time interval as short as 1 second.

BODY Not Applicable

{ • Immersion_index is a score between 0 - 100. 0 = bad, 100 = good

RESULT “immersion_index":100,
“tier_indicator”:"Very High”,
“color_indicator":"Green",
“context_indicator":"Captivated"
}
• Tier_indicator will be any of [Very Low, Low, Medium, High, Very High]
• Color_indicator will be any of [Red, Gray, Green]
• Context_indicator will be any of [Tuned Out, Indifferent, Interested, Absorbed, Captivated]

© 2021 Immersion Neuroscience Inc. All Rights Reserved. Confidential.

 Psychological Safety Results

Real-time Safety score results

ACTION GET

URL https://{base_url}/index/v2/index/safety/{identifier}?from_epoch={timestamp}&to_epoch={timestamp}

HEADERS Accept: application/json

Authorization: {auth_token}

PATH ARGUMENTS {base-url} : This was provided to you during API Onboarding
{identifier} : A unique 10-100 character string that you can use to identify this
individual. This must be unique to you and must be lowercase.
Example: mycompany-123456789
Do not include spaces, unicode, or high ascii characters.

© 2021 Immersion Neuroscience Inc. All Rights Reserved. Confidential.

 Psychological Safety Results
Real-time Safety score results
?from_epoch={timestamp}
QUERY STRING &to_epoch={timestamp}
BODY Not Applicable
{ •
RESULT “safety_index":100,
“tier_indicator”:"Very High”,
“color_indicator":"Green",
“context_indicator”:"Zen"
}
© 2021 Immersion Neuroscience Inc. All Rights Reserved. Confidential.
• ALL FIELDS ARE REQUIRED
• from_epoch is a 10 digit timestamp that represent when you would like to begin calculation
• to_epoch is a 10 digit timestamp that represent when you would like to end calculation
• Immersion will calculate the Immersion score for the period of time between the
from_epoch and to_epoch
• You may make this time interval as short as 1 second.
Safety_index is a score between 0 - 100. 0 = bad, 100 = good
• Tier_indicator will be any of [Very Low, Low, Medium, High, Very High]
• Color_indicator will be any of [Red, Gray, Green]
• Context_indicator will be any of [Very Unsafe, Unsafe, Safe, Very Safe, Zen]