Quickstart Guide

This guide will help you make your first API call to HiQOR Smile Simulator API. We'll walk through the smile simulation data submission process.

Step 1: Obtain an API Key

Before you can make API calls, you need to obtain an API key. If you haven't already, please contact our API team at api@hiqor.com to get your API key.

Step 2: Authenticate

Use your API key to obtain an authentication token. Send a POST request to the authentication endpoint:

curl -X POST https://7hh4csiioi.execute-api.us-west-2.amazonaws.com/default/hiqorSmile/authenticate \
-H "Content-Type: application/json" \
-d '{
"username": "your_username",
"password": "your_api_key"
}'

The response will contain your authentication token. You'll need this for subsequent API calls. The response will look like this:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Step 3: Send Non-Sensitive Data (PII)

You can send smile simulation data including patient information using the following endpoint:

curl -X POST https://7hh4csiioi.execute-api.us-west-2.amazonaws.com/default/hiqorSmile?dataType=non-sensitive \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" \
-H "Content-Type: application/json" \
-d '{
  "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"
}'

Replace the token in the Authorization header with the one you received in Step 2, and use appropriate values for the smile simulation data.

Step 4: Send Sensitive Data (Image Data)

You can send smile simulation image data using the following endpoint:

curl -X POST https://7hh4csiioi.execute-api.us-west-2.amazonaws.com/default/hiqorSmile?dataType=sensitive \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" \
-H "Content-Type: application/json" \
-d '{
  "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"
    }
  }
}'

Step 5: 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:

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

Response

When you send smile simulation data, you'll receive a confirmation response:

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

Important Notes

Two API calls are required and should be made in sequence.
Always include the dataType query parameter as "non-sensitive" or "sensitive"
Ensure your authentication token is valid and included in all requests
The assessmentType must be "Smile Simulator"
All required fields must be included in the payload
Image URLs should point to valid S3 locations

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