Mobile Operator Lookup (v3)

Use this operation to lookup the mobile operator for a phone number. The operation will also return:

  • The US state or Canadian Province where the phone number is provisioned
  • The nearest US zip code or Canadian postal code where the phone number is provisioned
  • An estimated latitude/longitude where the phone number is provisioned
  • The maximum text message length you can send to the end user

Note: If you're new to OpenMarket, then integrate with our Global SMS (version 4) operations.
Customers currently integrated using v3 may continue to use it, although we encourage customers to migrate to v4 in order to take advantage of new features.

Quick facts

Method

POST with XML

Returns

XML

Available

US and Canada only

Prerequisites

You must have SMS messaging provisioned with OpenMarket.

More information

See Overview.

Making a Request

Definition

POST smsc.openmarket.com

There are no URL parameters for this endpoint.

This endpoint supports version Transport Layer Security (TLS) 1.2.

Header fields

POST /wmp HTTP/1.1
Host: smsc.openmarket.com:443/wmp
Content-Type: text/xml
Connection:  close

There are no custom header fields required. You must specify a Content-Type of text/xml in your request header.

Request body

The request body contains the mobile number you wish to perform a lookup..

<?xml version="1.0" ?>
<request version="3.0" protocol="wmp" type="preview">
   <user agent="XML/SMS/1.0.0" />
   <account id="123-456-789-0000" password="password" />
   <destination ton="1" address="13135551212" />
</request>

Request element

The request element is the outer element of the XML document.

Attribute

Description

version

Version of the API. Set to 3.0.

Required: yes

Type: string

protocol

The protocol used. Set to wmp.

Required: yes

Type: string

type

The type of request being sent. Set to preview.

Required: yes

Type: string

user element

If you are using a custom user agent, define these properties to use as the user element with the following format:

[DevelopmentEnvironment]/SMS/[Version0.0.0]

Example: 

XML/SMS/1.0.0

Attribute

Description

agent

Identifies the interface used by your platform. The maximum length is 60 characters.

Required: no

Type: string

account element

Specifies your authentication details.

Attribute

Description

id

Your OpenMarket-provided account for using SMS version 3 operations.

Required: yes

Type: string
password

The password for the account.

Required: yes

Type: string

destination element

Attribute

Description

ton

Indicates the destination address type of number, or TON. Either:

  • 1 — international phone number format
  • 0 — unknown. This is acceptable, but not recommended.

Required: yes

Type: integer

address

The mobile number to which for which you want to lookup the mobile operator. Always include the country code prefix (e.g., 1 for North America).

  • If ton is 1, do not include the plus sign (+) at the start of the phone number.
  • If ton is 0, include the plus sign at the start of the phone number.

The maximum length is 20 characters.

Required: yes

Type: string

Response from OpenMarket

Accepted requests

If your request is accepted then OpenMarket sends an HTTP 202 response, similar to the below. Accepted requests include the ticket element. 

<?xml version="1.0" ?>
<response version="3.0" protocol="wmp" type="preview">
   <error code="0" description="No Error" resolution="" />
   <destination country_code="1" national_number="3134447001" area_code="313" area_code_length="3" num_min_length="7" num_max_length="7" na_nxx="444" na_line="7001" intl_notation="+13134447001" local_notation="(313) 444-7001" local_format="(###) ###-####" digits_all="11" digits_local="10" ported="no" ported_from="" />
   <location country="US" country_name="United States" zone="1" zone_name="North America, Caribbean" region="MI" region_name="Michigan" city="Birmingham" postal_code="48077" timezone="-5" estimated_latitude="42.29" estimated_longitude="83.19" />
   <operator id="79" name="T-Mobile" text_length="160" binary_length="140" unicode_length="70" binary="true" unicode="true" smart_messaging="true" wap_push="true" ems="true" />
</response>

The response will include the following data.

response element

Attribute

Description

version

The SMS API version. The value is always 3.0 for this operation.

Returned: always

Type: string

protocol

The protocol. The value is always wmp for this operation.

Returned: always

Type: string

type

Identifies that this is the response to an operator lookup request (a.k.a. "preview" request).

Returned: always

Type: string

destination element

Attribute

Description

country_code

A numeric ID of the country. For example, 44 for the United Kingdom and 52 for Mexico.

Returned: always

Type: string

national_number

The portion of the destination address that follows the country code.

Returned: always

Type: string

area_code

The portion of the destination address that specifies the code of a specific region.

Returned: always

Type: string

area_code_length

The length of the area code in the destination address.

Returned: always

Type: integer

num_min_length

The minimum length of the destination address.

Returned: always

Type: integer

num_max_length

The maximum length of the destination address.

Returned: always

Type: integer

na_npa

The area (exchange) served within an area code in the North American Numbering Plan for Canada, the US and its territories, and the Caribbean. Used for routing to mobile operators.

Returned: always

Type: string

na_nxx

The last four numbers of the NPA mobile number; this number follows the na_npa.

Returned: always

Type: string

intl_notation

The ISO standard for the international format of the destination address.

Returned: always

Type: string

local_notation

The typical mobile number notation for the destination address used within a geographic region.

Returned: always

Type: string

local_format

A formatting expression to help format local numbers inside an application.

Returned: always

Type: string

digits_all

The total number of digits contained in the destination address.

Returned: always

Type: integer

wnp

Whether the mobile phone number has been ported from the original mobile operator to an alternate operator. This value is determined from a dynamic query of the local WNP database within the region. The <operator> element contains the OpenMarket carrier ID for the mobile operator currently assigned to the destination address.

Returned: always

Type: Boolean

ported

Whether the mobile number has been ported from the original mobile operator to an alternate operator. This value is determined from a dynamic query of the local WNP database within the region. The <operator> element contains the carrier ID for the mobile operator currently assigned to the destination address.

Returned: always

Type: Boolean

ported_from

The carrier ID from which the number originates.

Returned: always

Type: integer

na_line

The line number of the destination address.

Returned: always

Type: string

location element

Attribute

Description

zone

The first digit of the destination address. Valid values are specific to the destination address used in the request.

Returned: always

Type: integer

zone_name

A descriptive name of the zone code.

Returned: always

Type: string

country

The two-digit ISO country code for the destination address.

Returned: always

Type: integer

country_name

A descriptive country name for the destination address. Valid values are specific to the destination address used in the request.

Returned: always

Type: string

region

The region or state for the destination address, based on the original registered location for the mobile number.

Returned: always

Type: string

region_name

A descriptive name for the region or state.

Returned: always

Type: string

city

The city associated with the destination address.

Returned: always

Type: string

postal_code

The postal code for the destination address, based on the original registered location for the mobile number.

Returned: always

Type: string

timzone_min

The minimum local reference to the GMT timezone for the specific region.

Returned: always

Type: integer

timzone_max

The maximum local reference to the GMT time zone for the specific region.

Returned: always

Type: integer

estimated_latitude

The latitude of the destination address based on the original registered location for the mobile number. The estimated latitude approximates the location. If a city or region is not known, the latitude maps to a country. You can use this value to plot coordinates in a map for reporting systems. The value is in decimal format, not degrees and radians.

Returned: always

Type: string

estimated_longitude

The longitude of the destination address based on the original registered location for the mobile number. The estimated longitude approximates the location. If a city or region is not known, the longitude maps to a country. You can use this value to plot coordinates in a map for reporting systems. The value is in decimal format, not degrees and radians.

Returned: always

Type: string

operator element

Attribute

Description

id

OpenMarket mobile operator ID associated with the mobile phone number.

For a list of the valid IDs, see Mobile Operator IDs.

Returned: always

Type: integer

name

The name of the mobile operator associated with the ID.

Returned: always

Type: string

text_length

The maximum text message length for the specific mobile operator.

Returned: always

Type: integer

binary_length

The maximum binary message length for the specific mobile operator.

Returned: always

Type: integer

unicode_length

The maximum Unicode message length for the specific mobile operator.

Returned: always

Type: integer

binary

Whether the mobile operator accepts binary messages.

Returned: always

Type: Boolean

unicode

Whether the mobile operator accepts Unicode messages.

Returned: always

Type: Boolean

smart_messaging

Whether the mobile operator accepts smart messaging.

Returned: always

Type: Boolean

wap_push

Whether the mobile operator accepts WAP push messages.

Returned: always

Type: Boolean

ems

Whether the mobile operator accepts enhanced message services (EMS) messages.

Returned: always

Type: Boolean

Rejected requests

If your request is rejected, then OpenMarket sends a HTTP 400-499 response. 

<?xml version="1.0" ?>
   <response version="3.0" protocol="wmp" type="preview">
   <error code="345" description="Unable to determine carrier id from pin or destination address." resolution="" />
</response>

error element

Attribute

Description

code

Number that indicates whether the request was successful or failed.

See Response and Delivery Receipt Codes for SMS Version 3 API.

Returned: always

description

Description for the error code. This provides some information about why the request failed.

Returned: always

resolution

This attribute is deprecated.

Returned: always

Testing your integration

OpenMarket provides an option for testing your integration with the production environment. See Testing Your SMS v3 Integration.

Troubleshooting

Response error codes

For a list of response codes and delivery receipt codes, see Response and Delivery Receipt Codes for SMS Version 3 API.