Amazon Pinpoint
REST API Reference

Phone Number Validate

Use this resource to convert an incoming phone number into E.164 format, and to get more information about the 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 indicates whether the phone number is valid, and the type of phone line that it's associated with (for example, whether it's a mobile or landline number). It also includes 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

Returns information about the specified phone number.

Body

Name Required Type

NumberValidateRequest

true

NumberValidateRequest

Header

Name Required Type

accept

false

string

Response

Status Code Schema

200

NumberValidateResponse

Errors

Errors

Status Code Schema Error Type

400

MessageBody

BadRequestException

403

MessageBody

ForbiddenException

404

MessageBody

NotFoundException

405

MessageBody

MethodNotAllowedException

429

MessageBody

TooManyRequestsException

500

MessageBody

InternalServerErrorException

Schemas

Request Schemas

Example NumberValidateRequest

{ "PhoneNumber": "12065550199", "IsoCountryCode": "US" }

Response Schemas

Example NumberValidateResponse

{ "CountryCodeIso2": "US", "CountryCodeNumeric": "1", "Country": "United States", "City": "Seattle", "ZipCode": "98108", "County": "King", "Timezone": "America/Los Angeles", "CleansedPhoneNumberNational": "2065550199", "CleansedPhoneNumberE164": "+12065550199", "Carrier": "Example Corp.", "PhoneTypeCode": 0, "PhoneType": "MOBILE", "OriginalPhoneNumber": "12065550199", "OriginalCountryCodeIso2": "US" }

Example MessageBody

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

Attributes

NumberValidateRequest

Attribute Type Description

IsoCountryCode

string

(Optional) The two-character ISO country code for the country or region where the phone number was originally registered.

PhoneNumber

string

The phone number to get information about. The phone number that you provide should include a country code. If the number doesn't include a valid country code, the operation might result in an error.

NumberValidateResponse

Attribute Type Description

Carrier

string

The carrier or servive provider that the phone number is currently registered with.

City

string

The city where the phone number was originally registered.

CleansedPhoneNumberE164

string

The cleansed phone number, shown in E.164 format.

CleansedPhoneNumberNational

string

The cleansed phone number, shown in the local phone number format.

Country

string

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

CountryCodeIso2

string

The two-character ISO code for the country or region where the phone number was originally registered.

CountryCodeNumeric

string

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

County

string

The county where the phone number was originally registered.

OriginalCountryCodeIso2

string

The two-character code (in ISO 3166-1 alpha-2 format) for the country or region in the request body.

OriginalPhoneNumber

string

The phone number that you included in the request body.

PhoneType

string

A description of the phone type. Possible values are MOBILE, LANDLINE, VOIP, INVALID, PREPAID, and OTHER.

PhoneTypeCode

integer

The phone type, represented by an integer. Possible values include 0 (MOBILE), 1 (LANDLINE), 2 (VOIP), 3 (INVALID), 4 (OTHER), and 5 (PREPAID).

Timezone

string

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

ZipCode

string

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

MessageBody

Attribute Type Description

Message

string

The error message that's returned from the API.

RequestID

string

The unique message body ID.