Quickstart Guide

This guide will help you set up your systems to receive processed health assessment data from HiQOR. We'll walk through API setup, authentication configuration, and handling both non-sensitive and sensitive data deliveries.

Step 1: Provide Your API Endpoint

Before HIQOR can deliver data to your system, you will provide us with one or more API URLs where processed data should be POSTed.

Your API endpoint should be able to receive JSON POST requests.

Provide to HIQOR:

• API URL (e.g., https://your-domain.com/api/hiqor/webhook)
• Preferred authentication method (API Key header, Bearer token, HMAC signature, etc.)
• Any required custom headers
• Environment mapping (e.g., staging vs production URLs)

HIQOR will store these settings and use them when POSTing data out from AWS.

Step 2: Configure Authentication

HIQOR does not require clients to call our API to retrieve results.

Instead, HIQOR authenticates when POSTing results to your API endpoint using the method you choose (API Key, Bearer Token, etc).

Example POST request from HIQOR → your API endpoint:

POST /api/hiqor/webhook HTTP/1.1
Host: your-domain.com
Content-Type: application/json
X-API-Key: your-api-key
X-HIQOR-Signature: sha256-signature-value   // optional if HMAC enabled

{
  "assessmentType": "FaceScan",
  "funnelID": "your-funnel-id",
  "patientUUID": "123e4567-e89b-12d3-a456-426614174000"
}

Step 3: Receive Patient Data

HIQOR will POST patient data to your API endpoint based on your selected data delivery preference.

Clients can choose to receive:

• Non-sensitive (PII) data only — typically collected during the initial intake form before the scan, or
• Full data (PII + PHI) — includes processed health metrics after the Face Scan assessment is completed.

Your API endpoint should be prepared to handle JSON payloads for whichever option you have configured.

Non-Sensitive Data Payload

Delivered when initial form is completed:

{
  "assessmentType": "FaceScan",
  "funnelID": "your-funnel-id",
  "uuid": "c2094a43-772f-4a55-973d-9bf775fa7013",
  "email": "patient@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+1234567890",
  "zipCode": "12345",
  "biologicalSex": "male",
  "age": 35,
  "dateOfBirth": "1988-01-01",
  "city": "New York",
  "state": "New York",
  "IPAddress": "192.168.1.1",
  "contactConsent": true,
  "formCompleted": true
}

Sensitive Data Payload

Delivered when face scan assessment is completed:

{
  "assessmentType": "FaceScan",
  "funnelID": "hiqor",
  "uuid": "de3d4971-0cb6-45f5-a0d4-8d124d4d4f7b",
  "email": "luanne@hiqor.com",
  "healthCreditScore": 770,
  "healthCreditCategory": "Very Good",
  "systolicBloodPressure": 117,
  "diastolicBloodPressure": 71,
  "bloodPressureCategory": "Normal",
  "heartRateBpm": 90,
  "heartRateCategory": "Normal",
  "heartRateVariabilityMs": 64,
  "heartRateVariabilityCategory": "Very Good",
  "breathingRateBpm": 17,
  "breathingRateCategory": "Normal",
  "oxygenSaturationPercent": 98,
  "oxygenSaturationCategory": "Normal",
  "stressIndex": "Low",
  "activityScore": 705,
  "activityScoreMax": 850,
  "activityCategory": "Good",
  "sleepScore": 825,
  "sleepScoreMax": 850,
  "sleepCategory": "Excellent",
  "equilibriumScore": 625,
  "equilibriumScoreMax": 850,
  "equilibriumCategory": "Fair",
  "metabolismScore": 625,
  "metabolismScoreMax": 850,
  "metabolismCategory": "Fair",
  "overallHealthScore": 770,
  "overallHealthScoreMax": 850,
  "overallHealthCategory": "Very Good",
  "relaxationScore": 705,
  "relaxationScoreMax": 850,
  "relaxationCategory": "Good",
  "sex": "male",
  "age": 29,
  "weight": 112,
  "height": "5'8"",
  "smokerStatus": "current",
  "diabetic": "none",
  "hypertension": "false",
  "bpMedication": "false",
  "assessmentCompleted": true
}

Step 4: Acknowledge Received Data

Your API endpoint must respond to HiQOR's POST requests to acknowledge successful receipt of the data. Return a 2xx status code to confirm successful processing:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "received",
  "uuid": "c2094a43-772f-4a55-973d-9bf775fa7013",
  "timestamp": "2025-01-15T10:30:00Z"
}

If your endpoint returns a non-2xx status code, HiQOR will automatically retry the delivery according to our retry logic (up to 3 attempts with exponential backoff).

Important Notes

• Your API endpoint must be publicly accessible and able to accept HTTP POST requests.
• Respond with a 2xx status code within 30 seconds to confirm successful receipt.
• Use the included uuid field for idempotency to prevent duplicate processing if retries occur.
• Authenticate every inbound request according to the authentication method you provided to HIQOR (e.g., API Key, OAuth token, Basic Auth, etc.).
• Store the uuid for tracking, auditing, and reconciling incoming data deliveries.
• If you are receiving PHI, ensure your endpoint and storage meet your compliance requirements.

If you encounter any issues or have questions, don't hesitate to contact our API team at api@hiqor.com.