Verdict Schema

In one sentence

The verdict your backend reads is a country, a confidence, an alarm level, and a coarse location region — and nothing about how they were derived.

Success response

Returned by GET /v1/verdict/{sessionRef} once a verdict is ready:

{
  "country": "DE",
  "confidence": 0.91,
  "alarm": "none",
  "estimatedLocation": { "lat": 52.52, "lon": 13.40 },
  "confidenceRadiusKm": 35,
  "feasibleRegion": [
    { "lat": 52.70, "lon": 13.05 },
    { "lat": 52.30, "lon": 13.10 },
    { "lat": 52.35, "lon": 13.80 },
    { "lat": 52.68, "lon": 13.75 }
  ]
}

Field	Type	Range / values	Meaning
country	string	ISO 3166-1 alpha-2 (e.g. "DE", "US")	Estimated country of origin for the session. Absent if there wasn't enough signal.
confidence	number	0–1	Confidence in country. Higher is more confident.
alarm	string	"none" | "low" | "medium" | "high"	Escalation indicator for the session. Higher warrants more caution.
estimatedLocation	object { lat, lon }	decimal degrees	The estimated location point — the coarse "where". Absent if no location could be estimated.
confidenceRadiusKm	number	kilometres	Radius of the uncertainty circle around estimatedLocation. Treat the estimate as an area, not a pinpoint.
feasibleRegion	array of { lat, lon }	decimal degrees	Ordered vertices of the uncertainty-region polygon, when one was computed. Absent or empty ⇒ fall back to the confidenceRadiusKm circle.

This is the complete contract

These fields are everything that crosses the boundary. Octet projects its full internal assessment down to exactly this shape before any response leaves — there is no hidden "why". The reasoning behind the verdict (which signals were weighed, how the country, alarm, or region were derived) stays on Octet's servers and is never returned, to your backend or the browser. See Trust & Privacy.

The country, estimatedLocation, confidenceRadiusKm, and feasibleRegion fields are each independently optional — handle their absence (not enough signal). confidence and alarm are always present.

Pending response

If the verdict isn't ready (the browser is still collecting, or no signals arrived for that sessionRef):

{ "status": "pending", "ref": "sess_abc123" }

returned with HTTP 404. Use the waitMs long-poll, or retry shortly. See Fetch the Verdict.

How to interpret it

• confidence gauges how much to trust country; choose a threshold for your risk tolerance and treat low confidence as "not enough signal", not as a negative.
• alarm is a separate axis — use it to decide how cautious to be, independent of country.
• Location region — estimatedLocation is a coarse point; render or reason about it as an area, never a pinpoint. If feasibleRegion is present and non-empty, use that polygon; otherwise draw the confidenceRadiusKm circle around estimatedLocation. Any of the three may be absent when there wasn't enough signal.

There is, by design, no field telling you why. See Verdicts and Trust & Privacy.

Where to go next

• Fetch the Verdict. How to read it.
• Verdicts. The conceptual read.