Phone API — Validate and standardise a phone number

Support DQE
Support DQE
  • Updated
Phone Validation - Classic API

The /TEL/ endpoint validates and standardises a landline or mobile phone number, with optional Level 2 verification for French mobile numbers.

When to use this endpoint - Call /TEL/ using DQE's legacy XML/form-based integration to validate a phone number and retrieve its carrier and type. Looking for the modern JSON integration instead? See Restful Phone API (/phonelookup) →

/TEL/

Jump to Parameters Response Example Errors ▶ Test the API

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}/TEL/?Pays={COUNTRY_CODE}&Tel={TEL}&Format={FORMAT}&Status=Y&TimeOut={TIME}&Separator={SYMBOL}&Licence={LICENCE_CODE}

Code examples

Valid mobile number

curl "https://{SERVER_ADDRESS}/TEL/?Pays=FRA&Tel=0611223344&Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/TEL/?" + new URLSearchParams({ Pays: "FRA", Tel: "0611223344", Licence: "{LICENCE_CODE}" })) .then(r => r.json()) .then(data => console.log(data));
import requests response = requests.get( "https://{SERVER_ADDRESS}/TEL/", params={ "Pays": "FRA", "Tel": "0611223344", "Licence": "{LICENCE_CODE}", }, ) print(response.json())
<?php $params = http_build_query([ 'Pays' => 'FRA', 'Tel' => '0611223344', 'Licence' => '{LICENCE_CODE}', ]); $ch = curl_init("https://{SERVER_ADDRESS}/TEL/?{$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}/TEL/', { params: { Pays: 'FRA', Tel: '0611223344', Licence: '{LICENCE_CODE}' } }) .then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient(); String url = "https://{SERVER_ADDRESS}/TEL/" + "?Pays=FRA&Tel=0611223344&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}/TEL/" + "?Pays=FRA&Tel=0611223344&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}/TEL/" + "?Pays=FRA&Tel=0611223344&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}/TEL/

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}/TEL/" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "Pays=FRA" \ -d "Tel=0611223344" \ -d "Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/TEL/", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ Pays: "FRA", Tel: "0611223344", Licence: "{LICENCE_CODE}" }) }) .then(r => r.json()) .then(data => console.log(data));
import requests response = requests.post( "https://{SERVER_ADDRESS}/TEL/", data={ "Pays": "FRA", "Tel": "0611223344", "Licence": "{LICENCE_CODE}", }, ) print(response.json())
<?php $ch = curl_init("https://{SERVER_ADDRESS}/TEL/"); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([ 'Pays' => 'FRA', 'Tel' => '0611223344', '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}/TEL/', qs.stringify({ Pays: 'FRA', Tel: '0611223344', Licence: '{LICENCE_CODE}' })) .then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient(); String form = "Pays=FRA&Tel=0611223344&Licence={LICENCE_CODE}"; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://{SERVER_ADDRESS}/TEL/")) .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> { ["Pays"] = "FRA", ["Tel"] = "0611223344", ["Licence"] = "{LICENCE_CODE}" }; var response = await client.PostAsync( "https://{SERVER_ADDRESS}/TEL/", 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("Pays", "FRA") form.Set("Tel", "0611223344") form.Set("Licence", "{LICENCE_CODE}") resp, err := http.PostForm("https://{SERVER_ADDRESS}/TEL/", form) if err != nil { panic(err) } defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) fmt.Println(string(body)) }

Parameters

Parameter Description Mand / Opt
Licence Licence code assigned to your account. Contact support if you do not yet have one. Mandatory
Pays ISO 3-letter country code. Mandatory
Tel Phone number to validate. Mandatory
Format Desired formatting level. See the format values table below. Optional
Status Y enables level 2 verification for French mobile phone numbers and returns the additional Status and LabelStatus fields. 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 with a single key "1" — a legacy artifact of this endpoint's implementation — wrapping the actual result fields below.

Level 1 vs Level 2 - TelOrigine, Geolocation, Tel, Operator, IdError, OldOperator, and Type are always returned (Level 1 verification: existence and format of the phone number). LabelStatus and an updated Status value are only added when Status=Y is passed in the request (Level 2 verification, French mobile numbers only).

Level 1 verification fields

Key Description Type
TelOrigine Phone number analyzed. String
Geolocation Location where the number was initially assigned. String
Tel Phone number formatted according to the selected format. String
Ported Empty in level 1 verification. String
Operator Operator to whom the phone number was initially assigned. String
IdError 2: valid syntax; 1: valid and attributed; 0: invalid or non-existing number. Integer
OldOperator Original operator of the phone number. String
Type MOBILE or FIXED_LINE or FIXED_LINE_OR_MOBILE or Empty. String

Level 2 verification fields

Warning: reachable information is no longer provided. This variable is retained for historical purposes.

Level 2 verification provides activity status and operator information. Enable it by passing Status=Y in the request. The JSON response contains the following additional (or updated) fields:

Key Description Type
Ported Y if the number has been ported, N otherwise. String(1)
Operator Current operator of the phone number. String
OldOperator Previous operator when the number has been ported. String
LabelStatus Reachable or No reachable information (mobile only). String
Status 0: reachable; 1: no reachable information. String

Response example

Level 1 (standard)
{ "1": { "TelOrigine": "+12XXXXXXXXX", "Geolocation": "UNITED STATES OF AMERICA", "Tel": "+12345678910", "Ported": "", "Operator": "FIRST COMMUNICATIONS", "IdError": 1, "OldOperator": "FIRST COMMUNICATIONS", "Type": "MOBILE" } }
Level 2 (with Status=Y)
{ "1": { "TelOrigine": "0XXXXXXXXX", "Geolocation": "FRANCE", "LabelStatus": "Not Reachable", "Tel": "0XXXXXXXXX", "Ported": "N", "Status": "1", "Operator": "ORANGE", "IdError": 1, "OldOperator": "", "Type": "MOBILE" } }

Errors

Error type Response type
Missing Licence parameter Licence Down error in the JSON response.
Empty Licence parameter Licence Down error in the JSON response.
Incorrect licence number Licence Down error in the JSON response.
Missing or empty Tel parameter 400 Bad Request
Parameter typo 400 Bad Request

Example of licence error:

{ "1": { "TelOrigine": "06XXXXXXXX", "Geolocation": "", "Tel": "", "Ported": "", "Operator": "", "IdError": 0, "OldOperator": "", "Error": "Licence Down" } }

Test the API

Click the button below to test this endpoint live in your browser.

Open console

See also

Related to

Was this article helpful?

0 out of 0 found this helpful