Skip to content
Circadify Circadify Circadify

Quick Start

This guide walks you through the complete flow: signing up, creating an API key, installing the SDK, and running your first measurement.

Prerequisites

Section titled “Prerequisites”
  • Node.js 18+ and a package manager (npm, yarn, or pnpm)
  • A modern browser — Chrome 80+, Firefox 75+, Safari 14+, or Edge 80+
  • HTTPS — Required for camera access (localhost works for development)

Create Your Account

Section titled “Create Your Account”

  1. Sign up at developer.circadify.com

    Fill in your name, work email, company, and category. Your account will be submitted for review.

  2. Wait for approval

    Our team reviews new accounts and you’ll receive an email when approved. This typically takes less than 24 hours.

  3. Log in at developer.circadify.com/login

    Once approved, log in with your email and password to access the developer dashboard.

Create an API Key

Section titled “Create an API Key”

  1. Navigate to the Keys page in the dashboard sidebar.

  2. Click Create Key.

  3. Enter a name (e.g., “Development”) and select the environment:

    • Test — For development and testing (ck_test_*)
    • Live — For production use (ck_live_*)

  4. Copy your key immediately. It’s only shown once. You’ll see the key in this format:

    ck_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4

Install the SDK

Section titled “Install the SDK”

Install @circadify/sdk via your package manager. See Installation for full setup instructions, CDN options, and TypeScript configuration.

Terminal window
npm install @circadify/sdk

Run Your First Scan

Section titled “Run Your First Scan”

With built-in UI

Section titled “With built-in UI”

The SDK includes a scanning interface with a face guide overlay, progress indicators, and quality warnings. Just provide a container element:

<div id="scan-container" style="width: 400px; height: 300px;"></div>
import { CircadifySDK } from '@circadify/sdk';


const sdk = new CircadifySDK({
  apiKey: 'ck_test_your_key_here',
});


const result = await sdk.measureVitals({
  container: document.getElementById('scan-container'),
});


console.log('Heart Rate:', result.heartRate, 'BPM');
console.log('Confidence:', result.confidence);

Headless mode (no UI)

Section titled “Headless mode (no UI)”

If you want to build your own interface, omit the container option:

const sdk = new CircadifySDK({
  apiKey: 'ck_test_your_key_here',
  onProgress: (progress) => {
    console.log(`${progress.phase}: ${progress.percent}%`);
  },
});


const result = await sdk.measureVitals();

With demographics (optional)

Section titled “With demographics (optional)”

Providing user demographics improves measurement accuracy:

const result = await sdk.measureVitals({
  container: document.getElementById('scan-container'),
  demographics: {
    age: 35,
    sex: 'M',
  },
});

Reading Results

Section titled “Reading Results”

The measureVitals() call returns a VitalSignsResult object:

interface VitalSignsResult {
  heartRate: number;         // BPM (always present)
  hrv?: number;              // Heart rate variability (ms)
  respiratoryRate?: number;  // Breaths per minute
  spo2?: number;             // Blood oxygen saturation (%)
  systolicBp?: number;       // Systolic blood pressure (mmHg)
  diastolicBp?: number;      // Diastolic blood pressure (mmHg)
  confidence: number;        // 0–1 measurement reliability
  sessionId: string;         // Unique session identifier
  timestamp: number;         // Unix timestamp (ms)
}

A confidence score above 0.7 generally indicates a reliable measurement. Below 0.4 suggests the scan had quality issues (poor lighting, excessive movement, etc.).

Handle Errors

Section titled “Handle Errors”

Wrap your measurement call to handle common failure cases:

import { CircadifySDK, CircadifyError, CircadifyErrorCode } from '@circadify/sdk';


try {
  const result = await sdk.measureVitals({
    container: document.getElementById('scan-container'),
  });
} catch (error) {
  if (error instanceof CircadifyError) {
    switch (error.code) {
      case CircadifyErrorCode.CAMERA_PERMISSION_DENIED:
        console.error('Camera access was denied by the user.');
        break;
      case CircadifyErrorCode.QUOTA_EXCEEDED:
        console.error('Monthly scan quota exceeded. Upgrade your plan.');
        break;
      case CircadifyErrorCode.RATE_LIMITED:
        console.error('Too many requests. Try again shortly.');
        break;
      default:
        console.error('Scan failed:', error.message);
    }
  }
}

Cancel a Scan

Section titled “Cancel a Scan”

Use an AbortController to let users cancel mid-scan:

const controller = new AbortController();


// Wire up a cancel button
document.getElementById('cancel-btn').onclick = () => controller.abort();


try {
  const result = await sdk.measureVitals({
    container: document.getElementById('scan-container'),
    signal: controller.signal,
  });
} catch (error) {
  if (error instanceof CircadifyError && error.code === CircadifyErrorCode.CANCELLED) {
    console.log('Scan cancelled by user.');
  }
}

Clean Up

Section titled “Clean Up”

When you’re done with the SDK (e.g., component unmount), release resources:

sdk.destroy();

This stops any active camera streams, unloads WASM modules, and removes UI elements.

Test Your Key

Section titled “Test Your Key”

You can also validate your API key in the developer portal without writing any code. Go to the Test page, paste your key, and click Test Key. The portal will create a test session and show you the response.

Next Steps

Section titled “Next Steps”