Device roaming status

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 Status eventsheader link

The snippet below will show you how to create a Device Status roaming subscription.

Note that the snippet below require you to identify your mobile network device.

import network_as_code as nac
from network_as_code.models.device import DeviceIpv4Addr
from network_as_code.models.device_status import EventType, AccessTokenCredential

 # 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(
    phone_number="+99999991000"
)

# Then we subscribe your device to roaming status events.
my_subscription = client.device_status.subscribe(
    device=my_device,
    event_type=[EventType.ROAMING_STATUS],
    # Use HTTPS to send notifications
    sink="https://example.com/notify",
    # You can also add optional parameters
    max_num_of_reports=5,
    subscription_expire_time=datetime.now(timezone.utc) + timedelta(days=1),
    sink_credential=AccessTokenCredential(
        access_token= "some-access-token",
        access_token_expires_utc= datetime.now(timezone.utc) + timedelta(days=1),
        access_token_type="bearer"
    ),
    initial_event=True

)

# 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 a device status roaming subscriptionheader link

The snippet below will show you how to retrieve a roaming subscription. If you need to modify or delete your subscription, you can easily retrieve it by its ID.

# Get the subscription previously created by its ID
subscription = client.device_status.get_roaming_subscription("<my-subscription-id>")

You can also get a list of active Device Status subscriptions for a client:

subscriptions = client.device_status.get_subscriptions()

Deleting Device Status roaming subscriptionsheader link

Use the following snippet to delete a Device Status roaming subscription, if you wish to stop receiving the previously configured status notifications.

# Get a previously created subscription by its ID
subscription = client.device_status.get_roaming_subscription("<my-subscription-id>")

# And delete it:
subscription.delete()

Getting a devices roaming statusheader link

You can check the device roaming status like so:

  print(my_device.get_roaming())

Getting device roaming status responsesheader link

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: Optional[str] | None
    networkAccessIdentifier: Optional[str] | None
    ipv4Address: Optional[str] | None
    ipv6Address: Optional[str] | None

class RoamingEventDetail(BaseModel):
    device: Device
    subscriptionId: str
    roaming: bool | None
    countryCode: int | None
    countryName: List[str] | None
    lastStatusTime: 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,
):

  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/device-roaming-status-subscriptions/v0.7/subscriptions/90409561-68f5-4360-b12d-9003f4dca8b0",
    "type": "org.camaraproject.device-roaming-status-subscriptions.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": 901
        "countryName": []
    }
}

Subscription-ends notificationheader link

This is the notification JSON schema for monitoring why a device's subscription ended.

{
   "id":"2628b42e-8789-4fcd-942a-841f16f52897",
   "source":"/device-status/device-roaming-status-subscriptions/v0.7/subscriptions/f76c90dd-3f68-4c69-bbdc-57bddfd0f910",
   "type":"org.camaraproject.device-roaming-status-subscriptions.v0.subscription-ends",
   "specversion":"1.0",
   "datacontenttype":"application/json",
   "time":"2027-04-17T07:31:01.416474Z",
   "data":{
      "device":{
         "phoneNumber":"+99999991000",
            "ipv4Address": {
                "publicAddress": "233.252.0.2",
                "privateAddress": "192.0.2.25",
                "publicPort": 80
            },
            "ipv6Address": "2001:db8:1234:5678:9abc:def0:fedc:ba98"
      },
      "subscriptionId":"f76c90dd-3f68-4c69-bbdc-57bddfd0f910",
      "terminationReason":"SUBSCRIPTION_EXPIRED"
   }
}

Supported event typesheader link

Subscription-ends keywordsheader 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 December 19, 2025