POST api/phonenumberlookup

Validates a single phone number.

Request Information

URI Parameters

None.

Body Parameters

The number to validate and, optionally, the validation type.

PhoneNumberLookupPostModel
NameDescriptionTypeAdditional information
Number

The phone number to validate (any common US format).

 string

None.
Type

The validation type: "basic" (default) or "lineType".

 string

None.

Request Formats

application/json, text/json

Sample: 
{
  "number": "sample string 1",
  "type": "sample string 2"
}

application/xml, text/xml

Sample: 
<PhoneNumberLookupPostModel xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/GlobalPortal.Api.Models.PhoneNumberLookup">
  <Number>sample string 1</Number>
  <Type>sample string 2</Type>
</PhoneNumberLookupPostModel>

application/x-www-form-urlencoded

Sample:

Failed to generate the sample for media type 'application/x-www-form-urlencoded'. Cannot use formatter 'JQueryMvcFormUrlEncodedFormatter' to write type 'PhoneNumberLookupPostModel'.

Response Information

Resource Description

PhoneNumberLookupResultModel
NameDescriptionTypeAdditional information
IsValid

True when Twilio reports the number as valid.

 boolean

None.
Outcome

Why the number is (in)valid: "valid", "invalidFormat" (rejected locally, no Twilio call was made - fix the input), or "invalidNumber" (well-formed, but Twilio reports it invalid).

 string

None.
FormatError

string

None.
PhoneNumber

The E.164 number that was validated.

 string

None.
NationalFormat

The national-format number from Twilio (SPE-326). Omitted when Twilio did not return one.

 string

None.
CanonicalE164

Twilio's canonical E.164 form (SPE-349). Omitted when Twilio did not return one.

 string

None.
Type

The validation type this result is for ("basic" or "lineType"), echoing the request so the meaning of is unambiguous.

 string

None.
LineType

Line type (mobile/landline/voip). Omitted from the response entirely unless "lineType" was requested and Twilio returned a value.

 string

None.
CarrierName

Carrier name (SPE-348). Omitted unless "lineType" was requested and returned.

 string

None.
MobileCountryCode

Mobile country code (SPE-348). Omitted unless "lineType" was requested and returned.

 string

None.
MobileNetworkCode

Mobile network code (SPE-348). Omitted unless "lineType" was requested and returned.

 string

None.
LineTypeErrorCode

line_type_intelligence error_code (SPE-348). Omitted when there was no error.

 integer

None.
ErrorCode

Twilio API-level error code on a failed lookup (SPE-326 AC4). Omitted on success.

 integer

None.
ErrorMessage

Twilio API-level error message on a failed lookup (SPE-326 AC4). Omitted on success.

 string

None.
ValidatedUtc

When the returned data was validated (UTC): the basic validation date for a "basic" request, the line-type validation date for a "lineType" request.

 date

None.
FromCache

True when served from the cache with no Twilio call.

 boolean

None.

Response Formats

application/json, text/json

Sample: 
{
  "isValid": true,
  "outcome": "sample string 2",
  "formatError": "sample string 3",
  "phoneNumber": "sample string 4",
  "nationalFormat": "sample string 5",
  "canonicalE164": "sample string 6",
  "type": "sample string 7",
  "lineType": "sample string 8",
  "carrierName": "sample string 9",
  "mobileCountryCode": "sample string 10",
  "mobileNetworkCode": "sample string 11",
  "lineTypeErrorCode": 1,
  "errorCode": 1,
  "errorMessage": "sample string 12",
  "validatedUtc": "2026-10-12T23:25:15.3023067+00:00",
  "fromCache": true
}

application/xml, text/xml

Sample: 
<PhoneNumberLookupResultModel xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/GlobalPortal.Api.Models.PhoneNumberLookup">
  <CanonicalE164>sample string 6</CanonicalE164>
  <CarrierName>sample string 9</CarrierName>
  <ErrorCode>1</ErrorCode>
  <ErrorMessage>sample string 12</ErrorMessage>
  <FormatError>sample string 3</FormatError>
  <FromCache>true</FromCache>
  <IsValid>true</IsValid>
  <LineType>sample string 8</LineType>
  <LineTypeErrorCode>1</LineTypeErrorCode>
  <MobileCountryCode>sample string 10</MobileCountryCode>
  <MobileNetworkCode>sample string 11</MobileNetworkCode>
  <NationalFormat>sample string 5</NationalFormat>
  <Outcome>sample string 2</Outcome>
  <PhoneNumber>sample string 4</PhoneNumber>
  <Type>sample string 7</Type>
  <ValidatedUtc>2026-10-12T23:25:15.3023067+00:00</ValidatedUtc>
</PhoneNumberLookupResultModel>