Skip to content

Number Lookup

The D7 Number Lookup API provides a comprehensive set of features for retrieving information about specific phone numbers. It offers access to various details, including country, network, MCC (Mobile Country Code), MNC (Mobile Network Code), status, and more.

By utilizing the Number Lookup API, you can easily perform Reverse Phone Lookup operations. Simply input the phone number, and the API will retrieve the relevant information associated with it.

POST
/hlr/v1/lookup

Authentication

AUTHORIZATION: Bearer Token

Request parameters

Parameter Value / Pattern
*recipient Phone Number to get details. The phone number should have a country code prefix. Allowed only one phone number at a time.

Response

Once the request is validated, you will receive complete information pertaining to the requested number.

200 - Success 
{
    "country_code": "IN",
    "country_code_iso3": "IND",
    "recipient": "+918156968853",
    "cic": "91077",
    "imsi": "40419XXXXXXXXXX",
    "ocn": null,
    "mcc": 404,
    "mnc": 19,
    "network": "IDEA (Vi) - Kerala",
    "ported": false,
    "reachable": "no",
    "type": "mobile",
    "status": "SUCCESS",
    "status_code": 0,
    "request_id": "f9f45e79-5d53-4550-841c-6c0a75487ede"
}
400 - Invalid Phone number 
{ 
    "detail": { 
    "code": "INVALID_PHONE_NUMBER",
    "message": "Number is not valid"
    } 
}
400 - Routing Not Found 
{ 
    "detail": { 
    "code": "ROUTING_NOT_FOUND",
    "message": "Routing not added for this user"
    } 
}
401 - Unauthorized 
{ 
    "detail": { 
    "code": "ACCESS_TOKEN_SIGNATURE_VERIFICATION_FAILED",
    "message": "It looks like your requests were failed due to a missing or invalid 'Access Token'. Sign up at https://app.d7networks.com and create an authentication token in the API Tokens Page."
    } 
}
422 - Validation Error 
{
    "detail": [
        {
            "loc": [
            "string"
            ],
        "msg": "string",
        "type": "string"
        }
    ]
}

Response Parameters

Parameter Value / Pattern
country_code Two digit code where the number belongs to.
country_code_iso3 Three digit code where the number belongs to.
recipient The number queried.
cic Carrier Identification Code for the current carrier.
imsi Some part of the International Mobile Subscriber Identity code.
ocn Operating Company Number (US, Canada, or null for the rest of the world).
mcc The Mobile Country Code of the current carrier.
mnc The Mobile Network Code of the current carrier.
network The name of the current carrier.
ported Whether the number is ported or not. Values: true/false
reachable Whether the number has been assigned e.g. is an active number Values: yes/no/na
type mobile/fixed.
status The status of number lookup.
status_code Code for the status of the Lookup.
request_id Unique id for each lookup request.

Examples:

Search Your Number details

1
2
3
4
5
6
curl --location --request POST 'https://api.d7networks.com/hlr/v1/lookup' \
--header 'Authorization: Bearer {{api_access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "recipient":{{recipient}}
}'

npm i direct7

1
2
3
4
5
6
7
const Client = require('direct7')

const client = new Client(apiToken="Your API token")

const response = await client.number_lookup.searchNumberDetails({recipient : "+91999999XXXX"});

console.log(response);

pip install direct7

1
2
3
4
5
from direct7 import Client

client = Client(api_token="Your API token")

client.number_lookup.search_number_details(recipient="+914257845XXXX")


composer require direct7/direct7-php

require_once 'vendor/autoload.php';

1
2
3
4
5
6
7
8
require_once __DIR__ . '/vendor/autoload.php';

use direct7\Direct7\Client;

$client = new Client(api_token="Your API token")

$response = $direct7->number_lookup->searchNumberDetails(recipient:'+91999999XXXX');
var_dump($response);

go get -u github.com/d7networks/direct7-go-sdk

1
2
3
4
5
6
7
8
import (
"github.com/d7networks/direct7-go-sdk/direct7"
)   
apiToken := "Your Api Token"
client := direct7.NewClient(apiToken)
numberLookup := direct7.NewNumberLookup(client)
recipient := "+919999XXXXXX"
response, err := numberLookup.SearchNumberDetails(recipient)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"recipient\":\"{{recipient}}\"\n}");
Request request = new Request.Builder()
.url("https://api.d7networks.com/hlr/v1/lookup")
.method("POST", body)
.addHeader("Authorization", "Bearer {{api_access_token}}")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
var headers = {
'Authorization': 'Bearer {{api_access_token}}',
'Content-Type': 'application/json'
};
var request = http.Request('POST', Uri.parse('https://api.d7networks.com/hlr/v1/lookup'));
request.body = json.encode({
"recipient": "{{recipient}}"
});
request.headers.addAll(headers);

http.StreamedResponse response = await request.send();

if (response.statusCode == 200) {
print(await response.stream.bytesToString());
}
else {
print(response.reasonPhrase);
}

1
2
3
4
5
6
7
8
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "Bearer {{api_access_token}}")
$headers.Add("Content-Type", "application/json")

$body = "{`n    `"recipient`":`"{{recipient}}`"`n}"

$response = Invoke-RestMethod 'https://api.d7networks.com/hlr/v1/lookup' -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json

gem install direct7

1
2
3
4
5
require 'direct7'

client = Direct7::Client.new('Your API token')

client.number_lookup.search_number_details(recipient="+914257845XXXX")

1
2
3
4
5
6
7
8
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.d7networks.com/hlr/v1/lookup");
request.Headers.Add("Authorization", "Bearer {{api_access_token}}");
var content = new StringContent("{\n    \"recipient\":\"{{recipient}}\"\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Status and Codes

Status Code Status Explanation
0 SUCCESS Successful Query
1 UNKNOWN_SUBSCRIBER Unknown subscriber: The number is not allocated.
2 NETWORK_NOT_REACHED The owning network cannot be reached.
3 NETWORK_CANNOT_REACH_NUMBER The network cannot reach the number.
4 NUMBER_LOCATION_NOT_KNOWN_TO_NETWORK The location of the number is not known to the network.
5 NUMBER_NOT_KNOWN_TO_MSC The number is not known to the MSC (Mobile Switching Center)
6 NUMBER_ABSENT_FOR_SM The number is absent for SM.
7 UNKNOWN_EQUIPMENT Unknown equipment.
8 ROAMING_NOT_ALLOWED Roaming not allowed.
9 ILLEGAL_SUBSCRIBER Illegal subscriber.
10 BEARER_SERVICE_NOT_PROVISIONED Bearer service not provisioned.
11 TELE_SERVICE_NOT_PROVISIONED Tele-service not provisioned.
12 ILLEGAL_EQUIPMENT Illegal Equipment.
13 CALL_BARRED call barred
21 FACILITY_NOT_SUPPORTED Facility not supported.
27 PHONE_SWITCHED_OFF Phone switched off.
28 INCOMPATIBLE_TERMINAL Incompatible terminal.
31 SUBSCRIBER_BUSY The subscriber is busy.
32 SM_DELIVERY_FAILED The delivery of the SM has failed.
33 CONGESTION_OCCURRED A congestion (a full waiting list) occurred.
34 SYSTEM_FAILURE System failure.
35 MISSING_DATA Missing data.
36 DATA_ERROR Data Error.
37 INVALID_NUMBER Invalid Phone Number.
38 NOT_ALLOWED_COUNTRY Not Allowed Country.
191 UNSUPPORTED_MOBILE_NETWORK_WITH_PORT_CORRECTION Unsupported mobile network with port correction
192 UNSUPPORTED_MOBILE_NETWORK_WITHOUT_PORT_CORRECTION Unsupported mobile network without port correction.
193 LANDLINE_NETWORK Landline network (not covered).