Smile Simulation Data API

The Smile Simulation Data API allows you to send smile simulation data including patient information and image results. All smile simulation data is processed through HiQOR's AWS environment. HiQOR securely ingests, processes, and makes results available through structured API responses.

Data Format

HiQOR processes smile simulation data using camelCase formatting for standardization. While HiQOR enforces a structured data model, we support flexible formatting options to accommodate client needs. For specific format requests, contact our API team at api@hiqor.com.

Send Non-Sensitive Data (PII)

The endpoint for sending non-sensitive patient data:

POST /hiqorSmile?dataType=non-sensitive

Send Sensitive Data (Image Data)

The endpoint for sending sensitive image data:

POST /hiqorSmile?dataType=sensitive

Required Fields

The following fields are required for all API calls:

  • assessmentType (must be "Smile Simulator")
  • funnelID
  • email
  • patientUUID

Request Body

The request body will vary depending on whether you're sending non-sensitive or sensitive data. Note that while we process data in camelCase, our API can accept various formats in the request body.

Non-Sensitive Data Example

{
  "patientUUID": "c2049a43-77f2-4a55-973d-9f757fa7013",
  "assessmentType": "Smile Simulator",
  "funnelID": "hiqor",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "555-123-4567",
  "zip": "12345",
  "location": "My Location",
  "consent": "true",
  "resultsLink": "https://smilesimulator.co/viewmyresults/c2049a43-77f2-4a55-973d-9f757fa7013"
}

Sensitive Data Example

{
  "patientUUID": "c2049a43-77f2-4a55-973d-9f757fa7013",
  "assessmentType": "Smile Simulator",
  "funnelID": "hiqor",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "555-123-4567",
  "zip": "12345",
  "location": "My Location",
  "consent": "true",
  "resultsLink": "https://smilesimulator.co/viewmyresults/c2049a43-77f2-4a55-973d-9f757fa7013",
  "imageData": {
    "originalImageURL": "s3://hiqor-aws/originals/user123.jpg",
    "simulatorResults": {
      "whiteningBefore": "s3://hiqor-aws/whitening/before.jpg",
      "whiteningAfter": "s3://hiqor-aws/whitening/after.jpg",
      "orthodonticBefore": "s3://hiqor-aws/ortho/before.jpg",
      "orthodonticAfter": "s3://hiqor-aws/ortho/after.jpg"
    }
  }
}

Field Descriptions

The following describes the fields used in both non-sensitive and sensitive data submissions.

  • patientUUID: Unique identifier for the patient
  • assessmentType: Must be "Smile Simulator"
  • funnelID: Identifier for routing processed data (Non-Sensitive Data Only)
  • firstName, lastName: Patient's name (Non-Sensitive Data Only)
  • email: Patient's email address (Non-Sensitive Data Only)
  • phone: Patient's phone number (Non-Sensitive Data Only)
  • zip: Patient's zip code (Non-Sensitive Data Only)
  • location: Practice or location identifier (Non-Sensitive Data Only)
  • consent: Patient consent status (Non-Sensitive Data Only)
  • imageData: Contains original image URL and simulation results
  • resultsLink: URL where patient can view their results and can be passed to patient via SMS

Image Data Structure

The imageData object contains the original image and simulation results:

  • originalImageURL: S3 URL of the original uploaded image
  • simulatorResults: Object containing before/after images for different treatments:
    • whiteningBefore/After: Teeth whitening simulation images
    • orthodonticBefore/After: Orthodontic treatment simulation images

UUID Handling

The UUID serves as a unique identifier for each patient's smile simulation session. Our system processes incoming data as follows:

  • If a patientUUID is provided along with assessmentType "Smile Simulator", we check for an existing record.
  • If a match is found, we update the existing record instead of creating a new one.
  • If no matching record exists, we proceed with creating a new smile simulation record.
  • If data is received with only an email (without a UUID), we check whether an existing record exists for that email under the same assessmentType.
  • If found, we update the existing record.
  • If not, we create a new smile simulation record.

This process ensures that smile simulation data remains accurate and up-to-date while preventing unnecessary record duplication.

Data Separation Workflow

Our API employs a data separation workflow to handle Personally Identifiable Information (PII) and sensitive image data separately. This approach enhances security and compliance.

  • Non-sensitive data (PII) is sent via the /hiqorSmile?dataType=non-sensitive endpoint.
  • Sensitive image data is sent via the /hiqorSmile?dataType=sensitive endpoint.
  • The patientUUID is used to link the non-sensitive data with the corresponding sensitive image data.

Example Response

{
  "message": "Smile simulation data received successfully",
  "patientUUID": "c2049a43-77f2-4a55-973d-9f757fa7013"
}

Receiving Processed Data

After sending smile simulation data, HiQOR will process it and route it based on the funnelID. You will receive the processed results via webhooks or SNS subscriptions.

To receive these results, you need to:

  1. Set up a webhook endpoint on your server to receive the processed data
  2. Or, set up an SNS subscription to receive notifications when new data is available

Contact our API team at api@hiqor.com to set up your webhook or SNS subscription and discuss any specific data format requirements for outgoing data.

Validation Rules

The API includes validation rules to ensure data integrity and security. You may encounter the following validation errors:

Invalid Funnel ID

If the provided funnelID is not valid or recognized:

{
  "message": "Invalid Client"
}

Missing or Invalid Data Type

If the dataType parameter is missing or invalid:

{
  "message": "Invalid data type. Use 'non-sensitive' or 'sensitive'"
}

Invalid Assessment Type

If the assessmentType is not "Smile Simulator":

{
  "message": "Invalid assessment type. Must be 'Smile Simulator'"
}

Note: All requests to the Smile Simulation Data API require authentication. Make sure to include the Authorization header with a valid token, prefixed with "Bearer ".