Amazon Pinpoint
REST API Reference

Phone Number Validate

You can use the Phone Number Validate resource to convert a phone number to E.164 format and to get more information about a phone number.

This resource accepts a POST request that includes a phone number in the request body. It responds with information about the phone number. This information includes whether the phone number is valid and the type of phone line that's associated with the number, such as mobile or landline. It also provides other helpful information about the number, such as the carrier that the number is registered with and the location where the number was originally registered.

URI

/v1/phone/number/validate

HTTP Methods

POST

Operation ID: PhoneNumberValidate

Retrieves information about a phone number.

Header Parameters

Name Type Required Description
accept String False

Indicates which content types, expressed as MIME types, the client understands.

Responses

Status Code Response Model Description
200 NumberValidateResponse

The request succeeded.

400 MessageBody

The request contains a syntax error (BadRequestException).

403 MessageBody

The request was denied because access to the specified resource is forbidden (ForbiddenException).

404 MessageBody

The request failed because the specified resource was not found (NotFoundException).

405 MessageBody

The request failed because the method is not allowed for the specified resource (MethodNotAllowedException).

429 MessageBody

The request failed because too many requests were sent during a certain amount of time (TooManyRequestsException).

500 MessageBody

The request failed due to an unknown internal server error, exception, or failure (InternalServerErrorException).

OPTIONS

Retrieves information about the communication requirements and options that are available for the Phone Number Validate resource.

Responses

Status Code Response Model Description
200 None

The request succeeded.

Schemas

Request Bodies

Example POST

{ "PhoneNumber": "string", "IsoCountryCode": "string" }

Response Bodies

Example NumberValidateResponse

{ "CountryCodeIso2": "string", "CountryCodeNumeric": "string", "Country": "string", "City": "string", "ZipCode": "string", "County": "string", "Timezone": "string", "CleansedPhoneNumberNational": "string", "CleansedPhoneNumberE164": "string", "Carrier": "string", "PhoneTypeCode": integer, "PhoneType": "string", "OriginalPhoneNumber": "string", "OriginalCountryCodeIso2": "string" }

Example MessageBody

{ "RequestID": "string", "Message": "string" }

Properties

MessageBody

Provides information about an API request or response.

Property Type Required Description
RequestID

string

False

The unique identifier for the request or response.

Message

string

False

The message that's returned from the API.

NumberValidateRequest

Specifies a phone number to validate and retrieve information about.

Property Type Required Description
PhoneNumber

string

False

The phone number to retrieve information about. The phone number that you provide should include a valid numeric country code. Otherwise, the operation might result in an error.

IsoCountryCode

string

False

The two-character code, in ISO 3166-1 alpha-2 format, for the country or region where the phone number was originally registered.

NumberValidateResponse

Provides information about a phone number.

Property Type Required Description
CountryCodeIso2

string

False

The two-character code, in ISO 3166-1 alpha-2 format, for the country or region where the phone number was originally registered.

CountryCodeNumeric

string

False

The numeric code for the country or region where the phone number was originally registered.

Country

string

False

The name of the country or region where the phone number was originally registered.

City

string

False

The name of the city where the phone number was originally registered.

ZipCode

string

False

The postal or ZIP code for the location where the phone number was originally registered.

County

string

False

The name of the county where the phone number was originally registered.

Timezone

string

False

The time zone for the location where the phone number was originally registered.

CleansedPhoneNumberNational

string

False

The cleansed phone number, in the format for the location where the phone number was originally registered.

CleansedPhoneNumberE164

string

False

The cleansed phone number, in E.164 format, for the location where the phone number was originally registered.

Carrier

string

False

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.

PhoneTypeCode

integer

False

The phone type, represented by an integer. Valid values are: 0 (mobile), 1 (landline), 2 (VoIP), 3 (invalid), 4 (other), and 5 (prepaid).

PhoneType

string

False

The description of the phone type. Valid values are: MOBILE, LANDLINE, VOIP, INVALID, PREPAID, and OTHER.

OriginalPhoneNumber

string

False

The phone number that was sent in the request body.

OriginalCountryCodeIso2

string

False

The two-character code, in ISO 3166-1 alpha-2 format, that was sent in the request body.

See Also

For more information about using this API in one of the language-specific AWS SDKs and references, see the following:

PhoneNumberValidate