Skip to main content

Device Status API

API docs by Redocly

Device Status (0.5.1)

Download OpenAPI specification:Download

E-mail: contact@spryfoxnetworks.com License: Apache 2.0

This API provides the customer with the ability to query device:

  • Roaming Status
  • Connectivity Status

Moreover, this API extends the functionality by allowing users customers to subscribe to events associated with these status queries.

Product documentation at CAMARA

Introduction

Roaming Status

API consumer is able to verify whether a certain user device is in roaming situation (or not). This capability is provided in 2 ways:

  • via direct request with the roaming situation in the response.
  • via a subscription request - in this case the roaming situation is not in the response but event notification is sent back to the event subscriber when roaming situation has changed.

The verification of the roaming situation depends on the network's ability. Additionally to the roaming status, when the device is in roaming situation, visited country information could be returned in the response.

Connectivity Status

API consumer is able to verify whether a certain user device is connected to the network via data- or sms-usage. This capability is provided in 2 ways:

  • via direct request with the connectivity situation in the response.
  • via a subscription request - in this case the connectivity situation is not in the response but event notification is sent back to the event subscriber when connectivity situation has changed.

Possible Use-Cases

Device status verification could be useful in scenario such as (not exhaustive):

  • For regulatory reasons, where a customer may need to be within a certain jurisdiction, or out with others, in order for transactions to be authorized
  • For security / fraud reasons, to establish that a customer is located where they claim to be
  • For service delivery reasons, to ensure that the customer has access to particular service, and will not incur roaming charges in accessing them

Relevant terms and definitions

  • Device: A device refers to any physical entity that can connect to a network and participate in network communication. At least one identifier for the device (user equipment) out of four options: IPv4 address, IPv6 address, Phone number, or Network Access Identifier assigned by the mobile network operator for the device.

  • Roaming : Roaming status - true, if device is in roaming situation - false else.

  • Country : Country code and name - visited country information, provided if the device is in roaming situation.

  • Connectivity : Connectivity status.

    • CONNECTED_SMS, if device is connected to the network via SMS usage
    • CONNECTED_DATA, if device is connected to the network via data usage
    • NOT_CONNECTED, if device is not connected to the network

API Functionality

The API exposes following capabilities:

Device roaming situation

The endpoint POST /roaming allows to get roaming status and country information (if device in roaming situation) synchronously.

Device connectivity situation

The endpoint POST /connectivity allows to get current connectivity status information synchronously.

Device status subscription

These endpoints allow to manage event subscription on roaming device status event. The CAMARA subscription model is detailed in the CAMARA API design guideline document and follows CloudEvents specification.

It is mandatory in the subscription to provide the event type subscribed are several are managed in this API.

Following event type are managed for this API:

  • org.camaraproject.device-status.v0.roaming-status - Event triggered when the device switch from roaming ON to roaming OFF and conversely

  • org.camaraproject.device-status.v0.roaming-on - Event triggered when the device switch from roaming OFF to roaming ON

  • org.camaraproject.device-status.v0.roaming-off: Event triggered when the device switch from roaming ON to roaming OFF

  • org.camaraproject.device-status.v0.roaming-change-country: Event triggered when the device in roaming change country code

  • org.camaraproject.device-status.v0.connectivity-data: Event triggered when the device is connected to the network for Data usage.

  • org.camaraproject.device-status.v0.connectivity-sms: Event triggered when the device is connected to the network for SMS usage

  • org.camaraproject.device-status.v0.connectivity-disconnected: Event triggered when the device is not connected.

Note: Additionally to these list, org.camaraproject.device-status.v0.subscription-ends notification type is sent when the subscription ends. This notification does not require dedicated subscription. It is used when the subscription expire time (optionally set by the requester) has been reached or if the API server has to stop sending notification prematurely.

Notifications callback

The notifications callback describes the format of event notifications and expected responses to the messages sent when the event occurs. As for subscription, detailed description of the event notification is provided in the CAMARA API design guideline document.

WARNING: This callback endpoint must be exposed and reachable on the listener side under 'notificationUrldefined in thewebhook` attribute.

Further info and support

(FAQs will be added in a later version of the documentation)

Device connectivity status

Operations to get the current connectivity status of a device

Get the current connectivity status information

Get the current connectivity status information

Authorizations:
openId
Request Body schema: application/json
required
required
object (Device) non-empty

End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.

The developer can choose to provide the below specified device identifiers:

  • ipv4Address
  • ipv6Address
  • phoneNumber
  • networkAccessIdentifier

NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device.

phoneNumber
string (PhoneNumber) ^\+?[0-9]{5,15}$

A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'.

networkAccessIdentifier
string (NetworkAccessIdentifier)

A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.

object or object (DeviceIpv4Addr)

The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers).

If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress.

If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object)

In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone.

ipv6Address
string <ipv6> (DeviceIpv6Address)

The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).

Responses

Request samples

Content type
application/json
{
  • "device": {
    }
}

Response samples

Content type
application/json
Example
{
  • "connectivityStatus": "CONNECTED_SMS"
}

Device roaming status

Operation to get device roaming status and country information (if roaming) synchronously

Get the current roaming status and the country information

Get the current roaming status and the country information

Authorizations:
openId
Request Body schema: application/json
required
required
object (Device) non-empty

End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.

The developer can choose to provide the below specified device identifiers:

  • ipv4Address
  • ipv6Address
  • phoneNumber
  • networkAccessIdentifier

NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device.

phoneNumber
string (PhoneNumber) ^\+?[0-9]{5,15}$

A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'.

networkAccessIdentifier
string (NetworkAccessIdentifier)

A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.

object or object (DeviceIpv4Addr)

The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers).

If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress.

If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object)

In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone.

ipv6Address
string <ipv6> (DeviceIpv6Address)

The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).

Responses

Request samples

Content type
application/json
{
  • "device": {
    }
}

Response samples

Content type
application/json
Example
{
  • "roaming": true,
  • "countryCode": 901,
  • "countryName": [ ]
}

Device status subscription

Operation to manage event subscription on device status event (roaming, connectivity)

Create a device status event subscription for a device

Create a device status event subscription for a device

Authorizations:
openId
Request Body schema: application/json
required
required
object (SubscriptionDetail)

The detail of the requested event subscription

subscriptionExpireTime
string <date-time>

The subscription expiration time in date-time format.

required
object (Webhook)

Webhook information for event channel

Responses

Callbacks

Request samples

Content type
application/json
{
  • "subscriptionDetail": {
    },
  • "subscriptionExpireTime": "2023-01-17T13:18:23.682Z",
  • "webhook": {}
}

Response samples

Content type
application/json
{
  • "subscriptionDetail": {
    },
  • "subscriptionExpireTime": "2023-01-17T13:18:23.682Z",
  • "webhook": {},
  • "subscriptionId": "qs15-h556-rt89-1298",
  • "startsAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Callback payload samples

Callback
POST: Session notifications callback
Content type
application/cloudevents+json
Example
{
  • "id": "123654",
  • "source": "https://notificationSendServer12.supertelco.com",
  • "type": "org.camaraproject.device-status.v0.roaming-status",
  • "specversion": "1.0",
  • "datacontenttype": "application/json",
  • "data": {
    },
  • "time": "2023-01-17T13:18:23.682Z"
}

Retrieve a list of device status event subscription

Retrieve a list of device status event subscription(s)

Authorizations:
openId

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a device status event subscription for a device

retrieve event subscription information for a given subscription.

Authorizations:
openId
path Parameters
subscriptionId
required
string

Subscription identifier that was obtained from the create subscription operation

Responses

Response samples

Content type
application/json
{
  • "subscriptionDetail": {
    },
  • "subscriptionExpireTime": "2023-01-17T13:18:23.682Z",
  • "webhook": {},
  • "subscriptionId": "qs15-h556-rt89-1298",
  • "startsAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Delete a device status event subscription for a device

delete a given event subscription.

Authorizations:
openId
path Parameters
subscriptionId
required
string

Subscription identifier that was obtained from the create event subscription operation

Responses

Response samples

Content type
application/json
{
  • "subscriptionId": "qs15-h556-rt89-1298"
}