Technical Details

The Device Status API enables you to query a device's connectivity and roaming status. Some example use cases for these capabilities include:

• 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.
• For IoT devices, so that companies can proactively detect when devices lose connection to the network.

Device Status API Operations

Connectivity Status

The connectivity operation gives you information about a device's current connectivity status, returning one of three options:

• CONNECTED_DATA: The device is connected to the network for Data usage.
• CONNECTED_SMS: The device is connected to the network for SMS usage.
• NOT_CONNECTED: The device is not connected to the network.

Roaming Status

The roaming operation gives you information on whether or not a device is roaming, returning:

• roaming: whether or not the device is currently roaming.
• countryCode: if roaming, the mobile country code for the country the device is roaming in.
• countryName: if roaming, the name of the country the device is roaming in.

API Reference

The OpenAPI specification for the Device Status API is available here.

Authentication

The authentication process for the Device Status API is referred to as Server Authentication. For a comprehensive overview of how this works, check out our authentication guide.

Be sure to read our Network API Scopes guide to understand how scopes work in the authentication flow.

Registration

Before using the Device Status API, you must first register your application with Vonage and the mobile operators. The Vonage Network Registry automates the registration process through a common dashboard interface and sends the information to the operators for approval. Vonage’s customer dashboard is the single source for registration across all participating operators.

Optionally, you can use the Network Registry API to programmatically handle the registration and approval process.

Playground

Currently, the Device Status API can only be used in the playground with a Virtual Operator, which provides predefined and deterministic API responses based on the parameters of the API request. This allows for the discovery, development and testing of Network APIs in scenarios where access to a live operator is unavailable.

See the playground guide for more information on how to setup your account, and the Virtual Operator guide for more information on the preconfigured requests and responses.