Roaming

Use the Roaming Insight from the Vonage Identity Insights API to check the roaming status and country for a given device on a mobile network. It can identify which country the device is roaming in, along with a timestamp of the last broadcasted time.

Some use cases where this information can be useful are:

• Fraud identification: Decrease fraud risk without additional friction for the user. For example, a large transaction is requested from a country that doesn’t match the roaming status of the account holder. The mismatch between the country identified by the bank and the one detected via Roaming leads the bank to block the transaction.
• Regulatory compliance: Enforce regulatory compliance and territorial restrictions based on the user's cellular network location, such as content license restrictions for video streaming in certain countries.
• Personalization of services: Provide seamless personalization of services and advertisements according to the user's location.

Prerequisites

To use Identity Insights, you must ensure your account is configured correctly; see the Getting Started guide for more information on:

• Creating your account,
• Creating a Vonage application for use with the Identity Insights API,
• The different environments available and how to configure your account to use them,
• And how to use the Dashboard Getting Started UI to use the API without writing any code.

This guide will explain how to use the Roaming Insight programatically using cURL.

Making an API Call

Authentication for the Identity Insights API is done via JWTs, a compact and self-contained JSON token. To generate a JWT, you can use our online generator, or alternatively use the Vonage CLI. You will need your application ID and private key to generate the JWT. Once you have your JWT, you can send a request to the API.

This example shows a cURL request for the Roaming insight to check if a given device is roaming, and if so what country that device is roaming in:

curl -X POST https://api-eu.vonage.com/v0.1/identity-insights \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+990123411",
    "purpose": "FraudPreventionAndDetection",
    "insights": {
      "roaming": {}
        }
    }'

The API will then return roaming information for that device - if it is roaming, and the country it is roaming in can be identified, that country is returned using the country_codes field:

{
  "request_id": "c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "insights": {
    "roaming": {
        "latest_status_at":"2024-02-20T10:41:38.657Z",
        "is_roaming": true,
        "country_codes": ["DE"], 
        "status": {
            "code": "OK",
            "message": "Success"
        }
    }
  }
}

You'll see the following fields in the roaming array:

Further Reading

• Read more about the Identity Insights API in the API Reference.
• If you have any questions, you can reach out to us on the Vonage Community Slack.