Device reachability status

The Device Status reachability feature allows querying and reporting information on several aspects of data reachability for a device, so you can monitor its status updates, such as when it goes online or offline.

Subscribe to Reachability Status eventsheader link

The snippet below will show you how to create a Device Status reachability 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 reachability status events.
my_subscription = client.device_status.subscribe(
    device=my_device,
    event_type=[EventType.REACHABILITY_DATA],
    # Use HTTPS to send notifications
    sink="https://endpoint.example.com/sink",
    # 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 reachability subscription status
print(my_subscription)

Reachability subscription parametersheader link

Reachability event typesheader link

Simulated Device Reachability scenariosheader link

The Network as Code simulators have been configured to provide specific device reachability 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 reachability subscriptionheader link

The snippet below will show you how to retrieve a reachability 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_reachability_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 a Device Status reachability subscriptionheader link

Use the following snippet to delete a Device Status reachability 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_reachability_subscription("<my-subscription-id>")

# And delete it:
subscription.delete()

Getting a devices reachability statusheader link

You can check the device reachability status like so:

  print(my_device.get_reachability())

Getting device reachability status responsesheader link

Getting reachability notificationsheader link

The code snippet below will set up an HTTP server with a POST endpoint. This will allow receiving device reachability status updates. For example, you can learn if a device is available (reachable from the network) or not. Learn more about the notification URL/auth token and how to create an HTTP server with a POST endpoint for reachability notifications.

Reachability 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 Optional


app = FastAPI()

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

class ReachabilityEventDetail(BaseModel):
    device: Device
    subscriptionId: str
    connectivity: List[str] | None
    reachable: bool | None
    lastStatusTime: str | None
    terminationReason: str

class Event(BaseModel):
    eventType: str
    eventTime: str
    eventDetail: ReachabilityEventDetail

class Data(BaseModel):
    device: Device
    subscriptionId: str
    terminationReason: str

class Notification(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: Notification,
    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)

Reachability notification detailsheader link

This notification JSON schema is used for notifications about device reachability.

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

{
    "id": "9884b8d2-5392-4ed7-8cde-0ce25bf58df3",
    "source": "/device-status/device-reachability-status-subscriptions/v0.7/subscriptions/83b1eaae-4533-4bff-a0af-e805cb8a2940",
    "type": "org.camaraproject.device-reachability-status-subscriptions.v0.reachability-data",
    "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": "83b1eaae-4533-4bff-a0af-e805cb8a2940"
    }
}

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-reachability-status-subscriptions/v0.7/subscriptions/f76c90dd-3f68-4c69-bbdc-57bddfd0f910",
   "type":"org.camaraproject.device-reachability-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