Integration Guide

User Information
Version 1.2 November 2007

Version 1.2

Page 1 of 8

Contents
CONTENTS.......................................................................................................................................................................2 DOCUMENT CHANGE LOG .........................................................................................................................................3 INTRODUCTION..............................................................................................................................................................4 WEB SERVICES API ......................................................................................................................................................5 SECURITY ........................................................................................................................................................................5 WSDL LOCATION ...........................................................................................................................................................5 REQUESTING W EB SERVICES ACCESS...........................................................................................................................5 W EB METHODS ...............................................................................................................................................................6 GetMobileNumber ....................................................................................................................................................6 GetUserId ..................................................................................................................................................................7 MarketingOptOut ......................................................................................................................................................8

Version 1.2

Page 2 of 8

Document change log

Date 20 June 2007 03 October 2007 23 November 2007 Version 1.0 1.1 1.2 Change detail Published MarketingOptOut method added GetMobileNumber responses extended GetMobileNumber response OPERATOR_REFUSED replaced with OPERATOR_REJECTED

Version 1.2

Page 3 of 8

Introduction
The Bango User Information service allows you to securely find out useful information relating to users registered in the Bango platform, for example a users mobile phone number for marketing or support purposes. The User Information service is likely to be expanded so please refer to the latest version of this document. User information supports the following scenarios: You have the user MSISDN and want to match it to the Bango Fingerprint You have the Bango Fingerprint and want to match it to the users MSISDN for agreed reasons. For example marketing or customer care purposes. You wish to inform Bango that a user has opted out of your service.

Version 1.2

Page 4 of 8

Web Services API

The Web Services API is a secure server-to-server API allowing access to the details of users held within the Bango system.

Security
The Web Services API is protected to ensure that only authorized clients use it. There are three primary levels of security: API username / password and third-party account authentication Client IP address validation Secure Sockets Layer (SSL) data transport

A failure at any one of these security levels denies access to the Web Services API. The Web Services API allows your server to send requests to the Bango server. The Bango server will only accept requests from authorized IP addresses. Requests directly from an on-handset application are not allowed the application must communicate with your server, which must then communicate with the Bango Web Services API.

WSDL Location
The User Information WSDL can be located at the following URL: https://webservices.bango.com/userinformation/?wsdl

Requesting Web Services access

Before you can use the Web Services API, you need to first request access credentials from Customer Services via support@bango.com. Access to the API is dependant upon package level. If you are unsure whether the API is available to you please contact Customer Services.

Version 1.2

Page 5 of 8

Web Methods
Method: Description:

GetMobileNumber
Returns a users mobile phone number (MSISDN). A request for a users mobile phone number must be accompanied with a purpose as operator policies on providing the number do vary. You must only use the mobile phone number for the purpose stated. For example, if you request the mobile phone number for SUPPORT you cannot then go on and use the same number for MARKETING.

Inputs:

username password userId bango purpose

Your username Your password User ID Bango Number Why the phone number is required - one of: SUPPORT DELIVERY MARKETING PARTNERMARKETING

Outputs:

responseCode responseMessage usageCondition mobileNumber

Status of request. Indication of whether the users mobile number can be used for the requested purpose. Textual description of request status Free-text description of any operator conditions associated with using the mobile number for the requested purpose Users mobile number (or empty string if not released) Success Invalid username/password Invalid IP address Invalid access to specified Bango number Invalid Bango number Invalid user ID Invalid purpose code A problem on the server meant that the request could not be processed Operator not known for this user Operator will not release MSISDN Mobile number not known for this user User has not yet opted into marketing User has explicitly opted out of marketing User opt-in has expired; i.e. greater than 6 months old

Response Codes:

OK ACCESS_DENIED ACCESS_DENIED ACCESS_DENIED INVALID_BANGO INVALID_USERID INVALID_PURPOSE INTERNAL_ERROR OPERATOR_UNKNOWN OPERATOR_REJECTED NO_MOBILE_NUMBER USER_NOT_OPTED_IN USER_OPTED_OUT USER_OPTIN_EXPIRED

Version 1.2

Page 6 of 8

Method: Description:

GetUserId
Returns the user id (Fingerprint) for a mobile phone number on a specific operator. If the user is already known to the Bango system, their user id will be returned. If the user is not known, but is on an operator which passes real-time MSISDNs to Bango, a new user account is automatically created and the user id returned. When the user does access the Bango system and their MSISDN is passed to Bango by their operator, this is the user id they will be assigned.

Inputs:

username password userId mobileNumber networkId bango

Your username Your password User ID The mobile number to search for must be international format i.e. 16141234567 or 447787123456 Bango operator id (see Relay documentation for list) A Bango Number accessible by these credentials Status of request. Textual description of request status User id for this mobile number Success Invalid username/password Invalid IP address Invalid access to specified Bango number Invalid Bango number A problem on the server meant that the request could not be processed Matching user id not found (and cannot be created)

Outputs:

responseCode responseMessage userId OK ACCESS_DENIED ACCESS_DENIED ACCESS_DENIED INVALID_BANGO INTERNAL_ERROR NOT_FOUND

Response Codes:

Version 1.2

Page 7 of 8

Method: Description:

MarketingOptOut
Notifies Bango a user has opted out of your service. A request for opting out a user must be accompanied with a Bango Number belonging to your service.

Inputs:

username password userId bango responseCode responseMessage OK ACCESS_DENIED ACCESS_DENIED ACCESS_DENIED INVALID_BANGO INTERNAL_ERROR

Your username Your password User ID A Bango Number accessible by these credentials Status of request. Textual description of request status Success Invalid username/password Invalid IP address Invalid access to specified Bango number Invalid Bango number A problem on the server meant that the request could not be processed

Outputs: Response Codes:

Version 1.2

Page 8 of 8