Data Delivery API

HIQOR securely delivers processed face scan assessment data from HIQOR’s AWS environment to your systems. HIQOR transmits both non-sensitive (PII) intake data and sensitive (PHI) scan result data based on your selected delivery configuration. All data is delivered as structured HTTP POST requests to your provided endpoint(s).

Data Format

All data is delivered in JSON, using camelCase formatting:

Content-Type: application/json

If your system requires alternate formatting (XML, snake_case, or field exclusions), contact the HIQOR API team at api@hiqor.com.

Endpoint Requirements

Your endpoint must:

Accept HTTPS POST requests
Return a 2xx status code to confirm successful receipt
Support your preferred authentication method (API Key, OAuth token, Basic Auth, or custom headers)

Delivery configuration options:

Delivery Type	Contents	When Sent
Non-Sensitive Data (PII)	User identity + contact + intake responses	When the user completes the initial intake form
Sensitive Data (PII + PHI)	Full health/scan metrics + structured results	When the user completes the Face Scan assessment

Clients may choose to receive:

PII only
PII + PHI
PII to one endpoint and PHI to another (optional split)

Key Fields

All API payloads will include the following key fields:

assessmentType - Type of assessment (e.g., "FaceScan")
funnelID - Your unique funnel identifier for routing
email - Patient email address
uuid - Unique identifier for the patient assessment

API Payload Structure

HiQOR will POST data to your API endpoint with the following payload structures. Your endpoint should be prepared to handle both types of data.

Non-Sensitive Data Payload Example

Received when initial form is completed:

{
  "assessmentType": "FaceScan",
  "funnelID": "your-funnel-id",
  "uuid": "11884643-42a0-499c-bafd-2b9a9617a5a6",
  "IPAddress": "192.168.0.1",
  "email": "patient@example.com",
  "lastName": "Doe",
  "firstName": "John",
  "phone": "1234567890",
  "zip": "12345",
  "contactConsent": true,
  "biologicalSex": "male",
  "age": 35,
  "dateOfBirth": "1988-01-01",
  "city": "New York",
  "state": "New York",
  "formCompleted": true
}

Sensitive Data Payload Example

Received 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
}

Note: The formCompleted field in the non-sensitive data payload indicates that the initial form has been completed. The assessmentCompleted field only appears in the sensitive data payload and indicates that the face scan assessment has been completed.

UUID Handling and Idempotency

The uuid field serves as a unique identifier for each patient assessment. Your system should use this UUID to implement idempotency handling:

Store the UUID when you first receive an API delivery
Check if the UUID already exists before processing subsequent deliveries
If a duplicate UUID is received, acknowledge receipt but skip duplicate processing
This prevents duplicate data processing in case of retry attempts

HiQOR may send the same data multiple times if your endpoint doesn't respond with a 2xx status code, so proper UUID-based idempotency handling is essential.

UUID for User Journey Tracking

The uuid represents a single user's journey within a funnel.

You may use it to associate all events for that user (intake → scan → follow-ups) under a single engagement record.

When receiving data from HIQOR:

If the uuid already exists in your system:
- Do not overwrite the record.
- Update or append the new data to the existing user timeline.
If the uuid does not exist:
- Create a new record and associate all future events with the same uuid.

This prevents duplicate entries during retries and enables you to:

Track user journey and engagement over time
Display trends or progress
Keep a clean, unified record per individual

Note:

Using the uuid for journey tracking is optional.
If your system does not track longitudinal engagement, you may still use the uuid strictly for idempotency to prevent duplicate processing.

Endpoint Response Requirements

Your endpoint must respond to HiQOR's POST requests to acknowledge successful receipt. Return a 2xx status code with a JSON response:

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

{
  "status": "received",
  "uuid": "11884643-42a0-499c-bafd-2b9a9617a5a6",
  "timestamp": "2025-01-15T10:30:00Z"
}

Any non-2xx response will be treated as a delivery failure and will trigger HiQOR's retry logic.

Retry Logic

If your endpoint doesn't respond with a 2xx status code, HiQOR will automatically retry the delivery:

Initial delivery attempt immediately after data processing
First retry after 1 minute
Second retry after 5 minutes
Third retry after 15 minutes
After 3 failed attempts, the delivery is marked as failed and logged

Failed deliveries can be manually retried or retrieved via API. Contact our team at api@hiqor.com if you need to retrieve failed deliveries or set up manual retry procedures.

Endpoint Setup

To configure your endpoint to receive data from HIQOR, you need to:

Create a publicly accessible HTTPS endpoint that accepts POST requests
Implement authentication validation for incoming requests
Implement UUID-based idempotency handling
Return appropriate 2xx status codes for successful receipt
Provide your endpoint URL and authentication requirements to HIQOR

Contact our API team at api@hiqor.com to configure your API endpoint and discuss any specific data format requirements.

Validation and Error Handling

Your endpoint should validate incoming data and return appropriate status codes:

Successful Receipt

Return 200 OK when data is received and processed successfully:

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

{
  "status": "received",
  "uuid": "de3d4971-0cb6-45f5-a0d4-8d124d4d4f7b"
}

Invalid Data Format

Return 400 Bad Request if the payload is malformed or missing required fields:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Missing required field: uuid"
}

Authentication Failure

Return 401 Unauthorized if authentication validation fails:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Invalid authentication credentials"
}

Server Error

Return 500 Internal Server Error for temporary processing issues (will trigger retry):

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": "Temporary processing error"
}

Note: Your API endpoint should respond within 30 seconds to avoid timeout errors. Implement asynchronous processing if your data handling requires more time.