CarrierLookup
Returns information about a destination phone number, including whether the number type and whether it is valid, the carrier, and more.
Request Syntax
{
"PhoneNumber": "string"
}Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- PhoneNumber
-
The phone number that you want to retrieve information about. You can provide the phone number in various formats including special characters such as parentheses, brackets, spaces, hyphens, periods, and commas. The service automatically converts the input to E164 format for processing.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 40.
Pattern:
\+[({\s\[]?[1-9][0-9(){}\s\[\],.-]{1,38}Required: Yes
Response Syntax
{
"Carrier": "string",
"Country": "string",
"DialingCountryCode": "string",
"E164PhoneNumber": "string",
"IsoCountryCode": "string",
"MCC": "string",
"MNC": "string",
"PhoneNumberType": "string"
}Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- Carrier
-
The carrier or service provider that the phone number is currently registered with. In some countries and regions, this value may be the carrier or service provider that the phone number was originally registered with.
Type: String
- Country
-
The name of the country or region for the phone number.
Type: String
- DialingCountryCode
-
The country or region numeric dialing code for the phone number.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 3.
Pattern:
[\d]+ - E164PhoneNumber
-
The phone number in E164 format, sanitized from the original input by removing any formatting characters.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 20.
Pattern:
\+[1-9][0-9]{1,18} - IsoCountryCode
-
The two-character country or region code, in ISO 3166-1 alpha-2 format, for the phone number.
Type: String
Length Constraints: Fixed length of 2.
Pattern:
[A-Z]{2} - MCC
-
The phone number's mobile country code, for mobile phone number types
Type: String
Length Constraints: Fixed length of 3.
Pattern:
[\d]+ - MNC
-
The phone number's mobile network code, for mobile phone number types.
Type: String
Length Constraints: Minimum length of 2. Maximum length of 3.
Pattern:
[\d]+ - PhoneNumberType
-
Describes the type of phone number. Valid values are: MOBILE, LANDLINE, OTHER, and INVALID. Avoid sending SMS or voice messages to INVALID phone numbers, as these numbers are unlikely to belong to actual recipients.
Type: String
Valid Values:
MOBILE | LANDLINE | OTHER | INVALID
Errors
For information about the errors that are common to all actions, see Common Errors.
- AccessDeniedException
-
The request was denied because you don't have sufficient permissions to access the resource.
- Reason
-
The reason for the exception.
HTTP Status Code: 400
- InternalServerException
-
The API encountered an unexpected error and couldn't complete the request. You might be able to successfully issue the request again in the future.
- RequestId
-
The unique identifier of the request.
HTTP Status Code: 500
- ServiceQuotaExceededException
-
The request would cause a service quota to be exceeded.
- Reason
-
The reason for the exception.
HTTP Status Code: 400
- ThrottlingException
-
An error that occurred because too many requests were sent during a certain amount of time.
HTTP Status Code: 400
- ValidationException
-
A validation exception for a field.
- Fields
-
The field that failed validation.
- Reason
-
The reason for the exception.
HTTP Status Code: 400
Examples
Example
A carrier lookup response for a valid mobile number.
{ "PhoneNumber": "+1 (555) 555-5333" }
{ "Carrier": "ExampleCorp Mobile", "Country": "United States", "IsoCountryCode": "US", "MCC": "111", "MNC": "11", "DialingCountryCode": "1", "E164PhoneNumber": "+15555555333", "PhoneNumberType": "MOBILE" }
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
