Proctoring that stands up to scrutiny.

Overview

There are two halves, and most customers use both for the same candidate.

They join on one identifier. You mint a session before the exam, pass its id to the SDK, and send the same session id when you submit the recording. That is what puts both halves in one report. It is also the step people miss most often.

What a finding is, and what it is not

The same care is needed with the recorded analysis, though a little less. A looking-away interval means our model measured that the candidate looked away from the screen for a while. It does not mean they were reading something. That is why every finding carries a proof_frame, so a person can look at the image and decide.

Build your flow so that a finding sends the interview to a human reviewer, instead of failing the candidate on its own. Anything else is a decision you will not be able to defend if someone challenges it.

Quickstart

A working integration is three calls. Everything else is detail.

1. Mint a session on your server

   This is the only endpoint you must build against. It returns a short-lived token scoped to one candidate and one page.

   Copy

   curl -X POST $INCPROC_BASE/api/v1/proctoring/browser/sessions \
     -H "X-API-Key: $INCPROC_KEY" \
     -H "X-API-Secret: $INCPROC_SECRET" \
     -H "Content-Type: application/json" \
     -d '{
       "origin": "https://exams.yourcompany.com",
       "reference_id": "candidate-4821",
       "capabilities": ["events", "evidence"],
       "ttl_seconds": 7200
     }'

   const BASE = process.env.INCPROC_BASE   // given to you with your keys
   
   const res = await fetch(
     `${BASE}/api/v1/proctoring/browser/sessions`,
     {
       method: 'POST',
       headers: {
         'X-API-Key': process.env.INCPROC_KEY,
         'X-API-Secret': process.env.INCPROC_SECRET,
         'Content-Type': 'application/json',
       },
       body: JSON.stringify({
         origin: 'https://exams.yourcompany.com',
         reference_id: 'candidate-4821',
         capabilities: ['events', 'evidence'],
         ttl_seconds: 7200,
       }),
     }
   )
   
   const { data } = await res.json()
   // Hand data.session_id + data.session_token to the browser. Nothing else.

   import os, requests
   
   BASE = os.environ["INCPROC_BASE"]   # given to you with your keys
   
   res = requests.post(
       f"{BASE}/api/v1/proctoring/browser/sessions",
       headers={
           "X-API-Key": os.environ["INCPROC_KEY"],
           "X-API-Secret": os.environ["INCPROC_SECRET"],
       },
       json={
           "origin": "https://exams.yourcompany.com",
           "reference_id": "candidate-4821",
           "capabilities": ["events", "evidence"],
           "ttl_seconds": 7200,
       },
       timeout=30,
   )
   session = res.json()["data"]

   $base = getenv('INCPROC_BASE');   // given to you with your keys
   
   $ch = curl_init($base . '/api/v1/proctoring/browser/sessions');
   curl_setopt_array($ch, [
       CURLOPT_POST           => true,
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_HTTPHEADER     => [
           'X-API-Key: ' . getenv('INCPROC_KEY'),
           'X-API-Secret: ' . getenv('INCPROC_SECRET'),
           'Content-Type: application/json',
       ],
       CURLOPT_POSTFIELDS => json_encode([
           'origin'       => 'https://exams.yourcompany.com',
           'reference_id' => 'candidate-4821',
           'capabilities' => ['events', 'evidence'],
           'ttl_seconds'  => 7200,
       ]),
   ]);
   $session = json_decode(curl_exec($ch), true)['data'];

   var body = """
       {"origin":"https://exams.yourcompany.com",
        "reference_id":"candidate-4821",
        "capabilities":["events","evidence"],
        "ttl_seconds":7200}
       """;
   
   var request = HttpRequest.newBuilder()
       .uri(URI.create(System.getenv("INCPROC_BASE")
           + "/api/v1/proctoring/browser/sessions"))
       .header("X-API-Key", System.getenv("INCPROC_KEY"))
       .header("X-API-Secret", System.getenv("INCPROC_SECRET"))
       .header("Content-Type", "application/json")
       .POST(HttpRequest.BodyPublishers.ofString(body))
       .build();
   
   var response = HttpClient.newHttpClient()
       .send(request, HttpResponse.BodyHandlers.ofString());

   origin must exactly match the page the exam is served from. The token is bound to it and refused anywhere else — and the 401 the browser gets does not explain why. https://exams.yourcompany.com and https://exams.yourcompany.com/ are the same; http:// and a different subdomain are not.

   It must be https://. The only exception is localhost and 127.0.0.1, so local development still works. This is not our rule. The browser's own camera and screen-share APIs (getUserMedia, getDisplayMedia) only work on a secure page, so the SDK could never have run on plain http. So an http:// origin fails straight away with 422 VALIDATION_FAILED, instead of working here and then breaking later in the browser. A staging site on plain http will not work — put a certificate on it, or point origin at http://localhost while developing.

   If your account is restricted to specific domains, mint fails with 422 until the origin is on that list. The message says so:

   {
     "error": {
       "code": "VALIDATION_FAILED",
       "message": "Origin https://exams.yourcompany.com is not permitted to host a
                   proctoring session on this deployment. Contact support to have
                   it added."
     }
   }

   This is switched on per account. Most accounts do not have it, and any origin works as soon as your keys are issued. It is worth asking for, because it means a leaked key cannot create sessions from someone else's page and spend your credits. If your account does have it, every domain you mint from must be registered first, including staging and preview URLs.

   Ask your account manager which applies to you before you start, and send the full list of domains at once. It is the one thing that can stop your very first call from working, and the error message is the only place you will see it.

2. Start the SDK in the candidate's browser

   Pass the minted session straight through. The SDK handles token refresh, batching and reconnection on its own.

   Copy

   npm install @incproctor/proctoring-sdk

   import { createProctoringSession } from '@incproctor/proctoring-sdk'
   
   // `session` is exactly what your server received in step 1.
   const proctoring = createProctoringSession({
     baseUrl: INCPROC_BASE,   // the same base URL your server uses
     session,
     camera:   { enabled: true, required: false },
     evidence: { enabled: true, intervalSec: 15, sources: ['camera'], maxDimension: 640 },
   })
   
   await proctoring.start()
   
   // When the candidate clicks "Finish" — this is what closes the session cleanly.
   await proctoring.stop()

   <script src="https://cdn.jsdelivr.net/npm/@incproctor/proctoring-sdk"></script>
   <script>
     const proctoring = InCruiterProctoring.createProctoringSession({
       baseUrl: INCPROC_BASE,
       session: MINTED_SESSION,
       camera: { enabled: true, required: false },
     })
     proctoring.start()
   </script>

   Never put your API key or secret in the browser. That credential reads every report your account has ever produced. Only the minted session_token belongs client-side — it expires, and it only works for one candidate on one origin.

3. Submit the recording when the interview ends

   Send the same session_id from step 1. That is what merges the live signals and the recorded analysis into one report.

   Copy

   curl -X POST $INCPROC_BASE/api/v1/proctoring/video/analyze \
     -H "X-API-Key: $INCPROC_KEY" \
     -H "X-API-Secret: $INCPROC_SECRET" \
     -H "Content-Type: application/json" \
     -d '{
       "file_url":      "https://your-storage/recordings/abc.mp4",
       "start_time":    "2026-09-14T10:00:00",
       "end_time":      "2026-09-14T10:45:00",
       "room_id":       "room-4821",
       "interview_id":  "interview-4821",
       "session_id":    "pbs_XXXXXXXXXXXXXXXX",
       "call_back_url": "https://yourcompany.com/hooks/proctoring"
     }'

   await fetch(`${BASE}/api/v1/proctoring/video/analyze`, {
     method: 'POST',
     headers: {
       'X-API-Key': process.env.INCPROC_KEY,
       'X-API-Secret': process.env.INCPROC_SECRET,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       file_url:      recordingUrl,       // must be reachable by us
       start_time:    '2026-09-14T10:00:00',
       end_time:      '2026-09-14T10:45:00',
       room_id:       'room-4821',
       interview_id:  'interview-4821',
       session_id:    session.session_id, // ← the id from step 1
       call_back_url: 'https://yourcompany.com/hooks/proctoring',
     }),
   })

   requests.post(
       f"{BASE}/api/v1/proctoring/video/analyze",
       headers={
           "X-API-Key": os.environ["INCPROC_KEY"],
           "X-API-Secret": os.environ["INCPROC_SECRET"],
       },
       json={
           "file_url":      recording_url,
           "start_time":    "2026-09-14T10:00:00",
           "end_time":      "2026-09-14T10:45:00",
           "room_id":       "room-4821",
           "interview_id":  "interview-4821",
           "session_id":    session["session_id"],   # the id from step 1
           "call_back_url": "https://yourcompany.com/hooks/proctoring",
       },
       timeout=30,
   )

   We call your call_back_url when the report is ready. Do not poll — see Webhooks.

Authentication

Base URL

Every example on this page reads the base URL from INCPROC_BASE. There is one per environment, and your account manager gives it to you with your keys. Keep it in your configuration instead of writing it into the code. The value is different for test and for production, and a fixed value in the source is how test traffic ends up hitting production.

export INCPROC_BASE="https://…"        # from your account manager
export INCPROC_KEY="pk_…"
export INCPROC_SECRET="sk_…"

Your keys

You receive a key pair when your account is set up. There is nothing to request and nothing to configure — the pair arrives with your base URL, from your InCruiter account manager.

Every server-to-server call carries both, as headers.

You are given a separate pair for each environment. A key made for one will not work on another. That is on purpose: it is what stops a test integration from reaching production data.

Live browser proctoring

Once start() is called, the SDK reports these on its own. You do not wire them up.

What the log looks like

One session produces one report. Fetch it with your API key once the exam has ended:

curl -sS "$INCPROC_BASE/api/v1/proctoring/browser/sessions/$SESSION_ID/report" \
  -H "X-API-Key: $INCPROC_KEY" -H "X-API-Secret: $INCPROC_SECRET"

An 18-minute sitting, abbreviated — the candidate settled in, lost focus twice, left the exam tab twice and dropped out of fullscreen once:

{
  "session": {
    "session_id":   "pbs_XXXXXXXXXXXXXXXX",
    "reference_id": "candidate-4821-attempt-1",   // your id, not ours
    "state":        "ended",
    "end_reason":   "ended_by_client",
    "metadata":     { "exam": "backend-engineer-l3" },
    "events_received": 18, "evidence_received": 4
  },

  "counts": {
    "events": 18, "evidence": 4,
    "by_type":     { "tab_hidden": 2, "window_blur": 3, "fullscreen_exited": 1, ... },
    "by_severity": { "high": 3, "medium": 3, "low": 12 }
  },

  "events": [
    { "type": "session_started",      "severity": "low",    "elapsed_ms": 0,       ... },
    { "type": "environment_reported", "severity": "low",    "elapsed_ms": 1000,
      "detail": { "system": { "os": "Windows", "browser": "chrome",
                              "browser_version": "140", "screen": "1920x1080",
                              "trust": "self_reported" } } },
    { "type": "screen_share_started", "severity": "low",    "elapsed_ms": 4000,    ... },

    { "event_id":   "evt_008185uej",
      "type":       "tab_hidden",                 // left the exam tab
      "severity":   "high",                       // assigned by us, never by the browser
      "occurred_at": "2026-09-21T11:34:31.122Z",  // the candidate's clock
      "received_at": "2026-09-21T11:51:39.510Z",  // ours
      "elapsed_ms":  292000,                      // 04:52 into the exam
      "detail":     { "reason": "visibilitychange" },
      "trust":      "advisory" },

    { "type": "tab_visible",      "severity": "low",  "elapsed_ms": 305000,
      "detail": { "away_ms": 13000 } },           // how long they were gone
    { "type": "fullscreen_exited", "severity": "high", "elapsed_ms": 688000, ... },
    { "type": "session_stopped",   "severity": "low",  "elapsed_ms": 1080000,
      "detail": { "reason": "completed" } }
  ],

  "evidence": [
    { "event_id":     "shot_019a7h8qe",
      "kind":         "screen",
      "captured_at":  "2026-09-21T11:30:09.122Z",
      "content_type": "image/jpeg",
      "size_bytes":   10457,
      "sha256":       "22d64404fcb6f8e44e486d149b6d6d62…" }
  ],

  "trust": "advisory",
  "trust_note": "Browser events and screenshots are produced by JavaScript on the candidate's
                 own machine and can be suppressed or fabricated…",
  "generated_at": "2026-09-21T11:51:40.363Z"
}

Each frame in evidence is fetched by its event_id, and comes back as an image rather than JSON:

GET $INCPROC_BASE/api/v1/proctoring/browser/sessions/$SESSION_ID/evidence/$EVENT_ID
→ 200 image/jpeg

Ending the session

Call stop() when the candidate finishes. It sends anything still waiting in the queue and closes the session. If the tab just closes, we notice and close the session ourselves. Calling stop() is still better: it is cleaner, and it settles the credit sooner.

Recorded interview analysis

Send a finished recording and we return findings in three groups. Each one comes with a proof frame — the actual image the finding was made from.

Required fields

Fetching the report

When the webhook tells you a job is completed, fetch it with your API key:

curl "$INCPROC_BASE/api/v1/proctoring/video/results/$JOB_ID" \
  -H "X-API-Key: $INCPROC_KEY" -H "X-API-Secret: $INCPROC_SECRET"

What comes back

Findings are grouped by kind. Each interval carries the window, the proof frame, and how strong the signal was.

{
  "job_id": "db8a2b36-8808-4135-aefb-c33b0102a498",
  "roomId": "room-4821",

  "proctoring_summary": {

    "looking_away_intervals": [
      {
        "start":        "2026-09-14T10:04:12",
        "end":          "2026-09-14T10:04:19",
        "duration_sec": 7,
        "proof_frame":     "data:image/jpeg;base64,…",   // or an https URL
        "proof_timestamp": "2026-09-14T10:04:15",
        "evidence_score":  0.7412,
        "source":          "AI"
      }
    ],

    "face_issue_intervals": [
      {
        "start":        "2026-09-14T10:00:24",
        "end":          "2026-09-14T10:00:29",
        "duration_sec": 5,
        "faces":        0,                 // 0 = nobody, 2+ = more than one person
        "face_status":  "absent",          // absent | multiple | partial
        "proof_frame":     "…",
        "proof_timestamp": "2026-09-14T10:00:28",
        "evidence_score":  1.0,
        "source":          "AI"
      }
    ],

    "device_intervals": [
      {
        "start":        "2026-09-14T10:02:41",
        "end":          "2026-09-14T10:02:49",
        "duration_sec": 8,
        "item":         "additional screen",   // or "mobile phone"
        "proof_frame":     "…",
        "proof_timestamp": "2026-09-14T10:02:46",
        "evidence_score":  0.7188,
        "source":          "AI"
      }
    ],

    "drowsiness_percent": 6.79
  },

  // One row per analysed frame — the raw measurements the intervals above are
  // summarised from. Thousands of rows on a real interview.
  "frames": [
    { "frame": "frame_00001.jpg", "timestamp": "2026-09-14T10:00:00",
      "faces": 1, "gaze_h": 0.0, "gaze_v": 0.0, "looking_away_abs": false,
      "face_partial": false, "person_present": true,
      "objects": [], "drowsiness_yawn": { "is_drowsy": false, "is_yawning": false } }
  ]
}

Webhooks

We call you when a report is ready. This is the part worth reading twice.

What we send

The body is deliberately thin — identifiers and a status, never candidate data. A webhook body lands in log stores that are read far more widely than a database.

POST https://yourcompany.com/hooks/proctoring

webhook-id:        msg_2f8a91c4e7
webhook-timestamp: 1789385412
webhook-signature: v1,K8xW2pQ...

{
  "jobId":       "ea62cfe5-0b75-44c4-badf-27da5d8aa95e",
  "sessionId":   "pbs_XXXXXXXXXXXXXXXX",
  "roomId":      "room-4821",
  "interviewId": "interview-4821",
  "status":      "completed"
}

Then fetch the full report with your API key, over a channel you control.

Every status you can receive

Branch on status. A handler written for only the happy path will sit waiting for a report that is never coming.

{
  "jobId":       "ea62cfe5-0b75-44c4-badf-27da5d8aa95e",
  "sessionId":   "pbs_XXXXXXXXXXXXXXXX",
  "roomId":      "room-4821",
  "interviewId": "interview-4821",
  "status":      "failed",
  "reason":      "could not download the recording"
}

Verifying the signature

We follow the Standard Webhooks specification. Verify every request before you act on it — the endpoint is public, and anyone can POST to it.

The signed string is exactly {webhook-id}.{webhook-timestamp}.{raw body}.

import crypto from 'node:crypto'

export function verify(rawBody, headers, secret) {
  const id   = headers['webhook-id']
  const ts   = headers['webhook-timestamp']
  const sigs = headers['webhook-signature']
  if (!id || !ts || !sigs) return false

  // Reject anything older than 5 minutes — this is what stops a captured
  // request being replayed at you later.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
  const expected = 'v1,' + crypto
    .createHmac('sha256', key)
    .update(`${id}.${ts}.${rawBody}`)   // rawBody — NOT JSON.stringify(parsed)
    .digest('base64')

  // The header may carry several space-separated signatures during a rotation.
  return sigs.split(' ').some((candidate) =>
    crypto.timingSafeEqual(
      crypto.createHash('sha256').update(candidate).digest(),
      crypto.createHash('sha256').update(expected).digest()
    )
  )
}

import base64, hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    wid = headers.get("webhook-id")
    ts  = headers.get("webhook-timestamp")
    sigs = headers.get("webhook-signature")
    if not (wid and ts and sigs):
        return False

    # Reject anything older than 5 minutes.
    if abs(time.time() - int(ts)) > 300:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{wid}.{ts}.{raw_body.decode()}".encode()
    expected = "v1," + base64.b64encode(
        hmac.new(key, signed, hashlib.sha256).digest()
    ).decode()

    return any(hmac.compare_digest(c, expected) for c in sigs.split(" "))

function verify(string $rawBody, array $headers, string $secret): bool {
    $id  = $headers['webhook-id']        ?? null;
    $ts  = $headers['webhook-timestamp'] ?? null;
    $sig = $headers['webhook-signature'] ?? null;
    if (!$id || !$ts || !$sig) return false;

    if (abs(time() - (int) $ts) > 300) return false;

    $key = base64_decode(preg_replace('/^whsec_/', '', $secret));
    $expected = 'v1,' . base64_encode(
        hash_hmac('sha256', "$id.$ts.$rawBody", $key, true)
    );

    foreach (explode(' ', $sig) as $candidate) {
        if (hash_equals($expected, $candidate)) return true;
    }
    return false;
}

boolean verify(String rawBody, Map<String, String> headers, String secret)
        throws Exception {
    String id = headers.get("webhook-id");
    String ts = headers.get("webhook-timestamp");
    String sigs = headers.get("webhook-signature");
    if (id == null || ts == null || sigs == null) return false;

    if (Math.abs(System.currentTimeMillis() / 1000 - Long.parseLong(ts)) > 300)
        return false;

    byte[] key = Base64.getDecoder()
        .decode(secret.replaceFirst("^whsec_", ""));
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(key, "HmacSHA256"));
    String expected = "v1," + Base64.getEncoder().encodeToString(
        mac.doFinal((id + "." + ts + "." + rawBody).getBytes(UTF_8)));

    for (String candidate : sigs.split(" ")) {
        if (MessageDigest.isEqual(
                expected.getBytes(UTF_8), candidate.getBytes(UTF_8))) return true;
    }
    return false;
}

Responding

Return 2xx as soon as you have stored the message. Do the work afterwards — a slow handler looks like a failure and will be retried. Anything non-2xx is retried with exponential backoff.

Treat delivery as at-least-once: the same webhook-id can arrive twice. Store it and ignore repeats.

Credits & billing

One interview costs one credit — and only if it actually happened.

Why a hold, and not a charge-then-refund

Two reasons. A hold fails at the door: a client with one credit cannot start a thousand exams and find out a day later that the work is unbillable. And nothing appears on your statement for an interview that never completed — no 1000 → 999 → 1000.

Check your balance any time:

curl $INCPROC_BASE/api/v1/credits/me \
  -H "X-API-Key: $INCPROC_KEY" -H "X-API-Secret: $INCPROC_SECRET"

Errors

Every error carries a machine-readable code and a request_id. Log the request_id — quoting it to support is the difference between a minute and an afternoon.

{
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "X-API-Key and X-API-Secret are required."
  },
  "request_id": "req_491581f1a4034fb2a9a5e5dc306eff05"
}

Every code you can receive

Branch on code, not on the message. A message gets reworded; a code does not. These are stable — a new one may be added, but an existing one is never renamed or repurposed.

A validation failure carries the offending fields, which is what you map back to your own form or job record:

{
  "success": false,
  "request_id": "req_b38bad220b2d42899533663685070582",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request body did not validate.",
    "details": {
      "fields": [
        { "field": "origin", "error": "origin must be https:// — getUserMedia and getDisplayMedia require a secure context, so the SDK cannot run on plain http outside localhost." }
      ]
    }
  }
}

Rate limits

Three separate ceilings. You will only ever design against the first.

A short burst above the limit is tolerated before 429 is returned. These are defaults; if your volume needs more, ask your account manager rather than working around them.

The two per-session limits exist so one candidate's browser cannot flood the account. The SDK queues and backs off on its own; you do not handle them.

Pagination

The list endpoints take a limit, newest first.

Versioning & changes

The REST API is versioned in the path: /api/v1/…. The browser SDK follows semantic versioning.

A breaking change means a new path version, and v1 would be supported alongside it for an agreed period — confirm the notice period in your contract; it is not set by this page.

For the SDK, pin a major version. A minor upgrade will not change the shape of anything you already use.

Limits & retention

Next