Latest Legacy

Response Examples

Success Response Attributes

These attributes are returned for success response:

api_idstring

Uniquely identifies the request.

phone_numberstring

The phone number that was looked up in the API request in E.164 format.

countrydict

Three key-value pairs that provide information regarding the country:

name(string): The name of the country to which this number belongs.

iso2(string): The two-letter country code defined in the ISO 3166-1 standard.

iso3(string): The three-letter country code defined in ISO 3166-1.

formatdict

Four key-value pairs that provide information regarding different number formats.

e164(string): Gives the number in E.164 format. Example : "+12045551111"

national(string): Gives the number in national format. Example : "(204) 555-1111"

international(string): Gives the number in international format. Example : "+1 204-555-1111"

rfc3966(string): Gives the number in RFC 3966 format. Example : "tel:+1-204-555-1111"

carrierdict

Contains five key-value pairs that provide information regarding the carrier of the number.

mobile_country_code(string): A three-letter string that specifies the mobile country code (MCC) of the number. For Fixed type phone numbers this is set as empty_string.

mobile_network_code(string): A two- or three-letter string that specifies the mobile network code (MNC) of the number. For Fixed type phone numbers this is set as empty_string.

name(string): The name of the carrier to which the number belongs. If the name of carrier is not found, this is set as empty_string.

type(string): The type of phone number, which may be  fixed, mobile, voip, or toll-free. If the number belongs to any other type, the value will be unknown.

ported(string): If the number is ported, then the value is yes. If the number is not ported, then the value is no. Ported information is shown only for the USA and Canada. For other countries the value is set to unknown.

resource_uristring

The URI that can be used to look up the same phone number again.

Error Response Attributes

These attributes are returned for error responses:

api_idstring

Uniquely identifies the request.

error_codeinteger

Indicates an error and provides the error code.

messagestring

Provides error information regarding the request — given only when there’s an error.

Note: Only possible numbers (for a given region, using length and prefix information) will return formatting results. For further information about error codes in error responses, refer to the Troubleshooting page.

Response

Success

{
    "api_id": "e4a25a0a-a19f-4ff6-b8b5-1841bea253f6",
    "phone_number": "+16172252821",
    "country": {
        "name": "United States",
        "iso2": "US",
        "iso3": "USA"
    },
    "format": {
        "e164": "+16172252821",
        "national": "(617) 225-2821",
        "international": "+1 617-225-2821",
        "rfc3966": "tel:+1-617-225-2821"
    },
    "carrier": {
        "mobile_country_code": "",
        "mobile_network_code": "",
        "name": "Verizon",
        "type": "fixed",
        "ported": "no"
    },
    "resource_uri": "/v1/Number/+16172252821?type=carrier"
}

Error

{
   "api_id": "<api_id>",
   "error_code": 403,
   "message": "Account is forbidden from accessing resource."
}