Chapter 1
Chapter 2
Chapter 3
Chapter 4
WHITEPAPER

The benefits of a good cellular IoT API (and how to find one)

Abstract

As a product manager responsible for a cellular-connected IoT fleet, you’ll need to look beyond the web console when it’s time to grow. Manual SIM management for tens of thousands of connected asset trackers or smart devices/sensors for buildings, retail, healthcare, or farming is just too slow and labor-intensive to take you beyond the initial stages of a product rollout. 

 

Instead, you can program and automate your way to efficiency with cellular IoT APIs. A good API lets you scale up your fleet by adding volume, expanding to new regions, or creating more diverse customer experiences, all while streamlining operations to save costs. (A not-so-good API is another story, but we’ll get to that.) Ideally, you can run a fleet of 500,000 devices with the same resources it takes to manage one with 50.

 
APIs tend to get overlooked when IoT projects are set up because the focus is on building and launching the product, not on growth and scalability.

This white paper explains why APIs are important for cellular IoT device management and how you can use APIs to operate more efficiently and improve the user experience. It then gives you a plethora of practical tips for how to evaluate a vendor’s API so you can make sure you’re getting the best quality and functionality for your fleet.

 

INSIDE THE WHITEPAPER

Chapter 1

1

Introduction

Let’s assume that you’ve evaluated your options for connectivity based on your use case and your user and device needs. You’ve chosen licensed cellular over other methods such as Wi-Fi, Sigfox, and LoRaWAN based on throughput volume, mobility and power requirements, latency tolerance, and other factors. 


If you’re already running a cellular-connected fleet of devices, you may be feeling some growing pains as you run up against the limits of using a web-based console (or worse, support tickets logged with the provider) to activate and troubleshoot SIMs. Being familiar with APIs in general, you’re exploring ways you could use them to improve operations. 


But even if you’re still choosing which cellular provider to sign on with, it’s not too early to consider the role that APIs play in your decision. APIs tend to get overlooked when IoT projects are set up because the focus is on building and launching the product. And it’s feasible (even desirable) to do all that through a web console that is easily used by technical and non-technical staff alike. 


But when the product is successful and it’s time to expand, the reality of manually administering thousands of SIMs hits home. Thankfully, all that effort is avoidable if you take the time up front to find the right vendor with the right API.


Definitions

Cellular carrier or MNO, Mobile Network Operator:

A cellular provider that owns or controls its wireless network infrastructure

Cellular reseller or MVNO, Mobile Virtual Network Operator:

A cellular provider that doesn’t own its wireless network infrastructure but instead pays for access to another carrier’s network

Cellular provider:

A blanket term that includes both carriers (MNOs) and resellers (MVNOs)

Chapter 2

2

Why are APIs important for cellular IoT?

Knowing how much easier it is to manage a product using APIs, it’s natural to feel frustrated at being held back without one. Here’s how a cellular IoT API turns that frustration around.

Enabling scalability to support growth and expansion

You can’t afford to call and email a dozen times to activate a new batch of SIMs. You don’t have weeks to spend getting a support ticket resolved. You don’t want to be dodging questions from Sales — or worse, your CEO — who have all these customers lined up and no devices ready.

 

An API lets you automate most, if not all, of the IoT life cycle, which we’ll cover in detail later in the paper. (In fact, you may be surprised at how much you can do with a cellular IoT API.) Then you can move at the speed you want and need to for your business.

 

APIs can also help with forecasting your business growth. You can get information on demand for ordering or deploying new SIMs in particular areas, for example, and incorporate that into your existing operational dashboards.

Providing better troubleshooting, which improves agent and customer experience

It happens — customers run into issues and their device won’t connect, or it stops sending updates. If they call your customer service department, the agents will have to ask your cellular provider for help, with all the associated delays and miscommunication. Unless you’re using an API. With a programmatic way to consume and process information about the connectivity status of all devices, you can equip your agents with the knowledge to correct the issue instead of forcing them to go to the provider. Connectivity status — and, of course, product data — can be directly embedded and surfaced in the agent desktop if your contact center platform supports it.


Of course, not all problems are immediately inspectable. Sometimes an agent needs to open an internal ticket so an engineer can do a deeper analysis. In this case, data pushed to your system — such as on a stream of events — can give the technical troubleshooter better insight into what’s going on. As a result, some issues that had to go to the cellular provider can now be resolved by the IoT solution provider.


And when troubleshooting is easier for your team, your customers have a better experience. Their issues are resolved more quickly and easily so they can get on with using their devices.


It happens — customers run into issues and their device won’t connect, or it stops sending updates. If they call your customer service department, the agents will have to ask your cellular provider for help, with all the associated delays and miscommunication. Unless you’re using an API. With a programmatic way to consume and process information about the connectivity status of all devices, you can equip your agents with the knowledge to correct the issue instead of forcing them to go to the provider. Connectivity status — and, of course, product data — can be directly embedded and surfaced in the agent desktop if your contact center platform supports it.


Of course, not all problems are immediately inspectable. Sometimes an agent needs to open an internal ticket so an engineer can do a deeper analysis. In this case, data pushed to your system — such as on a stream of events — can give the technical troubleshooter better insight into what’s going on. As a result, some issues that had to go to the cellular provider can now be resolved by the IoT solution provider.


And when troubleshooting is easier for your team, your customers have a better experience. Their issues are resolved more quickly and easily so they can get on with using their devices.


Allowing more customization to align with the business

Carriers and resellers of cellular networks don’t typically specialize in the needs of IoT devices, so the functionality they offer for SIM management and configuration may be limited. You may only have a few set rate plans to choose from and be stuck with a configuration designed for specific telephony use cases that doesn’t fit your business. 


For example, perhaps you want a low-usage plan of 5 MB a month, but the carrier offers data plans at 5 GB a month, which doesn’t match your business well. You may be able to negotiate a customized rate plan with your cellular provider that takes weeks, if not months, to implement. But if your business needs change, you have to go through the same process again. Clearly, the carrier has the tools to configure what you want on their end, but they're just giving you a limited subset to build a customized experience for yourself that meets your needs. As you get more diverse customers, you will likely need more diverse options that become increasingly difficult to find and use.

Simplifying operations and reducing operating expenses

Because using APIs is so much more efficient than manual tools, they facilitate growth and speed of operations without requiring added resources — in fact, there should be time savings and reduced headcount, even after factoring in the initial investment for development and ongoing maintenance costs. API calls can be incorporated into your business workflows and systems, freeing up your team for more valuable work.

Not every API is created equal. You will find a great deal of variation in the quality of cellular IoT APIs. For many carriers and resellers, IoT is a small, relatively new addition to their services. Their focus — especially that of the MNOs — is more on connecting phones, not sensors, smart door locks, or HVAC systems. As such, their target customers and users of their APIs are resellers, connecting more phones. These APIs are created with this use case in mind and for those with decades of telephony experience.

 

That reality means that it’s not enough to just verify that an API exists for your chosen vendor. They might check a box on an RFP or tender to confirm they’ve got one, but it’s up to you to assess the API and make sure it is robust enough to meet your needs. 
1.
The modem contained in the scooter scans for the nearest cell tower to connect. This procedure is typically initialized by the base stations and terminated at the MME node of the VPLMN. The MME is one of the central components of the VPLMN. The MME identifies whom the IMSI belongs to by extracting the MNC and MCC fields. If the device is roaming, then the MME will need to talk to the HSS of the HPLMN in order to authenticate and authorize the scooter to connect to the network.
2.
The protocol used for exchanging authentication, authorization, and accounting messages between the MME and the HSS is conducted by the DRA.
3.
Once the HSS gives an `OK`, the MME determines which internet gateway to use for sending internet traffic. In LTE architecture, the PGW is used. In order to figure out which PGW to use, the MME performs a simple DNS query to get the PGW’s IP. This is handled via a simple DNS lookup of the access point name to the HPLMN DNS server.
4.
Once the selection is done, the MME instructs the SGW to establish a GPRS Tunnel Protocol tunnel with the selected PGW.
5.
Once the required tunnels are established, the device can connect to the internet.

Chapter 3

3

How to gain efficiencies in fleet management with APIs

What can you do with your cellular IoT API to improve and simplify operations? Depending on the functionality available, you can use an API throughout the life cycle of IoT SIMs to automate common tasks.

SIM activation and deactivation

As devices go out to the field, are temporarily suspended, or come back in, API calls let you send activate and deactivate requests quickly, and get confirmation back in minutes or seconds. Being able to turn a SIM off programmatically can also save on costs, as you avoid the monthly fee or further data downloads with a deactivated SIM.

SIM status queries

Keep tabs on devices. Are they online or offline? Which network are they currently on, and when did a new data session begin? Are SMS messages getting blocked or rejected? What are the rough latitude and longitude values of the SIM’s current location (based on cell tower triangulation)? What is the ID (IMEI) of the device that the SIM is currently in, and is it still the same device that the SIM was provisioned for?

 

Network access configuration

If the vendor offers the ability to define which networks your SIMs can and can’t connect to, it’s helpful if you can set that configuration programmatically. This level of programmatic control can empower you to develop your own unique plans for your customers to meet their commercial or technical needs without having to make any other changes to your workflows.

Billing information and usage records

Using an API, you can pull billing records automatically and incorporate them into your enterprise billing system. 

 

With usage records, you can determine how many megabytes a SIM or group of SIMs has used over a certain period. You can analyze trends or changes in behavior and spikes in usage that might point to problems. APIs then let you respond directly, for example, by deactivating a SIM.

 

A note on modernity: Just because an API allows you to pull information programmatically doesn’t mean that the data is easy to work with or well maintained. Are your call data records dropped onto an SFTP server that you have to scrape and process with your own usage bus? Or do you get connection events over an AWS Kinesis stream or into a webhook of your choice so you can process them in real time? It’s not just about getting the job done but doing it in a way that matches your application, with modern REST APIs and web services.

 

Troubleshooting

Good APIs don’t just cover the happy path. They also give you ways to see errors and surface alerts, optimally in real time, or as close to that as possible. A modern solution streams connection events into systems such as AWS Kinesis or a webhook of your choice, so you can consume and respond to errors or activity events 100% programmatically.

 

Device reachability

You may need to be able to ping your IoT devices and tell them to pull the latest data records, return a sensor reading, or download a firmware update, for example. Sending short IP/UDP messages is a great way to reach out to a device, but there are drawbacks to maintaining a persistent data connection to the cloud (namely, higher data usage and lower battery life). Instead, you can send IP commands via an API without needing a persistent connection, static IP address, or VPN.

 

Chapter 4

4

The qualities of a good cellular IoT API (and how to find one)

Ideally, a cellular IoT API is developed and maintained like a product itself, with the investment and attention that entails. When you’re incorporating an API into your own product, you want it to meet certain standards to make sure it is reliable and has a positive impact on your business.

 

Here are the qualities you should look for in a cellular IoT API, along with tips on how to verify them (plus pro tips if you want to be REALLY sure).

Well documented and easy to use

One could argue that there’s nothing as bad as an undocumented or poorly documented API, because when you can’t rely on what it tells you to do, or it omits key details, it’s not worth using.

 

Good API documentation is complete and up to date, with no unexplained jargon. It includes practical elements like code examples, explanations of error cases, walk-throughs of advanced features, how-to tutorials, and use case descriptions. It may have mechanisms that let you interact with the API right there in the documentation. You should also be able to easily give feedback on the documentation and rate pages so they are continuously optimized and improved.

 

Documentation is not a one-and-done job — it needs to be properly maintained over the lifetime of the API. The best documentation is also treated like a product, with clear ownership and healthy interaction among users and writers.

 

A non-telephony engineer should be able to understand each parameter of a well-built API, either because of good documentation or because the objects are clear and straightforward. An easy-to-use API gives you more control over more parameters and configurations, which lets you build a much more customized experience. 

Well documented and easy to use

One could argue that there’s nothing as bad as an undocumented or poorly documented API, because when you can’t rely on what it tells you to do, or it omits key details, it’s not worth using.

 

Good API documentation is complete and up to date, with no unexplained jargon. It includes practical elements like code examples, explanations of error cases, walk-throughs of advanced features, how-to tutorials, and use case descriptions. It may have mechanisms that let you interact with the API right there in the documentation. You should also be able to easily give feedback on the documentation and rate pages so they are continuously optimized and improved.

 

Documentation is not a one-and-done job — it needs to be properly maintained over the lifetime of the API. The best documentation is also treated like a product, with clear ownership and healthy interaction among users and writers.

 

A non-telephony engineer should be able to understand each parameter of a well-built API, either because of good documentation or because the objects are clear and straightforward. An easy-to-use API gives you more control over more parameters and configurations, which lets you build a much more customized experience. 

TIP
Check whether a recently announced feature has been documented yet. If the documentation is rolled out together with the public feature announcement, that’s an indication that the product manager themself may have written it, which is a good sign.
TIP
Do a web search for a feature to see whether the API documentation is on the first page of results. If it is, that tells you it’s a page that developers actively use and that it’s relevant enough for the search engine to highlight.
PRO TIP
Put the URL of a documentation page into archive.org to see what has changed in the last year or two. Have they added examples, fixed errors, or given more detailed explanations?

Backward compatible

In the connectivity space, you must assume that devices will be out in the world for a long time. Product improvements can’t change the programming interface such that processes that rely on them suddenly break.

 

A good API has minimal breaking changes, and when they are necessary, users are given ample notice. You should never be surprised when a parameter disappears or an endpoint gets deprecated.  

TIP
Look at the API versioning. An API with many versions that are no longer supported — and with no history of when support ended — is likely more volatile.
PRO TIP
Search for blog posts or news items about breaking changes for that API.

Reliable and highly available under stress

When you’re building software at scale, reliability and availability are crucial. An API might perform fine during prototyping and testing, but that doesn’t tell you whether it will continue to perform when you expand your deployment. You want to know about scaling capability now, not two years down the road when you’re committed but don’t have the engineering resources to fix the issues.

 

And no matter how good the API, its value drops to zero when it’s unavailable during hours-long maintenance windows, which are common in the telecom world. In this scenario, you may have to hold all your API calls for hours or else get internal server errors and timeouts. There’s really no reason an API should ever be down — nor should the underlying infrastructure it exposes. Your business doesn’t stop, so your SIM management shouldn’t either.

TIP
Check for service level agreements (SLAs) that guarantee uptime and performance of the APIs themselves. 
TIP
Find out if there are maintenance windows. Can you do a SIM activation API call during that time? What could cause your usage reporting to be delayed? How often do maintenance windows occur, and how long do they last? Ask questions and get the answers in writing.
TIP
Search for a vendor status page (often status.companyname.com). Is there a developer portal or public listing of metrics related to outages and uptime? Have they had recent big outages? Do they provide root cause analysis or publish reasons for outages (RFOs)? When something goes wrong, you’re looking for an honest detailed explanation that assures you things will improve.
PRO TIP
Get the vendor’s request limits. How many API requests can you make per second? Or how many concurrent API requests can you make? If they don’t know, that tells you a lot about the quality of the API.

Attracts an active developer community

Good APIs create a thriving developer ecosystem around them: Current blog posts and forums with lots of comments, Hacker News rankings, developer buzz about great experiences with the API, open-source repositories with common scripts and additional tooling, helper libraries that you can import. These signs speak to an API’s quality and assure you that you’ll be able to find developers that have experience working with that API and the vendor behind it.

TIP
Ask your developers if they’ve ever heard of the vendor you’re evaluating. The answer will tell you how developer-friendly and developer-focused they are. 
PRO TIP
Research vendor communications with the developer community. Does the vendor send regular updates? Can you subscribe to a product newsletter? Do they run regular webinars on new features? What’s the cadence of product announcements? Do they maintain a public change log? What documentation do they deliver on release day to encourage people to build?

Well supported

A good vendor supports developers as if they were paying customers, even though early on they may not be — in fact, they shouldn’t be! A vendor that sends you to Sales when you have a question or issue is not developer-first. A self-service channel to get you started is fine, but if you have to go through a sales rep to get a basic question answered about why something isn’t working, that’s a bad sign. 

TIP
Look at the support plans. Is “Developer” mentioned as a category? What support does it include?
TIP
Find out which support channels are offered for free. Is it just email, or can you use chat or even voice channels?
TIP
Ask your vendor for a sample bill and a sample log file. Can you understand them? Can you easily translate them into useful information?

Conclusion

APIs tend to get overlooked when IoT projects are set up because the focus is on building and launching the product, not on growth and scalability. But connectivity efficiency is a promise to the customer – and your business – that you need to take seriously. 

 

This paper provided the guidance you need to successfully evaluate and choose a cellular vendor with an API that will best support you in keeping that promise.

 

Twilio provides cellular IoT connectivity through Twilio Super SIM, a product built with APIs in mind from day 1. Super SIM is an IoT SIM that bundles more than 400 cellular networks into a single multi-IMSI SIM. It offers SIM fleet operators an easy-to-use web console and powerful APIs for SIM management. Super SIM provides access to multiple tier-1 carriers in many of the 185+ supported countries, gives you full control over which mobile networks your devices use around the world, and offers worry-free scaling of your business across international borders, simple pay-as-you-go pricing, and one predictable monthly bill for everything.

 

Sign up for free to try out the Super SIM API, or get access to our interactive demo to experience how easy it is to order, set up, and manage Super SIMs with our web console. You can also put our Twilio IoT API documentation to the test.

Ready to learn more?

Webinar

Meet Twilio Super SIM

An overview of Twilio's leading IoT SIM

Sign up to watch now
E-Book

IoT SIM Buyer's Guide

7 Critical Capabilities of Your IoT Cellular Connectivity Partner

Download the E-Book
Super SIM Free Trial
Start building IoT with a free trial of Twilio Super SIM
Get started