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.

Calling the API directly

The SDK method wraps a single HTTP call, so a backend in any language can fetch the same timeline without the JS SDK:

curl https://app.getvouch.io/api/proof-request/8f14e45f-ceea-4a26-9c3f-1d0f4a3f9b21/telemetry-events \
  -H "Authorization: Bearer your-api-key"

GET /api/proof-request/{requestId}/telemetry-events authenticates with your API key as a bearer token and returns the same { events } body described below.

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.

Interpreting a timeline

The shape of a successful run

A desktop extension run that completes looks like this — mobile runs swap the extension events for the APP_OPENED / REDIRECT ones, and first-time users get INSTALL_EXTENSION / EXTENSION_INSTALLED before step 3:

1. PROOF_REQUEST_CREATED — the verification was issued.
2. CONSENT_DISPLAYED — the user opened the link and saw what will be shared.
3. EXTENSION_OPEN — the extension took over.
4. PROCESSING_NEW_PAGE (repeated) — the user signs in and navigates the target site.
5. REQUEST_MATCHED — the data being verified was captured.
6. NOTARIZATION_STARTED → NOTARIZATION_FINISHED — the proof was generated.
7. WEBPROOF_POSTED — the proof reached Vouch; the verification is successful.
8. WEBHOOK_SUCCESS — your webhook received the result.

A struggling timeline is this sequence cut short — whatever milestone is missing is the stage the user never reached.

Where did the user stop?

For a single stuck or abandoned verification, find the last event and read it against this table:

When the trail just stops, the events immediately before the end record how the user left: USER_NAVIGATED_AWAY, PROVING_TAB_CLOSED, and APP_WENT_TO_BACKGROUND.

Measuring drop-off

To see where users are lost across many verifications rather than one, count how many timelines reach each of these milestones:

1. PROOF_REQUEST_CREATED — the verification was issued.
2. CONSENT_DISPLAYED — the user opened the verification link.
3. First PROCESSING_NEW_PAGE — the user reached the site being verified.
4. NOTARIZATION_STARTED — the data was captured and proof generation began.
5. WEBPROOF_POSTED — the verification succeeded.

Each gap points at a different problem: losses between 2 and 3 are consent refusals or install/handoff friction, losses between 3 and 4 are users failing to sign in or find their data on the target site, and losses between 4 and 5 are technical failures — check those timelines for NOTARIZATION_ERROR, UPLOAD_ERROR, and PROCESSING_TIMEOUT.