CLX MSISDN Lookup Interface Description

Transcription

1 CLX MSISDN Lookup Interface Description VERSION CONTENT IS SUBJECT TO CHANGE TEL.: SUPPORT-DE@CLXCOMMUNICATIONS.COM All rights reserved. This product and related documentation are protected by copyright and under licenses restricting its use, copying, distribution and compilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorisation of CLX Communications GmbH. Wilhelm-Wagenfeld-Str München Deutschland

2 Table of Contents Version - History...Error! Bookmark not defined. 2.0 Introduction Setup and Connection Data Resource Management Timeouts HTTP Interface Description Interface Base URL Interface Parameter HTTP Return Values Configuration URLs and Downloads Error Codes CLX MSISDN LOOKUP INTERFACE DESCRIPTION TABLE OF CONTENTS

3 Revision History 1.0 Date Author Version Comment Armin Barbalata First version Armin Barbalata Added MNC, MCC 2013 Armin Barbalata Offer synchronized interface Chetan Kucheriya Added MNC Description Table 1: Revision History 3 CLX MSISDN LOOKUP INTERFACE DESCRIPTION REVISION HISTORY

4 Introduction 2.0 CLX messaging service platform provides a secure and highly available platform. This document describes the CLX HTTP Interface for querying specific MSISDNs and provides various examples. 2.1 Setup and Connection Data The HTTP messaging interface supports querying of MSISDNs via the HTTP GET method. CLX provides customers with the interface URL, customer identification number (cid), a password, a profile and a target URL used for the delivery of data via HTTP(S)-Request. 2.2 Resource Management Due to security reasons CLX uses an IP-address white-list. Each customer must provide their IP-Address to apply for a CLX HTTP account. If the maximum number of connections per IP address or of the system are reached, the system will reply with an HTTP status code 503 (system temporarily not available). In this case it is recommended to retry. Usually 10 parallel connections per IP address are allowed. 2.3 Timeouts CLX uses a HTTP timeout of 300 seconds. The HTTP protocol defines the timeout of an HTTP request. We recommend that clients use a higher value in their client implementation, as otherwise delayed responses may not be correctly evaluated. 4 CLX MSISDN LOOKUP INTERFACE DESCRIPTION INTRODUCTION

5 HTTP Interface Description Interface Base URL be provided by CLX>/msisdnlookup/query 3.2 Interface Parameter Parameter Type Description version m Version 2.1 is the version which return response with MNC description Example 2.1 cid m customer identification, numeric value 3512 password m customer authorisation, alphanumeric value Secret msisdn m Target numeric telephone number starting with the complete country code profile m determines how accurate the data query is 1 mnp lookup Example MSISDN Query be provided by CLX>/msisdnlookup/query? version=2.1 &cid=3512 &password=geheim &profile=1 &msisdn= Interface Parameter In response to their HTTP(S) Request, the customer receives a XML Document (HTTP response code 200) containing the information displayed in the following table. 5 CLX MSISDN LOOKUP INTERFACE DESCRIPTION HTTP INTERFACE DESCRIPTION

6 HTTP Interface Description 3.0 For global errors, the interface will generate an HTTP response unequal to 200, e.g. Service Unavailable (HTTP 503) Internal Server Error (HTTP 500) Tag Description Example <msisdnreport> </msisdnreport> Root-Tag which contains single return values. Attribute Type Description Example version m Version of report 2.1 msisdn o numeric telephone number, that was queried, starting with the complete country code guid o This attribute contains the unique message ID (GUID) of this message. The message ID is a string containing maximum 128 characters. Through the guid a mapping can be done with the former query D67C865FB6FA25A9261C75 E8D2F0F2B mnc o Mobile network code 07 mcc o Mobile country code 262 mnc-name o Mobile network code name D1 mncdescription o Mobile network code description T-Mobile 6 CLX MSISDN LOOKUP INTERFACE DESCRIPTION HTTP INTERFACE DESCRIPTION

7 HTTP Interface Description 3.0 mcc-name o Mobile country isocode name result m Attribute that shows whether the MSISDN query was successfully (success) or unsuccessfully (error) delivered to CLX. DE success error success absent_subscriber errorcode o This tag contains a numerical code in the case of an error errormessage o In case of an error, this attribute displays a detailed error message 7 Invalid password Example of an Eeisting MSISDN: <?xml version= 1.0 encoding= ISO ?> <msisdnreport version= 2.1 result= success msisdn=" " guid="e149c311d4dfa3ac5a611abf2a06dc0c" mnc= 07 mcc= 262 mncdescription= T-Mobile mnc-name= D1 mcc-name= DE /> Example of an invalid interface call: <?xml version= 1.0 encoding= ISO ?> <msisdnreport version= 2.1 result="error" errorcode="6" errormsg="invalid cid" /> 7 CLX MSISDN LOOKUP INTERFACE DESCRIPTION HTTP INTERFACE DESCRIPTION

8 Configuration URLs and Downloads 4.0 Configuration constants and network information can be download via HTTP GET requests. Note: All interfaces listed here are not designed to be accessed by runtime processes or to be used for batch queries. CLX may apply request throttling filters to restrict the access to < 10 request per minute per remote IP at any time. There is no guaranteed response time for these types of requests. 4.1 Error Codes All interface error codes are available as HTML documentation online: be provided by CLX>/msisdnlookup/errorcodes 8 CLX MSISDN LOOKUP INTERFACE DESCRIPTION CONFIGURATION URLS AND DOWNLOADS