> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verisoul.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Expected Countries

> Declare where an account should legitimately operate from and detect sessions that fall outside it

Expected countries let you tell Verisoul where an account should legitimately operate from. Once declared, every session for that account is checked against the declaration. Out-of-list activity surfaces in two ways: as the `outside_expected_countries` risk signal, and as a contribution to the [location spoofing score](/signals-scores/location#location-spoofing-score).

This is useful whenever you know something about a user's legitimate geography that Verisoul lacks on its own: the countries a customer's license covers, or the home country a user registered with.

## Declaring expected countries

Expected countries are declared per account through the `expected_countries` field on the [Account object](/api-reference/types/account), as a list of [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes. You can send it anywhere the Account object is accepted:

* **`POST /session/authenticate`**, alongside the rest of the account payload
* **`PUT /account/{account_id}`**, the [account update endpoint](/api-reference/account/update)

```json theme={null}
{
  "account": {
    "id": "acc_123456789",
    "email": "user@example.com",
    "expected_countries": ["US", "CA"]
  },
  "session_id": "00000000-0000-0000-0000-000000000001"
}
```

Sending a non-empty list replaces the stored declaration. Omitting the field or sending an empty list leaves it unchanged. See the [Account type](/api-reference/types/account#expected-countries) for full update semantics.

## How it surfaces

Declaring expected countries affects two outputs on every subsequent session for the account: a risk signal and a score.

### The `outside_expected_countries` risk signal

Sessions whose observed country falls outside the declaration carry the `outside_expected_countries` signal in [`risk_signal_details.network`](/signals-scores/risk-signals). The signal is deterministic, which makes it a good target for hard allow and block rules:

* It fires when an observed session country, either the IP country or the [resolved true country](/signals-scores/location#true-country-detection), is outside the declared list
* It fires only for accounts that declared expected countries, and only on definitive evidence: sessions with missing or unresolvable geo data are skipped
* It is independent of the proxy and VPN score gates, so it appears even on sessions whose network scores otherwise read clean

### The location spoofing score

When a session's location falls outside every declared country, the distance from the session's location to the nearest declared country feeds the session's [`location_spoofing` score](/signals-scores/location#location-spoofing-score). The contribution is dynamic and scales with the severity of the distance: a session just across a border from a declared country, say a US-declared account appearing in Mexico, raises the score modestly, while the same account appearing in China raises it substantially.

The component contributes only when the account declared expected countries, the session sits outside all of them, and location data for the session is available. This covers the case where the user really is where their IP says they are, with zero proxy or VPN involvement, but that place is outside everywhere the account should legitimately be.