MNP Lookup

Overview

Query mobile number portability (MNP) information to identify the current operator and network details for any phone number. The MNP Lookup API returns real-time network information including Mobile Country Codes (MCC), Mobile Network Codes (MNC), current operator, and porting status.

Use cases:

• Verify routing before sending SMS to ensure delivery to the correct operator
• Detect number porting to optimize routing and prevent delivery delays
• Confirm network information for regulatory compliance
• Identify operators for intelligent rate optimization
• Validate numbers before bulk SMS campaigns

Making a Request

Endpoint

GET https://mnp.agiletelecom.com/services/mnp/number-lookup?msisdn=+39333123123

Authentication

Choose one of three supported methods:

• Basic Auth: Provide your username and password encoded in the Authorization header
• API Key: Include your API key in the X-Api-Key header
• OAuth 1.1: Use OAuth 1.1 authentication in the Authorization header

Query Parameters

Parameter	Type	Description
msisdn	string	The telephone number to query. The leading "+" may be omitted, but you must include the country code. Examples: +39333123123 or 39333123123

Code Examples

cURL

# Using API Key authentication
curl -X GET "https://mnp.agiletelecom.com/services/mnp/number-lookup?msisdn=%2B39333123123" \
  -H "X-Api-Key: YOUR_API_KEY"

# Using Basic Auth authentication
curl -X GET "https://mnp.agiletelecom.com/services/mnp/number-lookup?msisdn=%2B39333123123" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"

Python

import requests

# Using API Key
headers = {
    "X-Api-Key": "YOUR_API_KEY"
}

params = {
    "msisdn": "+39333123123"
}

response = requests.get(
    "https://mnp.agiletelecom.com/services/mnp/number-lookup",
    headers=headers,
    params=params
)

data = response.json()
print(f"Operator: {data['operator']}")
print(f"Country: {data['country']}")
print(f"Ported: {data['ported']}")

Node.js

const axios = require('axios');

// Using API Key
const headers = {
  'X-Api-Key': 'YOUR_API_KEY'
};

const params = {
  msisdn: '+39333123123'
};

axios.get('https://mnp.agiletelecom.com/services/mnp/number-lookup', { 
  headers, 
  params 
})
  .then(response => {
    console.log(`Operator: ${response.data.operator}`);
    console.log(`Country: ${response.data.country}`);
    console.log(`Ported: ${response.data.ported}`);
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$msisdn = urlencode('+39333123123');

$ch = curl_init("https://mnp.agiletelecom.com/services/mnp/number-lookup?msisdn=$msisdn");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . $apiKey
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);

if (json_last_error() === JSON_ERROR_NONE) {
    echo "Operator: " . $data['operator'] . "\n";
    echo "Country: " . $data['country'] . "\n";
    echo "Ported: " . ($data['ported'] ? 'Yes' : 'No');
} else {
    echo "Error decoding response";
}

curl_close($ch);
?>

Java

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import org.json.JSONObject;

public class MNPLookup {
    public static void main(String[] args) throws Exception {
        String msisdn = URLEncoder.encode("+39333123123", StandardCharsets.UTF_8);
        HttpClient client = HttpClient.newHttpClient();
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://mnp.agiletelecom.com/services/mnp/number-lookup?msisdn=" + msisdn))
            .header("X-Api-Key", "YOUR_API_KEY")
            .GET()
            .build();
        
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
        
        JSONObject json = new JSONObject(response.body());
        System.out.println("Operator: " + json.getString("operator"));
        System.out.println("Country: " + json.getString("country"));
        System.out.println("Ported: " + json.getBoolean("ported"));
    }
}

C#

using System;
using System.Net.Http;
using System.Web;
using System.Threading.Tasks;
using Newtonsoft.Json;

class MNPLookup {
    static async Task Main() {
        using (HttpClient client = new HttpClient()) {
            client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
            
            try {
                string msisdn = HttpUtility.UrlEncode("+39333123123");
                string url = $"https://mnp.agiletelecom.com/services/mnp/number-lookup?msisdn={msisdn}";
                
                HttpResponseMessage response = await client.GetAsync(url);
                string content = await response.Content.ReadAsStringAsync();
                dynamic data = JsonConvert.DeserializeObject(content);
                
                Console.WriteLine($"Operator: {data.@operator}");
                Console.WriteLine($"Country: {data.country}");
                Console.WriteLine($"Ported: {data.ported}");
            } catch (Exception ex) {
                Console.WriteLine($"Error: {ex.Message}");
            }
        }
    }
}

Go

package main

import (
    "fmt"
    "io"
    "net/http"
    "net/url"
    "encoding/json"
)

type MNPResponse struct {
    Number     string `json:"number"`
    MCC        string `json:"mcc"`
    MNC        string `json:"mnc"`
    NumberType string `json:"numbertype"`
    Ported     bool   `json:"ported"`
    Operator   string `json:"operator"`
    Country    string `json:"country"`
}

func main() {
    params := url.Values{}
    params.Add("msisdn", "+39333123123")
    
    client := &http.Client{}
    req, _ := http.NewRequest("GET", 
        "https://mnp.agiletelecom.com/services/mnp/number-lookup?"+params.Encode(), nil)
    req.Header.Add("X-Api-Key", "YOUR_API_KEY")
    
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()
    
    body, _ := io.ReadAll(resp.Body)
    var data MNPResponse
    json.Unmarshal(body, &data)
    
    fmt.Printf("Operator: %s\n", data.Operator)
    fmt.Printf("Country: %s\n", data.Country)
    fmt.Printf("Ported: %v\n", data.Ported)
}

Ruby

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://mnp.agiletelecom.com/services/mnp/number-lookup')
uri.query = URI.encode_www_form('msisdn' => '+39333123123')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['X-Api-Key'] = 'YOUR_API_KEY'

response = http.request(request)
data = JSON.parse(response.body)

puts "Operator: #{data['operator']}"
puts "Country: #{data['country']}"
puts "Ported: #{data['ported']}"

Success Response (2XX)

When the lookup succeeds, the API returns network and operator information:

{
  "number": "+39333123123",
  "mcc": "222",
  "mnc": "10",
  "numbertype": "mobile",
  "ported": false,
  "operator": "Vodafone",
  "country": "Italia"
}

Field	Type	Description
number	string	The queried telephone number in international format
mcc	string	Mobile Country Code currently associated with the number
mnc	string	Mobile Network Code currently associated with the number
numbertype	string	Fixed value "mobile". Indicates the type of number
ported	boolean	true if the subscriber has transferred their number to a different operator; false otherwise
operator	string	Current operator name of the queried number
country	string	Country name currently associated with the number

Client Error Response (4XX)

When the request is invalid or missing required parameters:

{
  "error_code": 400,
  "error_description": "Specify a msisdn number"
}

Field	Type	Description
error_code	integer	HTTP error code returned
error_description	string	Description related to the error code

Common 4XX Errors

• 400: Missing or invalid msisdn parameter
• 400: Invalid number format

Server Error Response (5XX)

When a server-side error occurs:

{
  "error_code": 500,
  "error_description": "Server error"
}

Field	Type	Description
error_code	integer	HTTP error code returned
error_description	string	Description related to the error code

Ported Numbers & Routing

The ported field indicates whether the subscriber has transferred their number to a different operator. Use this information for intelligent routing decisions, load balancing across operators, and delivery optimization. Ported numbers may route through different gateways depending on the current operator.

What's next?

• SMPP Protocol – Persistent connection protocol for high-volume messaging
• Inbound SMS – Receive SMS on your dedicated number
• Credit Check – Monitor your account balance