Using researcher API Key
You can find the researcher API Key on the settings page:
Getting list of studies
Using this token you can fetch the list of studies of the associated researcher has.
To do that you need to make the GET request:
You need to replace {TOKEN} with the API Key. In return you will get the JSON list of studies.
Example
Request:
curl --request GET \
--url 'https://api.integration.corsano.com/v1/groups?token=TOKEN'
Response:
[
{
"name": "Cardiology",
"description": "Demo",
"code": "EZTJD",
"hcpCode": "HCP-EZTJD-ky3xrt",
"id": "hOEgOpsdhX",
"timestamp": 1669980357629
}
]
Getting list of patients in the study
To get the list of patients in the study you need to make the GET request:
https://api.integration.corsano.com/v1/groups/{GROUP_CODE}/patients?token={TOKEN}
You need to replace {GROUP_CODE} with the code of the study and {TOKEN} with the API Key. In return you will get the JSON list of patients.
Example
Request:
curl --request GET \
--url 'https://api.integration.corsano.com/v1/groups/EZTJD/patients?token=TOKEN'
Response:
[
{
"_id": "65a3c377f61b00514e6cc723",
"uuid": "7fbc9e37-67e2-4df3-a0e2-148ace6d13db",
"code": "PDVYFG83",
"state": "pre_created"
},
{
"first_name": "Peter",
"last_name": "Smith",
"state": "confirmed",
"email": "pcsmith@gmail.com",
"_id": "5ed616222e74ec20bcab8490",
"uuid": "50907d67-1575-4599-8693-80b14e68b57b"
}
]
Getting patients' summaries
You can get the summaries objects of patients inside the group by making GET request
https://api.integration.corsano.com/v1/groups/{GROUP_CODE}/summaries?token={TOKEN}&date={DATE}
You need to replace {GROUP_CODE} with the code of the study, {DATE} with a date of the summary (YYYY-MM-DD) and {TOKEN} with the API Key. In response you will get the object with summary of each patient in the group for the specified date. The key in the object is the uuid of the patient and the value is the summary.
You can pass optional parameter include_slots=1 to get the slots in each summary object.
Example
Request:
curl --request GET \
--url 'https://api.integration.corsano.com/v1/groups/EZTJD/summaries?token=TOKEN&date=2024-06-19'
Response:
{
"d23cf3dc-064c-456b-93fb-cdbb639bf520": {
"date": "2024-06-19",
"activity": {
"date": "2024-06-19",
"total_steps": 4128,
"daily_percent": 0,
"distance": 2976,
"calories": 2422, ...
},
"heart_rate": {
"date": "2024-06-19",
"avg_daily_heart_rate": 63,
"max_daily_heart_rate": 104,
"rest_daily_heart_rate": 51, ...
},
"recovery": {
"date": "2024-06-19",
"value": 58,
"avg_rmssd_past_60_days": 62.14,
"avg_rmssd_today": 45.16, ...
},
"respiration_rate": {
"date": "2024-06-19",
"avg_respiration_rate": 14, ...
},
"sleep": {
"date": "2024-06-19",
"sleep_duration": 22680,
"daily_percent": 0,
"awake_time": 120,
"rem_time": 5640, ...
},
"spo2": {
"date": "2024-06-19",
"avg_spo2": 99, ...
},
"stress": {
"avg_si": 61.5,
"avg_si_n": 37.8,
"avg_mrr": 1056.7,
"avg_sdnn": 73.5,
"avg_rmssd": 45.1,
"avg_pnn50": 24.2, ...
},
"stress_continuous": {
"avg_si": 91.4,
"avg_si_n": 45.3,
"avg_mrr": 923.9,
"avg_sdnn": 71.1, ...
},
"temperature": {
"date": "2024-06-19",
"avg_temp_sk1": 37.1,
"avg_temp_sk2": 0,
"max_temp_sk1": 38.2,
"max_temp_sk2": 0, ...
}
},
"50907d67-1575-4599-8693-80b14e68b57b": {
"date": "2024-06-19",
"activity": {
"date": "2024-06-19",
"total_steps": 13097,
"daily_percent": 0,
"distance": 9472, ...
....
Getting summary of individual patient
Similarly to the previous example, you can get the summary object of the individual patient inside the group by making GET request:
https://api.integration.corsano.com/v1/patients/{PATIENT_UUID}/summary/{DATE}?token={TOKEN}
You need to replace {PATIENT_UUID} with the uuid of the patient, {DATE} with a date of the summary (YYYY-MM-DD) and {TOKEN} with the API Key. In return you will get the summary object of the patient for the specified date. You can optionally pass the parameter include_slots=1 to get the slots in the summary object. You can pass the GET-parameter types (array of strings) to get the specific parts of the summary object. (For example ["activity", "heart_rate"])
Getting summary compliance of individual patient
You can get the summary compliance object of the individual patient by making GET request:
https://api.integration.corsano.com/v1/patients/{PATIENT_UUID}/compliance/{DATE}?token={TOKEN}
You need to replace {PATIENT_UUID} with the uuid of the patient, {DATE} with a date of the summary (YYYY-MM-DD) and {TOKEN} with the API Key.
In return you will get the compliance value of the patient for the specified date. This value is based on the heart rate data (the percentage of the heart rate data that has been recorded to the cloud for the specified date).
Creating a new study
To create a new study you need to make the POST request:
You need to replace {TOKEN} with the API Key. In the body of request you need to pass the JSON object with the following structure:
{
"name": "Cardiology",
"description": "Demo"
}
In return you will get the JSON object with the created study.
Example
Request:
curl --request POST \
--url 'https://api.integration.corsano.com/v1/groups?token=TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"name": "Cardiology",
"description": "Demo"
}'
Response:
{
"name": "Cardiology",
"description": "Demo",
"code": "EZTJD",
"hcpCode": "HCP-EZTJD-ky3xrt",
"id": "hOEgOpsdhX",
"timestamp": 1669980357629
}
Adding an anonymous patient with voucher to the study
To add a patient to the study you need to make the POST request:
https://api.integration.corsano.com/v1/groups/{GROUP_CODE}/patients?token={TOKEN}
You need to replace {GROUP_CODE} with the code of the study and {TOKEN} with the API Key.
Example
Request:
curl --request POST \
--url 'https://api.integration.corsano.com/v1/groups/EZTJD/patients?token=TOKEN' \
--header 'Content-Type: application/json'
Response:
{
"uuid": "f0ae6aea-cde0-4a5f-9896-4fff24592bfb",
"code": "YUHXXPCT",
"state": "pre_created",
"_id": "6633e43e65aa5f41e25e7f62"
}
Important: The patient will be created with the state "pre_created". The patient will be activated when the voucher is used by the patient in the mobile app. Please check instruction for activating the patient in the mobile app here: Activating the patient in the app
Checking the state of the patient with voucher
To check the state of the patient with voucher you need to make the GET request:
https://api.integration.corsano.com/v1/check-voucher-code/{VOUCHER_CODE}?token={TOKEN}
You need to replace {VOUCHER_CODE} with the voucher code and {TOKEN} with the API Key.
Example
Request:
curl --request GET \
--url 'https://api.integration.corsano.com/v1/check-voucher-code/YUHXXPCT?token=XXXX'
Response:
{
"exists": true,
"state": "confirmed",
"created_at": "2024-06-07T07:12:05.199Z"
}
Resetting the password of the patient
To reset the password of the patient you need to make the POST request:
https://api.integration.corsano.com/v1/patients/{PATIENT_UUID}/reset-password?token={TOKEN}
You need to replace {PATIENT_UUID} with the uuid of the patient and {TOKEN} with the API Key. You also pass the "password" parameter in the body of the request with the new password. You can reset the password only for the patients with the state "confirmed".
Example
Request:
curl --request POST \
--url 'https://api.integration.corsano.com/v1/patients/50907d67-1575-4599-8693-80b14e68b57b/reset-password?token=TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"password": "new_password1A!"
}'