Phone Validation - RESTful API
The phonelookup endpoint validates and formats landline or mobile phone numbers, returning carrier, location, and type information, with optional activity status.
When to use this endpoint - Call
phonelookup to validate a phone number and retrieve
its carrier, type, and location in a single JSON response.
Looking for the legacy XML/form-based integration instead?
See
Classic Phone API (/TEL/) →
phonelookup
Request
Both GET and POST are supported.
{SERVER_ADDRESS} and
{LICENCE_CODE} are provided by DQE upon
account creation. Contact your DQE account manager to obtain
these credentials.
GEThttps://{SERVER_ADDRESS}/v1/phonelookup/?Number={NUMBER}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}&Format={FORMAT}&Activity={ACTIVITY}&TimeOut={TIMEOUT}&Separator={SEPARATOR}
Code examples
Valid mobile number
curl "https://{SERVER_ADDRESS}/v1/phonelookup/?Number=0606060606&Country=FRA&Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/v1/phonelookup/?"
+ new URLSearchParams({
Number: "0606060606",
Country: "FRA",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/v1/phonelookup/",
params={
"Number": "0606060606",
"Country": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'Number' => '0606060606',
'Country' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/v1/phonelookup/?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
axios.get('https://{SERVER_ADDRESS}/v1/phonelookup/',
{
params: {
Number: '0606060606',
Country: 'FRA',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/v1/phonelookup/"
+ "?Number=0606060606&Country=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var url = "https://{SERVER_ADDRESS}/v1/phonelookup/"
+
"?Number=0606060606&Country=FRA&Licence={LICENCE_CODE}";
var response = await client.GetAsync(url);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://{SERVER_ADDRESS}/v1/phonelookup/"
+
"?Number=0606060606&Country=FRA&Licence={LICENCE_CODE}"
resp, err := http.Get(url)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
POSThttps://{SERVER_ADDRESS}/v1/phonelookup/
Send all parameters in the request body using
Content-Type: application/x-www-form-urlencoded.
The server address remains in the URL.
Code examples
Valid mobile number
curl -X POST "https://{SERVER_ADDRESS}/v1/phonelookup/"
\
-H "Content-Type: application/x-www-form-urlencoded"
\
-d "Number=0606060606" \
-d "Country=FRA" \
-d "Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/v1/phonelookup/",
{
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
Number: "0606060606",
Country: "FRA",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/v1/phonelookup/",
data={
"Number": "0606060606",
"Country": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/v1/phonelookup/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'Number' => '0606060606',
'Country' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
const qs = require('querystring');
axios.post('https://{SERVER_ADDRESS}/v1/phonelookup/',
qs.stringify({
Number: '0606060606',
Country: 'FRA',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "Number=0606060606&Country=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/v1/phonelookup/"))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var form = new Dictionary<string, string>
{
["Number"] = "0606060606",
["Country"] = "FRA",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/v1/phonelookup/",
new FormUrlEncodedContent(form));
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
form := url.Values{}
form.Set("Number", "0606060606")
form.Set("Country", "FRA")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/v1/phonelookup/",
form)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
Parameters
| Parameter | Description | Mand / Opt |
|---|---|---|
| Number | Phone number to validate. | Mandatory |
| Country | ISO 3-letter country code. | Mandatory |
| Licence | Your DQE licence key. Contact support if you do not yet have one. | Mandatory |
| Format | Desired output format. See the format values table below. | Optional |
| Activity |
Y if you want to get the activity
of the phone number.
|
Optional |
| TimeOut |
Maximum query time for verification, in seconds.
Example: 0.5 for 500 ms.
|
Optional |
| Separator |
Separator character used in the formatted phone
number. Accepted values: - and ..
Only works on formats that use spaces (1, 2,
3, 4, 6)
|
Optional |
Format values
The following values apply to the Format parameter
in both GET and POST requests.
| Value | Description | Examples (Germany / France / USA) |
|---|---|---|
| 0 | National format without spaces | 0301234567 / 0123456789 / (202)555-0123 |
| 1 | National format with country-specific digit grouping | 030 1234567 / 01 23 45 67 89 / (202) 555-0123 |
| 2 | International format with country-specific digit grouping | +49 30 1234567 / +33 1 23 45 67 89 / +1 202-555-0123 |
| 3 | International format with space between country code and subscriber number | +49 301234567 / +33 123456789 / +1 2025550123 |
| 4 | International format with trunk prefix and compact subscriber number | +49 (0)301234567 / +33 (0)123456789 / +1 (0)2025550123 |
| 5 | International format without spaces | +49301234567 / +33123456789 / +12025550123 |
| 6 | International format with trunk prefix and country-specific digit grouping | +49 (0) 30 1234567 / +33 (0) 1 23 45 67 89 / +1 (0) (202) 555-0123 |
| 7 | National format with dot-separated country-specific digit grouping | 030.1234567 / 01.23.45.67.89 / (202).555-0123 |
| 8 | International format with dot-separated country-specific digit grouping | +49.30.1234567 / +33.1.23.45.67.89 / +1.202-555-0123 |
| 9 | International format without spaces and without leading plus sign | 49301234567 / 33123456789 / 1202-555-0123 |
Response
On success, the API returns a JSON object containing the number of results and an array of validated phone numbers.
Business reading:
IdError carries
the detailed validation outcome (0: invalid
or non-existing, 1: valid and attributed,
2: valid syntax only, not attributed) — see
the full list in the
API Response Codes reference.
| Key | Description | Type |
|---|---|---|
| Found | Number of phone numbers returned. | Integer |
| Phones | Array of validation results, one entry per phone number submitted. | Array |
| IdError | Validation return code. See the API Response Codes reference. | String |
| Ported |
Y if the number has been ported;
empty when not available.
|
String |
| InputNumber | Phone number as submitted in the request. | String |
| Carrier | Current carrier of the phone number. | String |
| Location | Geographic location associated with the phone number. | String |
| OldCarrier | Previous carrier of the phone number, when known. | String |
| NumberFormatted | Phone number formatted according to the selected format. | String |
| Type |
MOBILE or FIXED_LINE
or Empty.
|
String |
Response example
Valid mobile number
{
"Found": 1,
"Phones": [
{
"IdError":
"1",
"Ported":
"",
"InputNumber":
"0606060606",
"Carrier":
"E*MESSAGE WIRELESS INFORMATION SERVICES FRANCE",
"Location":
"METROPOLE",
"OldCarrier":
"E*MESSAGE WIRELESS INFORMATION SERVICES FRANCE",
"NumberFormatted":
"0606060606",
"Type":
"MOBILE"
}
]
}
Errors
| HTTP | Error type | Response body |
|---|---|---|
| 400 |
Missing or empty mandatory parameter (e.g. Number)
|
{"status": 400, "message": "Missing parameters",
"details": "Number", "error": "bad request"}
|
| 401 | Invalid or unauthorized licence key |
{"status": 401, "message": "Your licence
is not allowed to cover this functionnality",
"details": "deded", "error": "unauthorized_client"}
|
Test the API
Click the button below to test this endpoint live in your browser.
Open console
See also
Related to