Get Subscriber Disconnects

This request retrieves details of mobile numbers that US mobile operators have indicated as having been disconnected.

Important: The information and contents displayed in these pages is for the OpenMarket's legacy UK SMS APIs. This information is relevant if only you're still using these APIs. For information on migrating from these APIs, see the API Release Notes. Please note, however, that Reporting is still done through Partner Centre, located here: https://partner.mxtelecom.com/home.

Quick facts

Method

GET

Returns

CSV

Prerequisites

Available for existing customers only. You must have a Subscriber Disconnect Partner Centre account.

Only available for US mobile phone numbers.

More information

All information for this request is on this page.

Help topics

Disconnects are processed in batches. Each batch has a unique batch ID. This is a 64-bit positive number that incrementally increases for each new ID. The latest processed notification will have the highest batch ID number.

OpenMarket provides for each disconnect a date range over which the disconnect will have occurred along with the date at which the information was made available to us. This date range is typically a day, week or month.

Mobile operators notify OpenMarket of disconnects in batches, typically daily although sometimes monthly. As we cannot be sure at what time each subscriber was disconnected during that period (the day or the month), we store the extreme range on either side.

For example, if a mobile operator sends us disconnects daily, then we store the disconnect date and time range for each number as 00:00:00 to 23:59:59 on the same day. The range you provide in the parameters will limit your search to include only those subscribers who had disconnected during this period.

A subscriber can be returned twice or more times in the results if they disconnected twice or more times during the given range — for example, if the requested range is from 2007-01-01 00:00:00+0000 - 2007-01-20 23:59:59+0000 and a particular subscriber was disconnected on the 2nd and the 20th again, they will be returned twice with their respective dates.

Although we regard subscribers as disconnecting from 00:00:00 to 23:59:59. For ease of usage of the service we treat the disconnectStart parameter as a greater than or equal to condition, and the disconnectEnd parameter as a strictly less than condition. This means that entering a disconnectEnd date of 2007-02-04 00:00:00+0000 will include subscribers who had disconnected on the 3rd of Jan or before and not those who have just started to disconnect on the 4th of Jan. You can effectively think of the the date 2007-01-04 00:00:00 being converted into 2007-01-03 23:59:59+0000.

The format of dates used in the Subscriber Disconnect service is:

YYYY-MM-DD hh:mm:ssZZZZZ

Each part is as follows:

Part

Description

YYYY:MM:DD

The date in the format of year (YYYY) as full four digits, then the month (MM) and day (DD).
hh:mm:ss

The time of day. The hours are in 24 hour format.
ZZZZZ

Timezone specified as an offset from GMT. The format is a + or - symbol followed by the hour and minute offset (-hhmm or +hhmm).

Examples

  • 2007-02-20 13:00:00+0000 — 1pm on the 20th February 2007 in GMT
  • 2007-10-15 09:30:00-0800 — 9:30am on the 15th October 2007 in Pacific Standard Time (PST)
  • 2008-05-09 22:20:21+0930 — 10:20pm and 21 seconds on the 9th May 2008 in Australia Central Standard (ACST)

Please note that details of disconnects are only accessible for the last 12 months. Any requests with date ranges preceding this time will cause an error to be raised and no data will be returned whether there are disconnects within this range or not. This behavior is present such that no disconnects are returned for the specified range rather than potentially falsely saying that there were no disconnects.

Mobile operators will inform us of subscriber disconnects after the disconnect has completed. Disconnects from various subscribers are processed in a batch and as so there are no guarantees as to how quickly after a disconnect we will be notified. We store the time and date that we were notified of the disconnect and give you the option to query based upon this date.

You can use the notificationStart and notificationEnd parameters to make periodic polls of the API in order to see newly notified disconnects. However, polling from an arbitrary time up until the current time is dangerous as there could be outstanding disconnects that we may have been notified about but not yet recorded. It is better to use the Batch ID for operations of this type.

The recommended method of undertaking period polling is to request data only for batches that you have not yet received. You can use the batch ID to easily and regularly poll for subscriber disconnects using the batchesFrom parameter. Specify the next number greater than the last batch ID you received in a previous request. (Note that the previous request should also be a request based on batch number, not on a date range.)

Making a Request

Definition

GET https://portal.openmarket.com/api/disconnects

URL example

https://portal.openmarket.com/api/disconnects?authUsername=myusername&authPassword=mypassword&disconnectStart=2007-01-01+00%3A00%3A00%2B0000&disconnectEnd=2007-01-05+00%3A00%3A00%2B0000

Query parameters

Note that you need to specify at least one of the following sets of optional parameters:

  • disconnectStart and disconnectEnd
  • notificationStart and notificationEnd
  • batchesFrom

Parameters must be URL-encoded.

Parameter

Description

authUsername

User name of a valid Partner Centre account.

Required: Yes
authPassword

Password for the account.

Required: Yes
disconnectStart

If present, only return disconnects that occurred since this date. The format is:

YYYY-MM-DD hh:mm:ssZZZZZ

Required: Required when disconnectEnd also specified
disconnectEnd

If present, only return disconnects that occurred before this date. The format is:

YYYY-MM-DD hh:mm:ssZZZZZ

Required: Required when disconnectStart also specified
notificationStart

If present, only return disconnects that were notified since this date. The format is:

YYYY-MM-DD hh:mm:ssZZZZZ

Required: Required when notificationEnd also specified
notificationEnd

If present, only return disconnects that were notified before this date. The format is:

YYYY-MM-DD hh:mm:ssZZZZZ

Required: Required when notificationStart also specified
batchesFrom

A batch ID. If present, only return disconnects that appeared in a batch with ID greater than or equal to this ID.

Required: No
msisdn

If present, only return disconnects for the specified mobile number (MSISDN format with no leading + symbol).

Required: No
network

If present, only return disconnects for the specified mobile operator. You can repeat this parameter in the same request in order to include multiple operators.

For operator codes, see Network Codes (UK SMS).

Required: No
displayTimezone

If present, returns the results in the given timezone. Default is Europe/London. See the section below for more information.

Required: No

Format of displayTimezone parameter

By default all dates and times are displayed in the the Europe/London timezone. If you want the results returned in the CSV file to be in a different timezone to that of Europe/London, you should use the displayTimezone parameter. You can specify a display timezone in 3 ways:

  • With a locale — for example, America/New_York. This is case sensitive but stable and copes with daylights savings
  • With a 3 letter mnemonic — for example, EST. This is not fully supported (as some mnemonics clash) and should be used sparingly
  • With a GMT offset — for example, GMT-0800. This is the specific but you need to be aware of your timezones offset from GMT and need to use the syntax GMT+/-HHMM

Commonly used values

Value

Description

US/Central

US Central Standard Time

US/Eastern

US Eastern Standard Time

US/Mountain

US Mountain Standard Time

US/Pacific

US Pacific Standard Time

America/New_York

New York, US

Europe/London

London, Great Britain

Header fields

There is no data required in the header.

Example requests

This request returns disconnects that occurred between 1st January 2007 and 5th January 2007 GMT:

https://portal.openmarket.com/api/disconnects?authUsername=myusername&authPassword=mypassword&disconnectStart=2007-01-01+00%3A00%3A00%2B0000&disconnectEnd=2007-01-05+00%3A00%3A00%2B0000

This request returns disconnects that OpenMarket were notified about between the period of 1st January 2007 to 5th January 2007 GMT:

https://portal.openmarket.com/api/disconnects?authUsername=myusername&authPassword=mypassword&notificationStart=2007-01-01+00%3A00%3A00%2B0000&notificationEnd=2007-01-05+00%3A00%3A00%2B0000

This request returns disconnects that were notified in batch 135 and onwards:

https://portal.openmarket.com/api/disconnects?authUsername=myusername&authPassword=mypassword&batchesFrom=135

This request returns disconnects that occurred between 1st January 2007 and 5th January 2007 GMT on Sprint and Verizon:

https://portal.openmarket.com/api/disconnects?authUsername=myusername&authPassword=mypassword&disconnectStart=2007-01-01+00%3A00%3A00%2B0000&disconnectEnd=2007-01-05+00%3A00%3A00%2B0000&network=SPRINTUS&network=VERIZONUS

This request returns disconnects that occurred between 1st January 2007 and 5th January 2007 GMT for mobile number 12188380921:

https://portal.openmarket.com/api/disconnects?authUsername=myusername&authPassword=mypassword&disconnectStart=2007-01-01+00%3A00%3A00%2B0000&disconnectEnd=2007-01-05+00%3A00%3A00%2B0000&msisdn=12188380921

Response from OpenMarket

Accepted requests

OpenMarket will respond to a successful request with an HTTP status code of 200.

Response body

The response body contains the disconnect data as Comma Separated Value (CSV) data in the HTTP body.

Example response body

MSISDN,Carrier/Network,Disconnect Start Date,Disconnect End Date,Notification Date,Batch ID
12182523194,DOBSONUS,2007-07-08 17:00:00 PDT,2007-07-09 16:59:59 PDT,2010-07-10 02:00:25 PDT,2540
12182561528,DOBSONUS,2007-07-08 17:00:00 PDT,2007-07-09 16:59:59 PDT,2010-07-10 02:00:25 PDT,2540
12182593288,DOBSONUS,2007-07-08 17:00:00 PDT,2007-07-09 16:59:59 PDT,2010-07-10 02:00:25 PDT,2540
12043250310,VERIZONUS,2007-07-08 16:00:00 PDT,2007-07-09 15:59:59 PDT,2010-11-30 06:55:20 PST,2541
12047201536,VERIZONUS,2007-07-08 16:00:00 PDT,2007-07-09 15:59:59 PDT,2010-11-30 06:55:20 PST,2541
12047201538,VERIZONUS,2007-07-08 16:00:00 PDT,2007-07-09 15:59:59 PDT,2010-11-30 06:55:20 PST,2541

Field

Description

MSISDN

The mobile number that has been disconnected. This is in international format with no leading + symbol.

Carrier/Network

The OpenMarket operator code of the mobile operator that the subscriber was disconnected from.

For operator codes, see Network Codes (UK SMS).

Disconnect Start Date

The start date of the date range during which the disconnect occurred. The format is YYYY-MM-DD hh:mm:ss zzz, where zzz is a 3 character timezone mnemonic.

Disconnect End Date

The end date of the date range during which the disconnect occurred. The format is YYYY-MM-DD hh:mm:ss zzz, where zzz is a 3 character timezone mnemonic.

Notification Date

The date at which OpenMarket was notified of the disconnect. The format is YYYY-MM-DD hh:mm:ss zzz, where zzz is a 3 character timezone mnemonic.

Batch ID

The batch to which this disconnect belonged. This is an increasing positive 64-bit integer.

Rejected requests

If your request is rejected then you'll receive a HTTP status code of 400, 403, or 501. The body of the response will contain a plain text description of the error.

Response error messages

These error messages are returned in the response body when there was a problem with receiving the request.

Message

Description
Data is only available for 12 months Your request is for a date range that is more than 12 months of the current date. The service only stores data for the last 12 months from the current date. You must provide date ranges within this time period.
You must provide parameter: The request appears to be missing a necessary parameter. Check the parameters in your request are spelled correctly (note that they are case sensitive) and that you have included all the required parameters for your request.
Bad date One of the dates in your request is in the wrong format. Check against the required formats.
Invalid Username/Password There was a problem with one of the authentication values. Check the values of authUsername and authPassword.
authUsername AND authPassword ARE BOTH REQUIRED There was a problem with one of the authentication parameters — either you have omitted or misspelt authUsername or authPassword in the request.
Internal database issue Internal issue. Please retry the request in a few minutes. Contact support if this is an ongoing problem.
Internal server error producing report Internal issue. Please retry the request in a few minutes. Contact support if this is an ongoing problem.

10001-10706 status codes

Submit status

Detail

Description
10001 - 10025 Required parameter <name> missing The request has an invalid or missing parameter (<name>). Either the parameter is missing from the request or it is misspelled in the request.
10100 - 10116 Bad <name> parameter The value for a required parameter <name> is invalid. For example, you would get this response if you specified a letter rather than a number for the report parameter. Check that the value uses the correct format before resubmitting the request. These errors are returned for required parameters but not optional parameters.

10200

This account cannot send to this country

Your account cannot send a message to the number as it is registered in a country you cannot send messages to. Talk to your OpenMarket account manager about sending messages to this region.

Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response.

10201

Invalid msisdn

The mobile number appears to be an incorrect length or includes non-numerical characters.

Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response.

10203 Message too long The message is too large to send in its current format. This will be either because it exceeds the number of parts the message type can have (between 2 and 5 parts), or you have not requested it to be sent as a multipart message. Either resubmit a shorter message or send the message as a multipart message.
10204 Failed to decode message OpenMarket could not decode the message content as it was not correctly hex-encoded. The message type you are sending requires the message contents to be hex-encoded.
10207 Request type unknown The format of the request did not include all the parameters you require to send any message type. For example, you would receive this error message if your request contained only the user, pass and smsto parameters.

10209

WAP pushes are not supported on this network

The end user is with a mobile operator that does not support WAP Pushes. You will need to send the URL to the end user as a plain-text SMS with the URL included.

Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response.

10210 Submitid too long The value of the submitid parameter exceeds the maximum allowed length (30 characters).
10500 Bad image data The image sent in the request was not correctly hex-encoded.
10501 Could not decode image data The image was correctly hex-encoded, but is not in an image format supported by this API. This API supports BMP, GIF, JPEG and PNG.
10551 Invalid URL Your request included a parameter that requires a URL. The value of this parameter must begin with either either http:// or https://. OpenMarket will also check that URLs with a 'www' subdomain include 3 'w' characters. Format the URL correctly before resending the request.
10552 Invalid expiration date

The value of the push_siexpires parameter must be a date in the format yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss, where 'T' is literally the character T. For example: 

push_siexpires=2011-02-27T14:00:00
10553 Action requires si-id You have specified push_action=4 in a WAP Push message request. This action deletes a WAP Push on an end user's cell phone. You must also specify the push_siid parameter to identify the WAP Push you wish to delete.
10554 Invalid push type For WAP Push message requests only. The value you specified for the pushtype parameter is incorrect. For WAP Push Service Indication requests, you must specify 0 for this parameter.
10560 Only http method POST is accepted

This status occurs only for broadcast requests.

Requests to the broadcast endpoints must be sent via HTTP POST.
10561 Too many concurrent requests

This status occurs only for broadcast request.

This endpoint cannot accept the broadcast request, as it is currently processing the maximum number of broadcast SMS requests it will accept at the same time. Wait one minute then resubmit the rejected request.
10562 Request still processing

This status occurs only for broadcast requests.

The request has the same submitid of a request you have very recently sent (within the last minute). After OpenMarket has finished processing the original request, we will return an HTTP 200 response. If you are attempting to send a different request, then change the value of the submitid parameter before resubmitting the request.
10700 Bad username/password Either the value of the user or pass parameter is not correct.

10701

Destination is blacklisted

The mobile number is currently in the number blacklist. Contact your OpenMarket account manager for more information.

Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response.

10702 Destination is blocked

The mobile number cannot receive the type of SMS message you are sending, or the number is outside the range of mobile operators that we can send that type of message to.

Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response.

10703 Credit limit exceeded

The request was rejected as sending the SMS messages would exceed your monthly per-account credit limit.

Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response.

10704 You are not authorized to send messages from that IP address The request did not come from one of the IP addresses in the whitelist you provided to OpenMarket. You can only submit requests from the IP addresses in your whitelist. Contact OpenMarket Support if you need to change the addresses in this whitelist.
10705 Maximum messages to this MSISDN exceeded

You have reached the maximum number of messages you can send to this mobile number in a day.

Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response.

10706 Reverse billing forbidden

The end user has not opted in to your premium rate service on this short code.

Broadcast requests: this code is returned for individual mobile numbers in your 200 response, rather than in a 400-499 response.

10900-10902 status codes

Submit status

Detail

Description
10900 - 10902

Internal error

Provisioning error

 There was a problem that stopped OpenMarket from receiving your request. Retry the request after a minute.