Phone API — Validate and standardise a phone number

Support DQE
Support DQE
  • Updated

Use this endpoint to validate and format a phone number using the /TEL/ endpoint.

Related Phone documentation:

GET request

Endpoint

https://{SERVER_ADDRESS}/TEL/?Pays={COUNTRY_CODE}&Tel={TEL}&Format={FORMAT}&Status=Y&TimeOut={TIME}&Separator={SYMBOL}&Licence={LICENCE_CODE}

Replace the values in braces with your own information:

Parameter Value Description Mandatory/Optional
SERVER_ADDRESS {SERVER_ADDRESS} Address of the DQE server that will process the data. Mandatory
Licence {LICENCE_CODE} Licence code assigned to your account. Mandatory
Pays {COUNTRY_CODE} ISO 3-letter country code. Mandatory
Tel {TEL} Phone number to validate. Mandatory
Format {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 {TIME} Maximum query time for verification, in seconds. Example: 0.5 for 500 ms. Optional
Separator {SYMBOL} Separator character used in the formatted phone number. Accepted values: - and .. Only works on formats that use spaces (1, 2, 3, 4, 6) Optional

POST request

Endpoint

https://{SERVER_ADDRESS}/TEL/

Send the following parameters in the request body using x-www-form-urlencoded.

Parameter Value Description Mandatory/Optional
Licence {LICENCE_CODE} Licence code assigned to your account. Mandatory
Pays {COUNTRY_CODE} ISO 3-letter country code. Mandatory
Tel {TEL} Phone number to validate. Mandatory
Format {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 {TIME} Maximum query time for verification, in seconds. Example: 0.5 for 500 ms. Optional
Separator {SYMBOL} 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

Success response

Level 1 verification

Level 1 verification validates the existence and format of the phone number.

The JSON response contains a key 1 with the following 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

Example:

{
  "1": {
    "TelOrigine": "+12XXXXXXXXX",
    "Geolocation": "UNITED STATES OF AMERICA",
    "Tel": "+12345678910",
    "Ported": "",
    "Operator": "FIRST COMMUNICATIONS",
    "IdError": 1,
    "OldOperator": "FIRST COMMUNICATIONS",
    "Type": "MOBILE"
  }
}

Level 2 verification

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

Example with Status=Y:

{
  "1": {
    "TelOrigine": "0XXXXXXXXX",
    "Geolocation": "FRANCE",
    "LabelStatus": "Not Reachable",
    "Tel": "0XXXXXXXXX",
    "Ported": "N",
    "Status": "1",
    "Operator": "ORANGE",
    "IdError": 1,
    "OldOperator": "",
    "Type": "MOBILE"
  }
}

Error response

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"
  }
}

See also

Related to

Was this article helpful?

0 out of 0 found this helpful