Device-Status-notification JSON schemas
On this page, you will find the different types of notification JSON schemas for Device-Status,
such as Connectivity, Roaming and End of subscription.
Underneath each JSON schema, there is a table with further information on the specific schema right above it.
At the bottom of this page, you can also check a table, which contains further details on the values that are shared by all the different schemas.
Remember that the string values represented below are just examples that can be used. So, they should contain your real device-status values.
Connectivity-event-detail schema
This is the notification JSON schema for monitoring when a device is attached or detached from a data network (connectivity).
{
"eventSubscriptionId": "device-one-connectivity-status",
"event": {
"eventType": "CONNECTIVITY",
"eventTime": "2023-01-17T13:18:23.682Z",
"eventDetail": {
"device": {
"phoneNumber": "36721601234567",
"networkAccessIdentifier": "device@bestcsp.net",
"ipv4Address": {
"DeviceIpv4Addr": {
"publicAddress": "233.252.0.2",
"privateAddress": "192.0.2.25",
"publicPort": "80"
}
},
"ipv6Address": "2001:db8:1234:5678:9abc:def0:fedc:ba98"
},
"deviceStatus": "REACHABLE"
}
}
}| Connectivity-keyword values | Description |
|---|---|
deviceStatus | A string, which will be REACHABLE if the device is online and UNREACHABLE when it's offline. |
Roaming-event-detail schema
This is the notification JSON schema for monitoring if a device is roaming or not.
{
"eventSubscriptionId": "device-one-connectivity-status",
"event": {
"eventType": "ROAMING_STATUS",
"eventTime": "2023-01-17T13:18:23.682Z",
"eventDetail": {
"device": {
"phoneNumber": "36721601234567",
"networkAccessIdentifier": "device@bestcsp.net",
"ipv4Address": {
"DeviceIpv4Addr": {
"publicAddress": "233.252.0.2",
"privateAddress": "192.0.2.25",
"publicPort": "80"
}
},
"ipv6Address": "2001:db8:1234:5678:9abc:def0:fedc:ba98"
},
"roaming": true,
"countryCode": 358,
"countryName": ["Finland", "Sweden", "Norway"]
}
}
}| Roaming-event-detail-keyword values | Description |
|---|---|
roaming | Either a Boolean or a "null" value. |
countryCode | Either an integer with the country code or a "null" value. |
countryName | Either a string or string array with the country name(s) or a "null" value. |
Subscription-ends-event-detail schema
This is the notification JSON schema for monitoring why a device's subscription ended.
{
"eventSubscriptionId": "device-one-connectivity-status",
"event": {
"eventType": "ROAMING_STATUS",
"eventTime": "2023-01-17T13:18:23.682Z",
"eventDetail": {
"device": {
"phoneNumber": "36721601234567",
"networkAccessIdentifier": "device@bestcsp.net",
"ipv4Address": {
"DeviceIpv4Addr": {
"publicAddress": "233.252.0.2",
"privateAddress": "192.0.2.25",
"publicPort": "80"
}
},
"ipv6Address": "2001:db8:1234:5678:9abc:def0:fedc:ba98"
},
"terminationReason": "SUBSCRIPTION_EXPIRED"
}
}
}| Subscription-ends-keyword values | Description |
|---|---|
terminationReason | A string value containing the termination reason. It explains if the subscription ended due to expiration "SUBSCRIPTION_EXPIRED" or network interruption "NETWORK_TERMINATED". |
Shared-keyword values
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:
| Keyword values | Description |
|---|---|
eventSubscriptionId | A string value with the event subscription identifier. |
event | An object, which contains other objects or strings with further details on the event. |
eventType | A string value containing the different status you want to check. The allowed values are: "ROAMING_ON", "ROAMING_OFF", "ROAMING_STATUS", "ROAMING_CHANGE_COUNTRY", "CONNECTIVITY". |
eventTime | A string value with the time the event occurred. Date and time are specified in ISO 8601 format, e.g.: 2023-08-20T21:01:02.345Z. |
eventDetail | An object that can contain three other object types, which are ConnectivityEventDetailExpand, RoamingEventDetailExpand and SubscriptionEndsEventDetail. The different JSON schemas for these objects are exemplified above. |
device | An object that will contain other objects or strings with multiple device identifiers. |
phoneNumber | Optional string with a pattern that matches "^[+]?[0-9]{5,15}$" or a "null" value. |
networkAccessIdentifier | Optional string with a pattern that matches "^[+]?[0-9]{5,15}$" or a "null" value. It is an mail-like external identifier for a device (or subscriber) into the network. If both the networkAccessIdentifier and phoneNumber are included, phoneNumber will be dropped and networkAccessIdentifier will be retained. |
ipv4Address | Optional object containing the Deviceipv4Addr object or a "null" value. It refers to the IPv4 address of the device. An IP address is needed for some flow-oriented services, such as QoD. |
DeviceIpv4Addr | Optional object that can contain the public or private IP address and port. |
publicAddress | Optional string with either the device's public IPv4 address, the Network Address Translation (NAT) behind it or a "null" value. Learn more about NAT. |
privateAddress | Optional string with the device's private IPv4 address if it is behind NAT or a "null" value. |
publicPort | Optional integer with the public port used by the device or a "null" value. A port is necessary, as private address ranges overlap, and public port is used to extend the range for Carrier-grade NAT (CGNAT), a type of large-scale NAT. |
ipv6Address | Optional string containing the device's IPv6 address or a "null" value. An IP address is needed for some flow-oriented services, such as QoD. |
Last updated on November 27, 2023