Use this endpoint to validate and format landline or mobile phone numbers using the /phone/lookup endpoint.
Related Phone documentation:
- Phone introduction
- Classic Phone API (/TEL/)
- Phone output columns
- Restful Phone Swagger documentation
GET request
Endpoint
GET https://{SERVER_ADDRESS}/{VERSION}/phone/lookup?country={COUNTRY_CODE}&phone={PHONE}&format={FORMAT}&status={STATUS}&timeout={TIMEOUT}&separator={SEPARATOR}Replace the values in braces with your own information.
| Parameter | Description | Mandatory/Optional |
|---|---|---|
| country | ISO 3-letter country code. | Mandatory |
| phone | Phone number to validate. | Mandatory |
| format | Desired output format. See the format values table below. | Optional |
| status | Set to true to enable additional status verification when available. |
Optional |
| timeout | Maximum query time for verification, in seconds. | Optional |
| separator | Separator character used in the formatted phone number. Accepted values: - and .. |
Optional |
POST request
Endpoint
POST https://{SERVER_ADDRESS}/{VERSION}/phone/lookupSend the following parameters in the request body using JSON.
| Parameter | Description | Mandatory/Optional |
|---|---|---|
| country | ISO 3-letter country code. | Mandatory |
| phone | Phone number to validate. | Mandatory |
| format | Desired output format. See the format values table below. | Optional |
| status | Set to true to enable additional status verification when available. |
Optional |
| timeout | Maximum query time for verification, in seconds. | Optional |
| separator | Separator character used in the formatted phone number. | Optional |
Example
{
"country": "FRA",
"phone": "0611223344",
"format": 2,
"status": true,
"timeout": 0.5,
"separator": "."
}Format values
The following values apply to the format parameter in both GET and POST requests.
| Value | Description |
|---|---|
0 |
Phone number without spaces. |
1 |
Phone number with a space every two digits. |
2 |
Phone number in international format with spaces. |
3 |
Phone number in compact international format. |
4 |
Phone number in international format with national prefix. |
5 |
Phone number in compact international format without spaces. |
6 |
Phone number in international format with national prefix and spaces. |
7 |
Phone number separated with dots, France only. |
8 |
Phone number in international format separated with dots. |
9 |
Phone number with country code without plus sign. |
Response
Success response
The JSON response contains validation and formatting details for the provided phone number.
| Key | Description | Type |
|---|---|---|
| IdError |
2: valid syntax; 1: valid and attributed; 0: invalid or non-existing number. |
INTEGER |
| Error | Error message associated with the validation result. | STRING |
| Formatted | Formatted phone number according to the selected format. | STRING |
| International | Phone number in international format. | STRING |
| National | Phone number in national format. | STRING |
| E164 | Phone number in E.164 format. | STRING |
| Country | ISO 3-letter country code. | STRING |
| CountryCode | International dialing code. | STRING |
| NationalNumber | National significant number. | STRING |
| Type | Phone number type: mobile, landline, VOIP, etc. | STRING |
| Operator | Telecom operator when available. | STRING |
| IsValid | Indicates whether the phone number is valid. | BOOLEAN |
| IsMobile | Indicates whether the number is a mobile number. | BOOLEAN |
| Status | Status returned by the optional status verification. | STRING |
Example
{
"IdError": 0,
"Error": "",
"Formatted": "+33 6 11 22 33 44",
"International": "+33611223344",
"National": "06 11 22 33 44",
"E164": "+33611223344",
"Country": "FRA",
"CountryCode": "33",
"NationalNumber": "611223344",
"Type": "Mobile",
"Operator": "Orange",
"IsValid": true,
"IsMobile": true,
"Status": "ACTIVE"
}Error response
| Error type | Response type |
|---|---|
| Missing or invalid authentication | 401 Unauthorized |
| Missing phone parameter | 400 Bad Request |
| Invalid phone number | Validation error response |
Related to