Use this endpoint to validate and format landline or mobile phone numbers using the /phonelookup 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}/phonelookup?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 .. Only works on formats that use spaces (1, 2, 3, 4, 6) |
Optional |
POST request
Endpoint
POST https://{SERVER_ADDRESS}/{VERSION}/phonelookupSend 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. Accepted values: - and .. Only works on formats that use spaces (1, 2, 3, 4, 6) |
Optional |
Example
{
"country": "FRA",
"phone": "0611223344",
"format": 2,
"status": true,
"timeout": 0.5,
"separator": "."
}Format values
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
| 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 |
MOBILE or FIXED_LINE or FIXED_LINE_OR_MOBILE or Empty |
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 |
See also
Related to