Tracking verification progress

Every verification leaves a trail of telemetry events — the extension being installed, the consent screen being shown, notarization starting and finishing, your webhook being called. getTelemetryEvents returns that trail for one of your verifications, so you can see exactly how far a user got and where they dropped off.

Fetch the events

import { Vouch } from "@getvouch/sdk";

const vouch = new Vouch({
  customerId: "1be03be8-5014-413c-835a-feddf4020da2",
  apiKey: "your-api-key",
});

const { events } = await vouch.getTelemetryEvents({
  requestId: "8f14e45f-ceea-4a26-9c3f-1d0f4a3f9b21",
});

for (const event of events) {
  console.log(event.timestamp, event.eventType, event.origin);
}

The requestId is the one returned by getDataSourceUrl or getWidgetUrl.

Response shape

getTelemetryEvents resolves to { events }, ordered oldest first:

{
  "events": [
    {
      "eventType": "PROOF_REQUEST_CREATED",
      "timestamp": "2026-07-22T09:01:12.443Z",
      "origin": "Server",
      "metadata": { "datasourceId": "e37a1a02-3b6e-4f38-9f6d-2b1a5c7d9e00" }
    },
    {
      "eventType": "CONSENT_DISPLAYED",
      "timestamp": "2026-07-22T09:01:31.902Z",
      "origin": "Desktop",
      "metadata": {
        "datasourceId": "e37a1a02-3b6e-4f38-9f6d-2b1a5c7d9e00",
        "geolocation": { "country": "PL", "city": "Warsaw" }
      }
    },
    {
      "eventType": "NOTARIZATION_FINISHED",
      "timestamp": "2026-07-22T09:02:41.008Z",
      "origin": "Desktop",
      "metadata": {
        "datasourceId": "e37a1a02-3b6e-4f38-9f6d-2b1a5c7d9e00"
      }
    }
  ]
}

eventType

What happened. The full set is listed in Event types below, and is exported as the TelemetryEventType union so your editor will autocomplete it:

import type { TelemetryEventType } from "@getvouch/sdk";

New event types are added over time. Switch on the ones you care about and ignore the rest rather than matching exhaustively, so a new event never breaks your integration.

timestamp

ISO 8601 UTC string recording when the event was captured.

origin

Which side emitted the event — "Desktop", "Android", "iOS", "Server", or "Unknown". Useful for telling a desktop-extension run apart from a mobile-app run.

metadata

Extra details attached to the event. Which keys are present depends on eventType, and every one of them is optional — a widget-created verification, for example, emits its first events before a data source has been chosen, so even datasourceId is absent there. Treat the whole object as optional and read keys defensively rather than assuming any one exists.

Only these keys are ever returned:

Everything else your end user's device reports — their IP address and coordinates, user agent, device model and OS, session identifiers, and the URL of the page they were on — is held back and never leaves Vouch through this API.

Event types

Not every verification produces every event — which ones you see depends on the device, the data source, and how far the user got. Events marked → status are the ones that move the verification's status.

Desktop

Emitted by the browser and the Vouch Verifier extension while the user is on desktop.

Mobile web

Emitted by a mobile browser, before any app takes over.

Mobile app

Emitted by the Vouch Verifier mobile app.

Processing

Emitted while the extension or app is on the target site, capturing the data to notarize.

Notarization

Emitted from both desktop and mobile as the proof is generated.

Server

Emitted by Vouch's backend.

Video verification

Only present on video verifications.

Limits

A timeline is capped at the 1000 most recent events. Long proving sessions emit progress events continuously, so if a run exceeds the cap the oldest events are dropped and the newest — the ones that explain where it ended up — are kept.

Common uses

• Diagnosing a stuck verification — find the last event to see where the user stopped.
• Drop-off analysis — compare how many requests reach CONSENT_DISPLAYED versus NOTARIZATION_FINISHED.
• Support — when a user reports a failure, the timeline shows whether they ever installed the extension or opened the app.