Reachability

Providing real-time information directly from mobile carriers, the Reachability Insight can be used to check the connectivity status for a given device, including if it is connected to the network for data, SMS, or both.

Key benefits include:

  • Enhanced user experience by sending relevant communications: Determine the reachability of a customer and send them the relevant communication, via SMS or data.
  • Customer record database management: Determine which customers need to be contacted to update their phone number, for example if a given user has not had data or SMS connectivity for the last 60 days.
  • Quick remote diagnostics and monitoring of IoT devices: Detect which devices are offline, and if so when they were last online, and remotely gain intelligence about which devices require maintenance.

Prerequisites

To use Identity Insights, you must ensure your account is configured correctly; see the Getting Started guide for more information on:

  • Creating your account,
  • Creating a Vonage application for use with the Identity Insights API,
  • The different environments available and how to configure your account to use them,
  • And how to use the Dashboard Getting Started UI to use the API without writing any code.

This guide will explain how to use the Reachability Insight programatically using cURL.

Making an API Call

Authentication for the Identity Insights API is done via JWTs, a compact and self-contained JSON token. To generate a JWT, you can use our online generator, or alternatively use the Vonage CLI. You will need your application ID and private key to generate the JWT. Once you have your JWT, you can send a request to the API.

This example shows a cURL request for the Reachability insight to check if, and how, a given device is connected to the mobile network:

curl -X POST https://api-eu.vonage.com/v0.1/identity-insights \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+990123400",
    "purpose": "FraudPreventionAndDetection",
    "insights": {
      "reachability": {}
        }
    }'

The API will then return roaming information for that device - if it is roaming, and the country it is roaming in can be identified, that country is returned using the country_codes field:

{
  "request_id": "c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "insights": {
    "reachability": {
        "latest_status_at":"2024-02-20T10:41:38.657Z",
        "is_reachable": true,
        "connectivity": ["DATA", "SMS"], 
        "status": {
            "code": "OK",
            "message": "Success"
        }
    }
  }
}

You'll see the following fields in the roaming array:

Field Description
latest_status_at Last time that the associated device connectivity status was updated.
is_reachable Indicates overall device reachability - will be true if the device is connected to the network.
connectivity Indicates if the device is connected to the network for DATA or SMS usage. Will only be returned if is_reachable is true.
status Indicates the status of the information returned for the specified phone number.
code Code indicating the status of the request. Must be one of:

NO_COVERAGE: The country or mobile network is not supported by available suppliers.
INVALID_PURPOSE: The purpose used is not valid or allowed for this Insight.
UNAUTHORIZED: The request could not be authorized for the combination of application, supplier, and phone number.
INTERNAL_ERROR: An internal error occurred while processing the request.
SUPPLIER_ERROR: The supplier returned an error while processing the request.
NOT_FOUND: The phone number could not be found for this Insight.
INVALID_NUMBER_FORMAT: The phone number format is not valid for assignment by carriers to users.
PARTIAL_SUCCESS: Some response attributes were omitted because they are not applicable or were not available.
OK: All Insight attributes are available and included in the response.
message More detailed status description.

Further Reading