Device roaming

The Device Status SDK allows checking the device roaming status and subscribing to its related events. A device can be in national (different networks in the same country) or international roaming (different networks in another country). Knowing whether the device is connected to a network other than its home one is important for regulatory, security and content delivery reasons.

For example, in some cases for certain transactions to take place, a device needs to be within an area where it is legally allowed to operate or make transactions. Another case would be to ensure a customer's device is exactly where it claims to be to avoid fraud. Other important examples include content or service delivery to avoid extra costs or unexpected roaming charges for accessing them.

Subscribe to Roaming eventsheader link

The SDK below allows you to subscribe client devices to Device Status roaming events.

import network_as_code as nac
from network_as_code.models.device_status import EventType

# We begin by creating a Network as Code client
client = nac.NetworkAsCodeClient(
    token="<your-application-key-here>"
)

# Then, we create an object for the mobile device we want to use
my_device = client.devices.get(
    # The phone number does not accept spaces or parentheses
    phone_number="+99999991000"
)

# Then we subscribe your device to roaming events.
my_subscription = client.connectivity.subscribe(
    event_type=EventType.ROAMING_STATUS,
    device=my_device,
    # You can tell when the subscription is supposed to expire
    subscription_expire_time="2024-04-10T14:13:29Z",
    # Use HTTPS to send notifications
    notification_url="https://example.com/notify",
    notification_auth_token="replace-with-your-auth-token"
)

# Use this to show the roaming subscription status
print(my_subscription)

Roaming subscription parametersheader link

Roaming event typesheader link

Simulated device roaming scenariosheader link

The Network as Code simulators have been configured to provide specific device roaming results for specific simulated devices based on their device identifier. This will be helpful in testing your code against the different responses, including possible errors, by simply substituting the device identifier in your code.

The device identifiers and their responses can be found in the following table:

Getting device roaming statusheader link

You can check the device roaming status like so:

  print(my_device.get_roaming())

Getting device roaming status responsesheader link

Getting a devices roaming status will respond with a boolean value indicating whether the device is roaming or not. If the device is roaming, the response will also contain the county code and country name the device is roaming in.

Getting roaming notificationsheader link

The code snippet below will set up an HTTP server with a POST endpoint. This will allow receiving device roaming status updates. Learn more about the notification URL/auth token and how to create an HTTP server with a POST endpoint for roaming notifications.

Roaming notification handlerheader link

# status_handler.py

# run with: uvicorn status_handler:app

from fastapi import FastAPI, Header
from pydantic import BaseModel

from typing_extensions import Annotated
from typing import List, Union

app = FastAPI()

class Device(BaseModel):
    phoneNumber: str | None
    networkAccessIdentifier: str | None
    ipv4Address: str | None
    ipv6Address: str | None

class RoamingEventDetail(BaseModel):
    device: Device
    subscriptionId: str
    roaming: bool | None
    countryCode: int | None
    countryName: List[str] | None
    terminationReason: str

class Event(BaseModel):
    eventTime: str
    eventDetail: RoamingEventDetail

class Data(BaseModel):
    device: Device
    subscriptionId: str
    roaming: RoamingEventDetail

class RoamingStatusNotification(BaseModel):
    id: str
    source: str
    type: str
    specversion: str
    datacontenttype: str
    time: str
    eventSubscriptionId: str
    event: Event
    data: Data

@app.post("/notifications")
def receive_notification(
    notification: RoamingStatusNotification,
    authorization: Annotated[Union[str, None], Header]
):
    if authorization == "Bearer my-token":
        # We can now react to the notifications
        # based on the Notification object
        print(notification)

Roaming notification detailsheader link

This is the notification JSON schema for roaming related notifications.

Remember that the string values represented below are just examples that can be used. So, they should contain your real device-status values.

{
    "id": "2628b42e-8789-4fcd-942a-841f16f52897",
    "source": "/device-status/v0/subscriptions/90409561-68f5-4360-b12d-9003f4dca8b0",
    "type": "org.camaraproject.device-status.v0.roaming-status",
    "specversion": "1.0",
    "datacontenttype": "application/json",
    "time": "2026-04-17T07:31:01.416474Z",
    "data": {
        "device": {
            "phoneNumber": "+99999991000",
            "networkAccessIdentifier": "[email protected]",
            "ipv4Address": {
                "publicAddress": "233.252.0.2",
                "privateAddress": "192.0.2.25",
                "publicPort": 80
            },
            "ipv6Address": "2001:db8:1234:5678:9abc:def0:fedc:ba98"
        },
        "subscriptionId": "90409561-68f5-4360-b12d-9003f4dca8b0",
        "roaming": true,
        "countryCode": 587
    }
}

Roaming event key wordsheader link

Shared-keyword valuesheader link

Check the table below for further information on mandatory, optional values and their types. The values described here are common to all the Device-Status notification JSON schemas:

Device identifiersheader link

Last updated November 05, 2025