Retrieve a Vitals Scan

GET

/businesses/{businessId}/vitals/scans/{scanId}

const url = 'https://api.upvio.com/v1/businesses/example/vitals/scans/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.upvio.com/v1/businesses/example/vitals/scans/example \
  --header 'Authorization: Bearer <token>'

Retrieve a vitals scan by ID.

Authorizations

apiKey

Parameters

Path Parameters

businessId

required

The ID of the Business.

string

scanId

required

The ID of the Vitals Scan.

string

Responses

200

A Vitals Scan.

application/json

object

data

object

required

Unique identifier across the platform.

string format: uuid

createdAt

required

Time when the resource was created (ISO 8601 format).

string format: date-time

updatedAt

required

Time when the resource was last updated (ISO 8601 format).

string format: date-time

patientId

Unique identifier across the platform.

string format: uuid

vitalsLinkId

The ID of the vitals link used for this scan.

string

status

required

The status of the vitals scan.

string

Allowed values: PENDING STARTED SUCCEEDED FAILED ABORTED

results

The results of a Vitals Scan. Only present when status is SUCCEEDED.

object

metrics

Metric values from the scan. Only metrics listed in includedMetrics will be present.

object

heartRate

Heart rate in beats per minute (BPM).

number

nullable

heartRateVariability

Heart rate variability in milliseconds (ms).

number

nullable

breathingRate

Breathing rate in breaths per minute (b/min).

number

nullable

stressIndex

Stress index on a 0–10 scale (modified Baevsky method). Higher values indicate more stress.

number

nullable

parasympatheticActivity

Parasympathetic activity as a percentage (0–100).

number

nullable

cardiacWorkload

Cardiac workload (rate-pressure product) in mmHg/s.

number

nullable

bloodPressureDiastolic

Diastolic blood pressure in mmHg.

number

nullable

bloodPressureSystolic

Systolic blood pressure in mmHg.

number

nullable

bmiClassification

Body Mass Index (BMI) in kg/m².

number

nullable

wellnessScore

Overall wellness score on a 0–100 scale. Higher values indicate better wellness.

number

nullable

vascularAge

Vascular age in years.

number

nullable

atheroscleroticCvdRisk

10-year atherosclerotic cardiovascular disease (ASCVD) risk as a percentage (0–100).

number

nullable

cardiovascularEventRisk

10-year risk of a hard cardiovascular event as a percentage (0–100).

number

nullable

cardiovascularRiskScore

Framingham cardiovascular risk score in points: the sum of the points assigned to each risk factor under the Framingham general cardiovascular disease point system. Higher totals indicate higher risk.

number

nullable

hypertensionRisk

Probability of developing hypertension within 4 years, as a percentage (0–100).

number

nullable

diabetesRisk

Probability of developing diabetes within 8 years, as a percentage (0–100).

number

nullable

fattyLiverDiseaseRisk

Fatty liver disease (NAFLD) risk category: 0 = Low, 1 = Moderate, 2 = High.

number

nullable

waistToHeightRatio

Waist-to-height ratio (WHtR), unitless.

number

nullable

bodyFatPercentage

Body fat as a percentage of body weight (0–100).

number

nullable

bodyRoundnessIndex

Body roundness index (BRI), unitless.

number

nullable

aBodyShapeIndex

A Body Shape Index (ABSI), unitless.

number

nullable

conicityIndex

Conicity index (CI), unitless, ranging from 1.00 to about 1.73.

number

nullable

basalMetabolicRate

Basal metabolic rate in kcal/day.

number

nullable

totalDailyEnergyExpenditure

Total daily energy expenditure (TDEE) in kcal/day.

number

nullable

includedMetrics

required

The metrics included in this scan.

Array<string>

Allowed values: A_BODY_SHAPE_INDEX ATHEROSCLEROTIC_CVD_RISK BASAL_METABOLIC_RATE BLOOD_PRESSURE BLOOD_PRESSURE_DIASTOLIC BLOOD_PRESSURE_SYSTOLIC BMI_CLASSIFICATION BODY_FAT_PERCENTAGE BODY_ROUNDNESS_INDEX BREATHING_RATE CARDIAC_WORKLOAD CARDIOVASCULAR_EVENT_RISK CARDIOVASCULAR_RISK_SCORE CONICITY_INDEX DIABETES_RISK FATTY_LIVER_DISEASE_RISK HEART_RATE HEART_RATE_VARIABILITY HYPERTENSION_RISK PARASYMPATHETIC_ACTIVITY STRESS_INDEX TOTAL_DAILY_ENERGY_EXPENDITURE VASCULAR_AGE WAIST_TO_HEIGHT_RATIO WELLNESS_SCORE

startedAt

When the scan was started.

string format: date-time

nullable

inputData

Pre-filled patient health profile data for the scan. Only present when provided during scan creation.

object

gender

Patient gender.

string

Allowed values: male female other

countryCode

ISO 3166-1 alpha-2 country code.

string

>= 2 characters <= 2 characters

age

Patient age in years.

number

>= 16 <= 120

dob

Date of birth in YYYY-MM-DD format.

string

/^\d{4}-\d{2}-\d{2}$/

race

Patient race/ethnicity.

string

height

Patient height in cm.

number

>= 100 <= 250

weight

Patient weight in kg.

number

>= 30 <= 200

waistCircumference

Waist circumference in cm.

number

>= 50 <= 150

neckCircumference

Neck circumference in cm.

number

>= 20 <= 60

hipCircumference

Hip circumference in cm.

number

>= 50 <= 200

smokingStatus

Patient smoking status.

string

Allowed values: never former current

diabetesStatus

Patient diabetes status.

string

Allowed values: none preDiabetes diabetes

hypertensionTreatment

Hypertension treatment status.

string

Allowed values: notNeeded no yes

activityLevel

Patient physical activity level.

string

Allowed values: inactive exercise10Mins exercise20to60Mins exercise1to3Hours exerciseOver3Hours

chronicMedicationStatus

Chronic medication status.

string

Allowed values: none oneOrTwoDiseases threeOrMoreDiseases

cholesterol

Total cholesterol level in mg/dL.

number

cholesterolHdl

HDL cholesterol level in mg/dL.

number

cholesterolLdl

LDL cholesterol level in mg/dL.

number

familyDiabetesHistory

Family history of diabetes.

string

Allowed values: none noneFirstDegree firstDegree

parentalHypertensionHistory

Parental history of hypertension.

string

Allowed values: none one both

historyOfHighGlucose

Whether patient has history of high glucose.

boolean

historyOfHypertension

Whether patient has history of hypertension.

boolean

vegetableFruitDiet

Whether patient eats vegetables and fruit daily.

boolean

fastingGlucose

Fasting glucose level in mg/dL.

number

triglyceride

Triglyceride level in mg/dL.

number

retriedByScanId

ID of the new scan that retried this one.

string format: uuid

nullable

successReturnUrl

HTTPS URL to redirect to when the scan completes successfully.

string format: uri

nullable

failureReturnUrl

HTTPS URL to redirect to when the scan fails.

string format: uri

nullable

abortReturnUrl

HTTPS URL to redirect to when the scan is aborted.

string format: uri

nullable

skipResultsScreen

When true, the patient app skips the post-scan results screen and redirects immediately to successReturnUrl. When skipResultsScreen is true, successReturnUrl is guaranteed to be non-null (enforced at scan creation).

boolean

nullable

settings

object

headerVisibility

Controls whether the patient app renders its header during this scan.

string

Allowed values: hidden visible

verificationMethod

How the identity behind the scan was established. EMAIL = verified patient session, API = created via the business API, NONE = no email verification.

string

nullable

Allowed values: EMAIL API NONE

metadata

required

Arbitrary string key/value pairs attached to the scan. Up to 10 keys; each key up to 40 characters and each value up to 500 characters. Always present; an empty object when none are set.

object

key

additional properties

string

failureInfo

Why the scan failed. Only present when status is FAILED.

object

failureReason

required

Why the scan failed. timeout: the measurement ran past the maximum scan time while its progress was stalled below the completion threshold. results_processing_timeout: the measurement finished but its results were not processed in time. no_measurement_results: the measurement finished but produced no results. other: the measurement failed for any other reason.

string

Allowed values: timeout results_processing_timeout no_measurement_results other

totalScanDurationMs

How long the scan ran before failing, in milliseconds. Only present when failureReason is timeout or results_processing_timeout.

integer

stallDurationMs

Total time the scan made no progress, in milliseconds. Only present when failureReason is timeout or results_processing_timeout.

integer

finalProgressPercentage

Measurement progress when the scan failed, as a percentage (0–100). Only present when failureReason is timeout or results_processing_timeout.

number

<= 100

maxScanTimeThresholdMs

Maximum scan time allowed before the scan could time out, in milliseconds. Only present when failureReason is timeout or results_processing_timeout.

integer

maxStallTimeThresholdMs

Maximum time without progress allowed before the scan could time out, in milliseconds. Only present when failureReason is timeout or results_processing_timeout.

integer

Example

{
  "data": {
    "status": "PENDING",
    "includedMetrics": [
      "A_BODY_SHAPE_INDEX"
    ],
    "inputData": {
      "gender": "male",
      "smokingStatus": "never",
      "diabetesStatus": "none",
      "hypertensionTreatment": "notNeeded",
      "activityLevel": "inactive",
      "chronicMedicationStatus": "none",
      "familyDiabetesHistory": "none",
      "parentalHypertensionHistory": "none"
    },
    "settings": {
      "headerVisibility": "hidden"
    },
    "verificationMethod": "EMAIL",
    "failureInfo": {
      "failureReason": "timeout"
    }
  }
}

400

The scan ID is malformed.

application/json

object

error

object

code

number

type

The specific error that occurred.

string

Allowed values: BadRequestError

title

Human-readable description of the error.

string

Example

{
  "error": {
    "code": 400,
    "type": "BadRequestError",
    "title": "Invalid platformId format."
  }
}

403

The API key is missing or invalid, or the Business cannot be accessed with it.

application/json

object

error

object

code

number

type

The specific error that occurred.

string

Allowed values: UnauthorizedError BusinessArchivedError BusinessDisabledError

title

Human-readable description of the error.

string

Example

{
  "error": {
    "code": 403,
    "type": "UnauthorizedError",
    "title": "Invalid API token"
  }
}

404

The vitals scan does not exist.

application/json

object

error

object

code

number

type

The specific error that occurred.

string

Allowed values: NotFoundError BusinessNotFoundError

title

Human-readable description of the error.

string

Example

{
  "error": {
    "code": 404,
    "type": "NotFoundError",
    "title": "Vitals Scan not found"
  }
}