Migrating from V1 to V2

Intro

Welcome to the latest version of IntelliProve!
Our V2 API unlocks powerful new features and improvements. If you’re familiar with IntelliProve’s V1 API, upgrading to V2 will be straightforward—this guide walks you through what’s new and how to make the switch.

What’s new

• ✨ A new look and improved experience: Enjoy an entirely new interface and UX during the Face Scan, including live results, dynamic progressbar, a smart assistant to guide users and personalized user-inputs to finetune the health insights. Learn more about the new experience →
• 🧠 Smarter insights: Insights now take into account more of the user’s personal profile, including age and sex, making them much more personalized, engaging and smart.
  Read about Health Insights →
• 🧩 IntelliWidgets: Easiliy embed ready-made health insight tiles in your app’s existing pages, including heart rate, respiratory rate and many more.
  Explore Widgets →.

Core Concepts in the V2 API

Let’s recap a few concepts. Not all of these are new, but they’re now more formalized and used more consistenlty throughout the API, so it’s good to do a refresher.

1. User: Represents an individual end user. Each user is created once and assigned a unique User ID, which is used to track Face Scans and health insights.
   ➡️ This replaces the older concepts of patient and performer.
   You’ll use the User ID to access all health-related data.
2. Face Scan: A single video-based scan performed by the user. Each scan has a unique Face Scan ID.Read more about the Face Scan →.
3. Biomarkers: Objective measurements from a single Face Scan (e.g., heart rate, respiratory rate).
4. Read more about the Biomarkers →.
5. Metrics: Insights derived from analyzing multiple scans over time. These are grouped into a User Health Profile.
   Read more about the Metrics →.

Upgrading to V2

The overall approach is familiar:
You request a URL from our API, embed the plug-in in an iframe, and receive results either in the UI or via the API.

What’s new in V2?

• Updated API structure: Endpoints reflect the new concepts introduced in V2.
• Explicit user creation: Users must be registered before a plug-in session is initiated.
• User-linked sessions: Each plug-in session is now associated with a specific user ID.

Upgrade Flow

• Creating the user
  Add an API call to register the user (if it’s their first scan and they haven’t been registered yet). Provide a unique User ID. This ID will also be used to retrieve health insights later.
• Request the plug-in URL: Use the User ID to obtain the URL through the new API endpoint.
• Embed the plug-in: Use the returned URL in your frontend, as before.
• (Optional) Request health insights via the API: Once the scan is complete, retrieve biomarker results through a separate API call. Retrieve Metrics at any point using the user’s user ID. Refer to the section below on how to keep the result format compatible with what you have today.

📘 Full setup instructions—including API references—can be found in our Getting Started guide.

→ Go to the Getting Started guide

Compatibility with V1 results format

If you want to keep using the existing V1 results format (e.g. for backward compatibility in your frontend or data pipeline), you can continue using the legacy results endpoint below. This allows you to adopt the new V2 plug-in for Face cans, while keeping your business logic unchanged. You can migrate to the new results format when ready.

Get Face Scan Biomarkers

GEThttps://engine.intelliprove.com/v2/face_scans/:face_scan_id/legacy

Get Biomarkers for a specific Face Scan, using the Face Scan ID.

Path parameters

face_scan_idString

required

Face Scan UUID

Header parameters

Authorizationstring

required

User action token obtained using the 'Create user action token' endpoint, with added "Token "-prefix

Response

200

{
  "face_scan_id": "ea6785c1-6ec6-494f-a87e-97362f55580a",
  "heart_rate": 65,
  "respiratory_rate": 15,
  "heart_rate_variability": 95,
  "resonant_breathing_score": 0,
  "ans_balance": 1,
  "morning_readiness": 8,
  "acute_mental_stress_score": 5,
  "mental_health_risk": null,
  "timestamp_epoch": 1742978680,
  "timestamp": "2025-03-26T09:44:40.078954+01:00"
}