Downloading Subscriber Disconnect lists using HTTP
Overview
The MX Telecom Subscriber Disconnect API provides details of mobile numbers that the carriers have indicated as having been disconnected.
Contents
- Downloading Subscriber Disconnect lists using HTTP
- Parameters for requests
- Response from the server
- Interpreting disconnects
- Periodic polling of the API
Downloading Subscriber Disconnect lists using HTTP
The MX Telecom Subscriber Disconnect API allows authorized applications with internet connectivity to query details of mobile numbers that have been disconnected.
Depending on the source of the data and the exact nature of the disconnect, we cannot be absolutely certain at which exact point in time a disconnect occurred. To cater for this we provide 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.
The following details are returned about each disconnect:
| Parameter(s) | Description |
| MSISDN | The MSISDN of the subscriber that has been disconnected |
| Carrier/Network | The carrier that the subscriber was disconnected from |
| Disconnect Start Date and Disconnect End Date | The date range during which the disconnect occurred |
| Notification Date | The date at which MX Telecom were notified of the disconnect |
| Batch ID | The batch to which this disconnect belonged |
A request for a page using the structure shown below is all that is needed for you to download details of the disconnects using the MX Telecom Subscriber Disconnect API. The endpoint for these HTTP requests is: https://partner.mxtelecom.com/api/disconnects
Requests should be sent as a HTTP GET using the relevant parameters detailed below.
Parameters for requests
| Parameter | Description | Example |
| authUsername | User name of the Partner Centre account to authenticate as | authUsername=myusername |
| authPassword | Password of the Partner Centre account to authenticate as | authPassword=mypassword |
| *disconnectStart | If present, only return disconnects that occurred since this date. Format is YYYY-MM-DD hh:mm:ssZZZZZ | disconnectStart=2007-01-01 00:00:00+0500 |
| *disconnectEnd | If present, only return disconnects that occurred before this date. Format is YYYY-MM-DD hh:mm:ssZZZZZ | disconnectEnd=2007-01-05 00:00:00+0500 |
| *notificationStart | If present, only return disconnects that were notified since this date. Format is YYYY-MM-DD hh:mm:ssZZZZZ | notificationStart=2007-01-03 12:30:00-0800 |
| *notificationEnd | If present, only return disconnects that were notified before this date. Format is YYYY-MM-DD hh:mm:ssZZZZZ | notificationEnd=2007-01-06 13:10:00-0800 |
| *batchesFrom | If present, only return disconnects that appeared in a batch with ID greater than or equal to this ID. See Batch IDs for more details | batchesFrom=39 |
| *msisdn | If present, only return disconnects for the specified mobile number (MSISDN format with no leading "+" req) | msisdn=12067148543 |
| *network | If present, only return disconnects for the specified carrier(s). This parameter can be repeated in order to include multiple carriers. See Carrier Codes for possible values | network=VERIZONUS&network=SPRINTUS |
| *displayTimezone | If present, return the results in the given timezone. Default is Europe/London. See here for more details | displayTimezone=US/Central |
Where * denotes an optional parameter
You need to specify at least one of the following sets of optional parameters:
- disconnectStart and disconnectEnd
- notificationStart and notificationEnd
- batchesFrom
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 behaviour is present such that no disconnects are returned for the specified range rather than potentially falsely saying that there were no disconnects.
Example requests
Return disconnects that occured between 1st January 2007 and 5th January 2007 GMT:
https://partner.mxtelecom.com/api/disconnects?authUsername=myusername&authPassword=mypassword&disconnectStart=2007-01-01+00%3A00%3A00%2B0000&disconnectEnd=2007-01-05+00%3A00%3A00%2B0000Return disconnects that were notified between 1st January 2007 and 5th January 2007 GMT:
https://partner.mxtelecom.com/api/disconnects?authUsername=myusername&authPassword=mypassword¬ificationStart=2007-01-01+00%3A00%3A00%2B0000¬ificationEnd=2007-01-05+00%3A00%3A00%2B0000Return disconnects that occured between 1st January 2007 and 5th January 2007 GMT on networks Sprint and Verizon:
https://partner.mxtelecom.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=VERIZONUSReturn disconnects that occured between 1st January 2007 and 5th January 2007 GMT for mobile number 12188380921:
https://partner.mxtelecom.com/api/disconnects?authUsername=myusername&authPassword=mypassword&disconnectStart=2007-01-01+00%3A00%3A00%2B0000&disconnectEnd=2007-01-05+00%3A00%3A00%2B0000&msisdn=12188380921Return disconnects that were notified in batch 135 and onwards:
https://partner.mxtelecom.com/api/disconnects?authUsername=myusername&authPassword=mypassword&batchesFrom=135Batch identifiers
Disconnects are processed in batches. Each batch has a unique batch ID which provides to give an in order representation of when we processed each disconnect. It is better to use this ID for polling to as the latest processed notification will have the highest Batch ID.
Format of date parameters
Dates are required in the form YYYY-MM-DD hh:mm:ssZZZZZ as specified by:
| Component | Description |
| YYYY | Year (full four digits) |
| MM | Month of year (January is 01) |
| DD | Day of the month (start at 01) |
| hh | Hour of day (24 hour format) |
| mm | Minutes |
| ss | Seconds |
| ZZZZZ | Timezone specified as an offset from GMT with the syntax +/-HHMM. Either +/- followed by a 2 digit hour and 2 digit minute offset from GMT. |
Example dates/times could be:
- 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 PST
- 2008-05-09 22:20:21+0930 - 10:20pm and 21 seconds on the 9th May 2008 in Australia Central Standard
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 e.g. America/New_York. This is case sensitive but stable and copes with daylights savings
- With a 3 letter mnemonic e.g. EST. This is not fully supported (as some mnemonics clash) and should be used sparingly
- With a GMT offset e.g. 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 parameters include:
| Timezone | 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, Europe |
Response from the server
When a request is successfully received by the MX Telecom Subscriber Disconnect API an HTTP 200 success code will be returned with the disconnect data return as Comma Separated Value data in the HTTP body.
Please see here for the meaning of non-200 error codes when they are returned.
The format of the data returned is:
| Column | Format | Description |
| MSISDN | MSISDN with no leading + | The MSISDN of the subscriber that has been disconnected |
| Carrier/Network | String carrier code as per Carrier Codes | The carrier that the subscriber was disconnected from |
| Disconnect Start Date | YYYY-MM-DD hh:mm:ss zzz where zzz is a 3 character timezone mnemonic | The start of the date range during which the disconnect occurred |
| Disconnect End Date | YYYY-MM-DD hh:mm:ss zzz where zzz is a 3 character timezone mnemonic | The end of the date range during which the disconnect occurred |
| Notification Date | YYYY-MM-DD hh:mm:ss zzz where zzz is a 3 character timezone mnemonic | The date at which MX Telecom were notified of the disconnect |
| Batch ID | An increasing positive 64-bit integer | The unique identified of the batch to which this disconnect belongs |
An example of the CSV data returned is:
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,2007-07-10 02:00:25 PDT,1 12182561528,DOBSONUS,2007-07-08 17:00:00 PDT,2007-07-09 16:59:59 PDT,2007-07-10 02:00:25 PDT,1 12182593288,DOBSONUS,2007-07-08 17:00:00 PDT,2007-07-09 16:59:59 PDT,2007-07-10 02:00:25 PDT,1 12043250310,VERIZONUS,2007-07-08 16:00:00 PDT,2007-07-09 15:59:59 PDT,2007-11-30 06:55:20 PST,2 12047201536,VERIZONUS,2007-07-08 16:00:00 PDT,2007-07-09 15:59:59 PDT,2007-11-30 06:55:20 PST,2 12047201538,VERIZONUS,2007-07-08 16:00:00 PDT,2007-07-09 15:59:59 PDT,2007-11-30 06:55:20 PST,2Error responses
A standard successful response will return a 200 HTTP response code along with the CSV file contained in the body of the response. All other HTTP codes are considered as errors and you should consult the error message provided along with this reference table to help you resolve common issues.
| Error code | Message | Fix |
| 400 | Data is only available for 12 months | Provide date ranges within 12 months of the current date |
| 400 | You must provide parameter: ? | Check the parameters you provided, you might have misspelt (it is case sensitive) or omitted a required parameter |
| 400 | Bad date | One of your dates is in the wrong format, check against the required formats |
| 403 | Invalid Username/Password | You have probably misspelt either your username or password |
| 403 | authUsername AND authPassword ARE BOTH REQUIRED | You have omitted or misspelt the one of the authentication parameters |
| 501 | Internal database issue | Internal issue, retry in a few minutes, if it keeps appearing contact support |
| 501 | Internal server error producing report | Internal issue, retry in a few minutes, if it keeps appearing contact support |
Interpreting disconnects
Disconnect Start Date and Disconnect End Date
Subscribers will be disconnected at an arbitrary time during the day. However we are only notified 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. In a day scenario the lower limit will be the day they disconnected on at 00:00:00, and the upper limit on the same day at 23:59:59. 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, e.g. 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 an end 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 for use in the API.
Notification Date
Network operators will inform us of subscriber disconnects after the disconnect has completed. Disconnects from various subscribers are processed in a batch (see Batch ID) and as so there 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.
Periodic polling of the API
The recommended method of undertaking period polling is to request data only for batches that you have not yet received. You do this using the batchesFrom parameter.
