Using researcher API Key

You can find the researcher API Key on the settings page:

Researcher API Key on the settings page

API Base URL Update

The API has moved to the new .corsano.health domain. The base URL has been updated from https://api.integration.corsano.com to https://public-api.corsano.health. Previous .corsano.com URLs continue to work for backward compatibility, but we recommend using the new .corsano.health base URLs for all new integrations.

All endpoints below use the base URL https://public-api.corsano.health and require the researcher API Key, passed as the token query parameter unless noted otherwise.

Studies

Getting list of studies

Endpoint: GET /v1/groups

Using this token you can fetch the list of studies the associated researcher has.

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The researcher API Key

Example

Request:

curl --request GET \
  --url 'https://public-api.corsano.health/v1/groups?token=TOKEN'

Response:

[
	{
		"name": "Cardiology",
		"description": "Demo",
		"code": "EZTJD",
		"hcpCode": "HCP-EZTJD-ky3xrt",
		"id": "<id>",
		"timestamp": 1669980357629
	}
]

Creating a new study

Endpoint: POST /v1/groups

Creates a new study and returns the created study object.

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The researcher API Key

Body

{
	"name": "Cardiology",
	"description": "Demo"
}

Example

Request:

curl --request POST \
  --url 'https://public-api.corsano.health/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": "<id>",
	"timestamp": 1669980357629
}

Patients

Getting list of patients in a study

Endpoint: GET /v1/groups/:groupCode/patients

Returns the list of patients in the given study.

Path Parameters

Parameter	Type	Description
`groupCode`	string	The code of the study

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The researcher API Key
`fields[]`	string	No	Repeatable parameter to limit the returned attributes. If omitted, all fields below are included, along with the `device` field.

Supported fields[] values:

Field	Description
`first_name`
`last_name`
`email`	Email address (if set) associated with the patient.
`birthday`	Date of birth.
`gender`
`country`	Country of residence (ISO country name).
`height`	Patient's height in centimeters.
`weight`	Patient's weight in kilograms.
`skin_color`	Fitzpatrick scale (1-6)
`customer_tag`	The 5-character study code (example: FA123)
`external_patient_id`	Identifier used in the customer's own system (EHR, CRM, etc.).
`state`	Patient onboarding status (e.g., `pre_created` if voucher code not yet activated, or `confirmed`).
`hair_density`	From 1-4

Example

Request:

curl --request GET \
  --url 'https://public-api.corsano.health/v1/groups/EZTJD/patients?token=TOKEN&fields=first_name&fields=email'

Response:

[
	{
		uuid: "5b72****01ec",
		first_name: "Fn",
		email: "fn@gmail.com",
		device: {
			// ...
		},
	},
	{
		uuid: "f118****9c3b",
		first_name: "Daniel",
		email: "daniel@gmail.com",
		device: {
			// ...
		},
	},
];

Adding an anonymous patient with voucher to a study

Endpoint: POST /v1/groups/:groupCode/patients

Adds a new anonymous patient, identified by a voucher code, to the given study. The patient is created with the state pre_created, and is activated once the voucher is used in the mobile app. See Activating the patient in the app for the activation flow.

Path Parameters

Parameter	Type	Description
`groupCode`	string	The code of the study

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The researcher API Key

Example

Request:

curl --request POST \
  --url 'https://public-api.corsano.health/v1/groups/EZTJD/patients?token=TOKEN' \
  --header 'Content-Type: application/json'

Response:

{
	"uuid": "<uuid>",
	"code": "YUHXXPCT",
	"state": "pre_created",
	"_id": "6633e43e65aa5f41e25e7f62"
}

Checking the state of a patient with a voucher

Endpoint: GET /v1/check-voucher-code/:voucherCode

Returns the state of the patient associated with the given voucher code.

Path Parameters

Parameter	Type	Description
`voucherCode`	string	The voucher code

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The researcher API Key

Example

Request:

curl --request GET \
  --url 'https://public-api.corsano.health/v1/check-voucher-code/YUHXXPCT?token=TOKEN'

Response:

{
	"exists": true,
	"state": "confirmed",
	"created_at": "2024-06-07T07:12:05.199Z"
}

Resetting a patient's password

Endpoint: POST /v1/patients/:uuid/reset-password

Resets the password of a patient. Only available for patients with the state confirmed.

Path Parameters

Parameter	Type	Description
`uuid`	string	The UUID of the patient

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The researcher API Key

Body

Parameter	Type	Required	Description
`password`	string	Yes	The new password

Example

Request:

curl --request POST \
  --url 'https://public-api.corsano.health/v1/patients/<uuid>/reset-password?token=TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "password": "new_password1A!"
}'

Getting a patient's health token

Endpoint: GET /v1/patients/:uuid/health-token

Returns the health token for a specific patient. Intended for use by authorized researchers or doctors with a valid researcher token and access rights to the specified patient.

Path Parameters

Parameter	Type	Description
`uuid`	string	The UUID of the patient

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The researcher token (API key format)

Example

Request:

curl --request GET \
  --url 'https://public-api.corsano.health/v1/patients/{uuid}/health-token?token={researcher_token}'

Response:

{
	"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ey..."
}

Getting a patient's latest NEWS score

Endpoint: GET /v1/patients/:uuid/latest-news-score

Returns the latest NEWS score entry for a specific patient. Intended for use by authorized researchers or doctors with a valid researcher token and access rights to the specified patient.

Path Parameters

Parameter	Type	Description
`uuid`	string	The UUID of the patient

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The researcher token (API key format)

Example

Request:

curl --request GET \
  --url 'https://public-api.corsano.health/v1/patients/{uuid}/latest-news-score?token={researcher_token}'

Response:

{
	"timestamp": 1745155064000,
	"value": 1,
	"score_heart_rate": 0,
	"score_respiration_rate": 0,
	"score_spo2": 1,
	"score_temperature": 0,
	"score_blood_pressure": 0,
	"heart_rate": 67,
	"respiration_rate": 18,
	"spo2": 96,
	"temperature": 37,
	"blood_pressure": 119,
	"movement_level": 0
}

Getting patients' real-time data

Endpoint: GET /v1/groups/:groupCode/patients

Returns the list of patients in a group along with their latest available values. Call the endpoint with the with_latest_values=1 parameter.

Path Parameters

Parameter	Type	Description
`groupCode`	string	The code of the study

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The researcher token (API key format)
`with_latest_values`	number	Yes	Set to `1` to include latest values

Example

Request:

curl --request GET \
  --url 'https://public-api.corsano.health/v1/groups/{GROUP_CODE}/patients?with_latest_values=1&token={TOKEN}' \
  --header 'Content-Type: application/json'

Response:

[
	{
		"uuid": "",
		// other patients information
		"latest_values": {
			"heart_rate": 64,
			"heart_rate_timestamp": 1749214381000,
			"respiration_rate": 18,
			"respiration_rate_timestamp": 1749214381000,
			"temperature": 36.78,
			"temperature_timestamp": 1749214381000,
			"spo2": 98,
			"spo2_timestamp": 1749214381000,
			"nibp_diastolic": 74,
			"nibp_systolic": 124,
			"nibp_diastolic_timestamp": 1749214381000,
			"nibp_systolic_timestamp": 1749214381000,
			"news_score": 3
		}
	}
]

Summaries

Getting patients' summaries

Endpoint: GET /v1/groups/:groupCode/summaries

Returns the summary objects of the patients inside a group for a specified date. The response is an object keyed by patient UUID, with the summary as the value.

Path Parameters

Parameter	Type	Description
`groupCode`	string	The code of the study

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The researcher API Key
`date`	string	Yes	The date of the summary (`YYYY-MM-DD`)
`include_slots`	number	No	Set to `1` to include the slots in each summary

Example

Request:

curl --request GET \
  --url 'https://public-api.corsano.health/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, ...
		}
	},
	"<uuid>": {
		"date": "2024-06-19",
		"activity": {
			"date": "2024-06-19",
			"total_steps": 13097,
			"daily_percent": 0,
			"distance": 9472, ...
	....

Getting summary of an individual patient

Endpoint: GET /v1/patients/:uuid/summary/:date

Similarly to the group summaries endpoint, returns the summary object of an individual patient for a specified date.

Path Parameters

Parameter	Type	Description
`uuid`	string	The UUID of the patient
`date`	string	The date of the summary (`YYYY-MM-DD`)

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The researcher API Key
`include_slots`	number	No	Set to `1` to include the slots in the summary object
`types`	array	No	Array of strings to limit the response to specific parts of the summary (e.g. `["activity", "heart_rate"]`)

Getting summary of an individual patient

Getting summary compliance for an individual patient

Endpoint: GET /v1/patients/:uuid/compliance/:date

Returns the compliance value of a patient for a specified date. This value is based on the heart rate data — the percentage of heart rate data that has been recorded to the cloud for that date.

Path Parameters

Parameter	Type	Description
`uuid`	string	The UUID of the patient
`date`	string	The date of the summary (`YYYY-MM-DD`)

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The researcher API Key

Getting summary compliance for an individual patient

Audit Logs

Getting audit logs

Endpoint: GET /v1/patients/audit/logs

Returns the audit logs for the account that owns the API token. Audit logs track important events and changes, providing a chronological record for compliance and monitoring purposes.

The response contains all log entries in which the token owner (doctor) appears — as the acting user, as the primary entity, or as the secondary entity. To review the events of one specific patient, filter the returned entries by the patient identifier in primary_entity_id / secondary_entity_id on the client side.

Deprecated: The previous endpoint GET /v1/patients/:uuid/audit/logs is deprecated and returns 410 Gone. Use GET /v1/patients/audit/logs instead. The scope of the results is the same: logs were already scoped to the token's doctor, not to the uuid path parameter.

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The researcher token (API key format)
`from`	number	Yes	Start timestamp in milliseconds (Unix epoch)
`to`	number	Yes	End timestamp in milliseconds (Unix epoch)
`action_type`	string	No	Filter logs by action code (e.g., `PATIENT_UPDATE`, `USER_LOGIN`)

Action Codes

The following action codes may appear in audit logs:

Patients

Action Code	Primary Entity	Secondary Entity
`PATIENT_CREATE`	patient.id
`PATIENT_UPDATE`	patient.id
`PATIENT_DELETE`	patient.id
`PATIENT_ATTACH_GROUP`	patient.id	group.id
`PATIENT_DETACH_GROUP`	patient.id	group.id
`PATIENT_PROFILE_UPDATE`	patient.id	hcp_admin.id
`PATIENT_ALARM_CHANGE`	patient.id	hcp_admin.id
`PATIENT_PORTAL_EXPORT`	patient.id	hcp_admin.id
`PATIENT_API_EXPORT`	patient.id	hcp_admin.id

Groups

Action Code	Primary Entity	Secondary Entity
`GROUP_CREATE`	group.id
`GROUP_UPDATE`	group.id
`GROUP_DELETE`	group.id
`GROUP_SETTINGS_CHANGE`	group.id

Users

Action Code	Primary Entity	Secondary Entity
`USER_REGISTERED`	user.id
`USER_LOGIN`	user.id
`USER_DELETE`	user.id

HCP (Healthcare Practitioner)

Action Code	Primary Entity	Secondary Entity
`ADD_HCP`	hcp.uuid	doctor.uuid
`REMOVE_HCP`	hcp.uuid	doctor.uuid

Bracelets

Action Code	Primary Entity	Secondary Entity
`BRACELET_CREATE`	user.id	bracelet.id
`BRACELET_UPDATE`	bracelet.id
`BRACELET_DELETE`	bracelet.id
`BRACELET_ATTACH`	bracelet.id
`BRACELET_DETACH`	bracelet.id

Errors

Status	Description
`401`	The token is missing or not valid
`403`	The token has no active subscription

Example

Request:

curl --request GET \
  --url 'https://public-api.corsano.health/v1/patients/audit/logs?token=TOKEN&from=1704067200000&to=1704153600000' \
  --header 'Content-Type: application/json'

Use Cases

Compliance: Track data access and modifications for regulatory requirements
Monitoring: Review patient-related events and activities
Troubleshooting: Investigate issues by reviewing the audit trail

Studies​

Getting list of studies​

Creating a new study​

Patients​

Getting list of patients in a study​

Adding an anonymous patient with voucher to a study​

Checking the state of a patient with a voucher​

Resetting a patient's password​

Getting a patient's health token​

Getting a patient's latest NEWS score​

Getting patients' real-time data​

Summaries​

Getting patients' summaries​

Getting summary of an individual patient​

Getting summary compliance for an individual patient​

Audit Logs​

Getting audit logs​

Studies

Getting list of studies

Creating a new study

Patients

Getting list of patients in a study

Adding an anonymous patient with voucher to a study

Checking the state of a patient with a voucher

Resetting a patient's password

Getting a patient's health token

Getting a patient's latest NEWS score

Getting patients' real-time data

Summaries

Getting patients' summaries

Getting summary of an individual patient

Getting summary compliance for an individual patient

Audit Logs

Getting audit logs