Delivery Reports API

1. Introduction.............................................................................................................................2

2. API Details................................................................................................................................2

2.1 API URL...................................................................................................................2

2.2. Steps for calling API................................................................................................2

2.3. API Parameters.......................................................................................................3

The API can be invoked to fetch by delivery status. This is useful to check for only failed numbers so that a program at Enterprise end can retry numbers the next day, for instance. Valid Status codes are available in ..........................................................3

2.4. API Output..............................................................................................................5

2.4.1 XLS..............................................................................................................................5

2.4.2. CSV, PIP Output...........................................................................................................5

2.4.3. SMP Output.................................................................................................................5

2.4.4. XML Output.................................................................................................................5

2.5 Error Codes.............................................................................................................6

3. Appendix..................................................................................................................................9

3.1 Circle.......................................................................................................................9

3.2 Operator..................................................................................................................9

3.3 Format...................................................................................................................10

3.4. Valid Status..........................................................................................................10

Netcore Confidential Page 1

11. Introduction

netCORE provides PULL Delivery Report API, with which Enterprises can check the Delivery Reports for the messages published.

The details of the Delivery Report API have been outlined in this document.

1API Details

3.3API URL

The base URL for Delivery Reports will be: http://stats.mytoday.com/dlr_api

1.3Steps for calling APIØYou need to call the API:

http://stats.mytoday.com/dlr_api?feedid=12345&date=2009-12-05

http://stats.mytoday.com/cgi/DLR_API/bin/dlr_api.pl

Feedid is a mandatory parameter for which you must specify a value. Date is one of the optional parameters. If do not specify a date, by default, the delivery report for today’s date will be shown. Refer to API Parameters for API Parameters.

If there is any error while specifying the API parameters, error message will be displayed corresponding to the type of error. Refer to 2.5 Error Codes to view the various error codes/ messages.

This will initiate the request to fetch Delivery Reports, asynchronously.

Ø When you call the API, the Delivery Report Request Transaction ID will be returned. This will need to be used for further requests to fetch the Delivery Report.

<RESULT>DTXNID</RESULT>

DTXNID is the Delivery Report Request Transaction ID. It is alphanumeric.

ØFor consequent requests to fetch the Delivery Report, the API needs to be invoked the DLR Request Transaction ID parameter (dtxnid=<DTXNID>):

Netcore Confidential Page 2

http://stats.mytoday.com/dlr_api?feedid=12345&date=2009-12-05&dtxnid=6xyjiulsd24afsf

You get the status as-

<RESULT>FETCHING<RESULT>

Or

<RESULT>DONE</RESULT>

FETCHING implies that the Delivery Report retrieval is in progress. The API needs to be invoked in a loop till status is returned as DONE.

ØDONE status indicates that the delivery report can be retrieved in the next API call.

Resend the API request, with an additional parameter ack=1:

http://stats.mytoday.com/dlr_api?feedid=12345&date=2009-12-05&dtxnid=6xyjiulsd24afsf&ack=1

The Delivery Report will be available in the required format.

1.3API ParametersNameMandatory?ExampleDescriptionfeedidMandatory12345Specify the Account ID / Feed ID that is provided for the Channel used to send messagesdateOptional2009-09-15Specify the date for which the Delivery Report is required. If not specified, the current date will be taken as date. DLRs can be fetched only for a given date in an API call (not across days).

1.3Specify date in yyyy-mm-dd formatstatusOptionaldeliveredfailedabsentsubsThe API can be invoked to fetch by delivery status. This is useful to check for only failed numbers so that a program at Enterprise end can retry numbers the next day, for instance. Valid Status codes are available in txnidOptional14254352342The Transaction ID of a message returned when a BulkSMS API call is made can be used to fetch Delivery Reports. This is a unique ID (big integer)requestidOptional 2341244The Request ID returned when a BulkSMS API call is made can be used to fetch Delivery Reports. This is a unique ID per SMS API request (big integer)msgtagOptionalMarketUpdates897923Upload1-9AMIn SMS API, Enterprises can set a tag for a message/ SMS API call. Tags could be an alphanumeric name (with space, hyphen, e.t.c.) to identify the SMS API transaction/ internal Transaction ID of the Enterprise.messageidOptional124412When using Publish message to subscribers’ option, the message ID (called itemid) is returned. Use “itemid” to get DLRs for a specific message publish to subscribers.fromhourOptional1209922fromhour and tohour can be used to limit the Delivery Report search to a specific time interval in the day. Specify in 24 hr format.

Example valid values are: 8, 08, 13, 23, e.t.c.tohourOptional1209922Fromhour and tohour can be used to limit the Delivery Report search to a specific time interval in the day. Specify in 24 hr format.

Example valid values are: 8, 08, 13, 23, e.t.c.mobileOptional993423522309934235224919923412345Specify the mobile number for which Delivery Report is required. This can be 10-digit or 11 digit with 0 prefix mobile number or 91-prefixed 12 digit mobile

Netcore Confidential Page 3

numbersenderidOptionalMyTodayThis is useful, specifically when multiple Sender IDs are used to send messages on the same channel. With this feature, Delivery Reports can be segregated by Sender IDcircleOptionalAS

GJ

Specify the Circle Identifier to get the Delivery reports of only the users belonging to the specified “circle”. The different permissible values are elaborated in 3.1 CircleoperatorOptionalA-Airtel users

V-Vodafone

Specify the Operator Identifier to get the Delivery reports of only the users belonging to the specified “operator”. For further information, refer to 3.2 OperatorformatOptionalxls-Delivery report will be downloaded as excel file

csv-Delivery report downloaded will be a csv fileThis specifies the format in which the Delivery report needs to be returned to the user. To view the valid formats, click:

xls is the default format.showexecOptional 1

0

If this is specified, an executive summary of the delivery report based on search criterion will be available in the first section of the Delivery report: this is available for xls, zip-xls formats only. The value, if specified is 1. If 0, executive summary will not be provided

This will show the total number of messages sent with a split up by delivery status.dtxnidMandatory once received<RESULT>XX1234XX</RESULT>When a DLR API call is initiated, the API will return a DLR API Request ID within XML.

This ID needs to be used in future requests to fetch the Delivery ReportackMandatory for final API callack=1Once the API returns <RESULT>DONE</RESULT> in return to the API call with DLR Request ID and other parameters, the next call to the API would return the delivery report file. The file would be returned in the output format requested. Default format is xls.

This API call returns with an XML file containing the status of the API call. The following table describes the different result status returned by the API (within the <RESULT> </RESULT> tag) and the appropriate action to be taken for each of these.

Result StringDescriptionAction to be taken<RESULT>DTXNID</RESULT> DTXNID is an alphanumeric request Id that needs to be used in future requests to fetch the Delivery ReportThe API needs to be called with DTXNID <RESULT>FETCHING</RESULT>This indicates that the Delivery Report request has been made to the system and the details are being fetched to be returnedContinue calling the API with the specified parameters.<RESULT>DONE</RESULT>This indicates that the

Delivery Report as requested is available for download.

The next call will return the DLR in the desired output formatThe next call to the API will

return the detailed DLR.<RESULT>

<ERROR>

<CODE>nnn</CODE>

Netcore Confidential Page 4

<DESCRIPTION>Error Description </DESCRIPTION>

</ERROR>

</RESULT>In case there’s an error in the API call – invalid parameters, unavailability of mandatory parameters, authentication issue, invalid combination of parameters, or if no data is available for the search: this result string will be thrown with the appropriate error pointerPlease check the parameters/ authentication settings with your Account Manager

1.3API Output

1.3.12.4.1 XLS

The XLS output sample is given below

Notes

1The mobile numbers in the Delivery Report will be prefixed with country code

1.3.1CSV, PIP Output

The column order will be:

Publish Date, Mobile, Delivery Status, Delivery Time, Sender ID, No. of SMS Parts, Request ID, Transaction ID, Item ID, MessageTag, Message, Operator, Circle

1.3.1SMP OutputThe output for SMP format will be:

submit date:100315000018 done date:100315081546 stat:DELIVRD err:Etext:This is to acknowled

submit date:100315010043 done date:100315010053 stat:DELIVRD err:Etext:This is to acknowled

1.3.1XML Output

Outlining the XSD for the XML DLR<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"><xsd:element name="REQ" minOccurs="1" maxOccurs="1"><xsd:complexType><xsd:sequence><xsd:element name="MODE" type="xsd:int"/><xsd:element name="VER" type=xsd:float><xsd:element name="ACCOUNT"><xsd:complexType><xsd:sequence><xsd:element name="ID" type="xsd:int"/></xsd:sequence></xsd:complexType></xsd:element>

Netcore Confidential Page 5

<xsd:element name="MESSAGE" minOccurs="0” maxOccurs="unbounded"><xsd:complexType><xsd:sequence><xsd:attribute name="TEXT" type="xsd:string"/><xsd:attribute name="REQUESTID" type="xsd:long"/><xsd:attribute name="TRANSACTIONID" type="xsd:long"/><xsd:attribute name="SENDERID" type="xsd:string"/><xsd:attribute name="TAG" type="xsd:string"/><xsd:attribute name="MESSAGEID" type="xsd:long"/><xsd:attribute name="NOOFSMS" type="xsd:int"/><xsd:element name="MOBILE" minOccurs="0" maxOccurs="unbounded" type="xsd:string"><xsd:complexType><xsd:sequence><xsd:attribute name="ID" type="xsd:int"/><xsd:attribute name="SENTTIME" type="xsd:date"/><xsd:attribute name="DELIVEREDTIME" type="xsd:date"/><xsd:attribute name="STATUS" type="xsd:string"/><xsd:attribute name="INDEXID" type="xsd:int"/></xsd:sequence></xsd:complexType></xsd:element></xsd:sequence></xsd:complexType></xsd:element></xsd:sequence></xsd:complexType></xsd:element></xsd:schema>

1.32.5 Error CodesNo.CodeDescriptionReason1101Please specify your Account IDMandatory parameter of FeedId/ Account Id has not been supplied.2102Invalid Account IDThe Account ID specified is invalid (Account IDs are numeric and positive)3103Unauthenticated Access to view Delivery ReportsIf the API call comes in from an IP Address that has been white-listed for the account, this error will be thrown. Please contact your Account Manager for assistance.4104Please specify date in a valid format (yyyy-mm-dd)Date should be specified in yyyy-mm-dd format. Please check before resubmitting the request5105Please specify a valid dateEnsure that the date submitted is valid ex. 2009-13-11 is an invalid date6106Please specify a valid MessageIDMessage ID should be a valid numeric value7107MessageID cannot be specified

with Request ID and Transaction IDMessage ID is a parameter used for Publish to Subscriber API : this cannot be combined with Request ID-Transaction ID parameters used for Bulk SMS API8108Please specify a valid Transaction IDTransaction ID should be numeric, positive9109Please specify a valid Request IDRequest ID should be numeric, positive10110Please specify a valid Sender IDSender ID should be alphanumeric within 11 characters or numeric within 12 characters11111Unauthenticated Sender IDIf the Sender ID has not been authenticated for the given account, this error will be thrown12112Please specify a valid mobile numberThe mobile number should be positive, numeric.

10 digit Indian mobile number, 91-prefixed number followed by 10 digits: Indian mobile number with country code; International number13113Please specify a valid, positive hourIf to hour or from hour is non-numeric or a negative number or not within 0-23, this error will be thrown14114From Hour cannot be greater than To HourIf from hour is ahead of to hour, this error will be thrown (Delivery Reports are for only one day)15115Please specify a valid output formatValid output formats are:

xls, csv, zip-xls, zip-csv, xml, zip-xml

Netcore Confidential Page 6

xls is the default format16116Please specify a valid showexec valueShowexec can be 0 or 1 only.

If 0 or not specified, the showexec will not be displayed. If 1, executive summary will be displayed in the xls output17117Showexec feature is available only in Xls outputIf a non-xls output format is specified and showexec is specified as 1, this error will be thrown18118Invalid Operator code specifiedPlease specify a valid operator code19119Invalid Circle code specifiedPlease specify a valid circle code20120

Please specify a valid status

If the status is not one of these-

delivered

failed

absentsubs

invalidsubs

subtonetwork

introaming

In such a case this error message will be thrown.21122Please confirm your Acknowledgement with valid DLR API Request ID

This error message is thrown if, while calling the API, ack=1 is given but the transaction id is not mentioned.22123Please specify a valid Acknowledgement ID

In case the acknowledgement Id is not 1, this message will be displayed23124

Invalid Request

This error message can be thrown in these cases:

1If using DLR API transaction request Id, the API call has been made and delivery report has been requested for. If API call is made again with the same transaction id, Invalid Request error message will be thrown.

2If a second API call request is made using an expired transaction Id along with ack=1, an Invalid Request error message will be thrown.24125

is not a valid parameter

If the parameters specified in the API call request are not in list as shown in section 2.2, this error message will be thrown.25126is a duplicate parameter

If a parameter is mentioned more than once in the API call request, this error message is displayed. 26127The DLR file size exceeds 50 MB. File will be available in your FTP

Netcore Confidential Page 7

Account. Please contact your Account Manager for details

If the DLR file is more than 50 MB, this error message will be thrown.27

128

Spammed RequestThere is a limit on the number of tries that a user can make to call API. If a user tries to make an API call after the limit, this error message is displayed.28130

No record found

Please recheck the parameters or retry after sometime

1Appendix

1.33.1 Circle1.3AbbrName     APAndhra PradeshASAssamBJBihar- JharkhandCHChennaiDLDelhiGJGujaratHPHimachal PradeshHRHaryanaJKJammu-KashmirKLKeralaKNKarnatakaKOKolkataMHMaharashtra- GoaMPMadhya PradeshMUMumbaiNENorth EastOROrissaPBPunjabRJRajasthanTNTamil NaduUEUttar Pradesh(East)UWUttar Pradesh(West)-UttarakhandWBWest Bengal-Andaman

NicobarTCTamil Nadu-Chennai 3.2 Operator

1.3AbbrName  AAirtelCAircelDDatacom SolutionsSTS TelIIdeaLBPL Mobile, Loop TelecomMMTNL, DolphinRGReliance GSMSPSpiceUUnitech InfrastructuresVVodafoneSWSwan TelecomZAllianz InfratechBGBSNL GSMBCBSNL CDMAHCHFCL Connect CDMARCReliance CDMASYShyam Telelink, Rainbow CDMATCTata

CDMATGTata GSM3.3 Format1.3File FormatDescription  xls The delivery report will get downloaded as an Excel sheetcsv The delivery report can be downloaded as a csv filezip-xls The delivery report can be downloaded as a zipped xlszip-csvThe delivery report can be downloaded as a zipped csvxml The Delivery report will be available as an xmlzip-xml The Delivery report will be

available as an xml file in zipped formatsmpThe delivery report will be available in smpp formatpipThe delivery report will get downloaded with pipe delimited formatzip-smpThe delivery report will be available in zipped smpp formatzip-pipThe delivery report will be available in zipped pipe delimited format

1.4

Netcore Confidential Page 8

1.3

1.43.4. Valid StatusStatusDescription  deliveredMessage successfully delivered on handsetfailedMessage not delivered to handsetabsentsubs Message could not be delivered since the user is out of network/ mobile phone is switched offinvalidsubs Mobile number is invalid/inactiveintroamingMessage could not be delivered because the user is roaming internationallyRerouting of messages can be done based on the client’s request(Please contact the client servicing manager for the same.)subtonetwork Submitted to the operator, but awaiting Delivery report/ not received DLR

Netcore Confidential Page 9