UK SMS HTTP
Get Subscriber Disconnects
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
Batch identifiers
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.
Disconnect start and end dates
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.
Format of date and time parameters
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)
Limits
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.
Notification date
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.
Periodic polling of the service
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/disconnectsURL 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%2B0000Query 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¬ificationStart=2007-01-01+00%3A00%3A00%2B0000¬ificationEnd=2007-01-05+00%3A00%3A00%2B0000This request returns disconnects that were notified in batch 135 and onwards:
https://portal.openmarket.com/api/disconnects?authUsername=myusername&authPassword=mypassword&batchesFrom=135This 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=VERIZONUSThis 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. |