Verdicts

A verdict covers one session: the country the session is operating from, how certain Octet is of that country, and how strongly the session's signals contradict it. The exact field list is in Verdict Reference.

`country`

country is an ISO 3166-1 alpha-2 code, for example "GB". Territories come back as their own codes, not their parent country's. Puerto Rico is "PR", not "US", and Guam is "GU". If your policy covers a country and its territories, list every code.

country is absent when Octet could not determine one. Treat an absent country as unknown, not as a pass.

`confidence`

confidence is a number from 0 to 1. It measures how certain Octet is of country. To judge whether the connection is masked, use alarm, not confidence.

`alarm`

alarm has four levels:

Level	Meaning
`none`	Nothing contradicts `country`.
`low`	A minor inconsistency with no sign of masking, such as a traveller or a device set up for another country. Use `country` as returned.
`medium`	The connection appears masked, for example by a VPN or proxy. Don't trust `country`.
`high`	The connection is masked. `country` is still the country the user is in. It is also `high` when Octet determines the device is being used in a country under comprehensive sanctions, masked or not. Octet does not reliably detect sanctioned regions inside a country, such as Crimea. See Sanctioned regions.

At high, country is the country the user is in, as Octet determines it. It can differ from the country of their IP address.

Sanctioned regions

Some sanctions cover a region inside a country rather than the whole country. Examples are Crimea and the so-called Donetsk and Luhansk People's Republics, all in Ukraine.

country is a country-level result, so a session in one of these regions comes back as "UA". The verdict does not reliably tell you whether a session is inside such a region. Placing a session on one side of a boundary inside a country is less certain than placing it on one side of an international border.

If your obligations cover a sanctioned region, don't rely on the verdict alone.

Choosing a policy

You decide what each verdict means for your service. A common starting point for a regulated action:

const RESTRICTED = new Set(['US', 'PR', 'GU', 'VI', 'AS', 'MP', 'UM']);

function needsKyc(verdict) {
  const masked = verdict.alarm === 'medium' || verdict.alarm === 'high';
  const restricted = verdict.country === undefined || RESTRICTED.has(verdict.country);
  return masked || restricted;
}

needsKyc returns true when country is on your list, when there is no country, or when alarm is medium or above. Adjust the list and the action to your own obligations. Octet makes no decision for you.

A few rules hold for any policy:

Read the verdict on your backend. Never act on anything the browser reports.
Treat medium and high as masked connections. At medium, don't rely on country. At high, country still tells you where the user is.
Don't block on low alone. It is how honest travellers usually appear.