Skip to main content
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. 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, as a list of 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
Sending a non-empty list replaces the stored declaration. Omitting the field or sending an empty list leaves it unchanged. See the Account type 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. 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, 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. 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.