Share article:

Know the details behind every phone number

Image for Know the details behind every phone number
Developers 3 min read | wrote in blog on April 16, 2018

Did you know that over 98% of text messages are opened, while only 22% of emails are opened? Customers respond to SMS and this behaviour can be very powerful for businesses. Unless you can connect with your customers seamlessly, any attempt to engage and retain them will frustrate them. They will either abandon your business for a competitor, or simply find a better solution to the issue you’re helping them solve. It’s crucial to stay connected with your customers.

You shouldn’t have to spend on unnecessary SMS to invalid numbers. Nor should you be struggling with authenticating phone numbers.  To help our clients combat these challenges and countless others, we’ve built the MessageMedia Lookups API.

Why Lookups API?

Lookups can be used to identify carriers, isolate invalid numbers and separate landlines from mobile phones (US). Our Lookups service also provides basic number insights to help you keep your contact numbers organized. You can clean up your database and extract the numbers with an invalid area code, numbers that are too long, too short or use unrecognisable letters and characters. Some number types don’t accept all communications – for instance, most landline numbers can’t accept SMS.  Why pay for an SMS to a landline number that can’t be received?

How do I use the Lookups API?

Let’s break it down into three basic steps:

  • Supply us with the phone numbers you’d like to check
  • Our Lookups endpoint identifies legitimate numbers, their carriers, country of origin and phone type (mobile or landline)
  • Our Lookups endpoint sends the data back to you

This is how you would lookup a number in Python

from message_media_lookups.message_media_lookups_client import MessageMediaLookupsClient
import json

basic_auth_user_name = 'YOUR_API_KEY' 
basic_auth_password = 'YOUR_API_SECRET'

client = MessageMediaLookupsClient(basic_auth_user_name, basic_auth_password)

lookups_controller = client.lookups

phone_number = 'YOUR_MOBILE_NUMBER'
options = 'carrier,type'

result = lookups_controller.get_lookup_a_phone_number(phone_number, options)

And this is how it would look like in Node.js

const sdk = require('messagemedia-lookups-sdk');

sdk.Configuration.basicAuthUserName = "YOUR_API_KEY"; 
sdk.Configuration.basicAuthPassword = "YOUR_API_SECRET"; 
var controller = sdk.LookupsController;

var phoneNumber = "YOUR_MOBILE_NUMBER";
var options = 'carrier,type';

controller.getLookupAPhoneNumber(phoneNumber, options, function(error, response, context) {


A typical response body from the lookups endpoint will have the following structure:

  "country_code": "AU", 
  "phone_number": "+61491570156", 
  "type": "mobile", 
  "carrier": { 
      "name": "Telstra" 

If neither of those are your go-to programming languages, we’ve got SDKs for Ruby, Java, C# and PHP. If SDKs aren’t your thing, read up on our API reference documentation to connect your website or application.


Getting better acquainted with the numbers in your contact database carries a host of benefits. From checking the validity, type and carrier records of phone numbers to reducing the number of failed or undeliverable messages sent. A simple call to our user-friendly REST API is all you need to retrieve detailed information on your contact numbers.

Ready to roll?

Image for Ready to roll?