Response Examples

    Success Response Attributes

    The following attributes are returned for success response:

    api_idstring

    Uniquely identifies the request.

    phone_numberstring

    This value is the phone number in E.164 format that was looked up in the API request.

    countrydict

    This value has three key-value pairs that provide information regarding the country.

    name(string): The value specifies the name of the country to which this number belongs to,

    code_iso2(string): The value specifies a two-letter country code defined in ISO 3166-1,

    code_iso3(string): The value specifies a three-letter country code defined in ISO 3166-1.

    formatdict

    This value contains four key-value pairs that provide information regarding different number formats.

    e164(string): This gives the number in e164 format. Example : "+1204XXXXXXX",

    national(string): This gives the number in national format. Example : "(204) XXX-XXXX",

    international(string): This gives the number in international format. Example : "+1 204-XXX-XXXX",

    rfc3966(string): This gives the number in rfc3966 format. Example : "tel:+1-204-XXX-XXXX".

    carrierdict

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

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

    mobile_network_code(string): This is a two or three letter string. This specifies the mobile network code(MNC) of the number. For Fixed type phone numbers this is set as null.

    name(string): This specifies the name of the present carrier to which the number belongs.

    type(string): This specifies the type of the phone number. As of now, this field can be set to one of these values: fixed,mobile,voip. If the number belongs to any other type that would be mentioned as null.

    ported(string): If the number is ported, then the value is true. If the number is not ported, then the value is false. This ported information is shown only for the USA and Canada. For the remaining countries this value is set to null.

    resource_uristring

    This contains the URI which can be used to do a lookup on the same phone number again.

    Error Response Attributes

    The following attributes are returned for error response:

    api_idstring

    Uniquely identifies the request.

    error_codeinteger

    Indicates an error and provides the error code.

    messagestring

    Provides error information regarding the request. This is given only when there is an error.

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

    Response

    Success

    {
      "api_id": "<api_id>",
      "phone_number": "+1204XXXXXXX",
      "country": {
        "name": "Canada",
        "code_iso2": "CA",
        "code_iso3": "CAN"
      },
      "format": {
        "e164": "+1204XXXXXXX",
        "national": "(204) XXX-XXXX",
        "international": "+1 204-XXX-XXXX",
        "rfc3966": "tel:+1-204-XXX-XXXX"
      },
      "carrier": {
        "mobile_country_code": XXX,
        "mobile_network_code": XXX,
        "name": "Carrier Name",
        "type": "number_type",
        "ported": true_or_false
      },
      "resource_uri": "/v1/Lookup/Number/+1204XXXXXXX?type=carrier"
    }
    

    Error

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