May 1, 2023pg. 0

CognITO API SPECIFICATION

Cognito APIS

Sunita Shrivastava(SunitaS), VinaSura, KaSandee,[Email address]

AbstractCognito APIs allow mobile applications to get upload user tagged information about callers both phone/instant message sender to

the Cognito Cloud service to enable user migration and crowd sourced inferencing scenarioss

Contents1. APIS......................................................................................................................................................2

1.1 Description of Headers used by the service.................................................................................2

5.1 Response Objects........................................................................................................................2

2 Core APIs.............................................................................................................................................4

2.1 GetServicesEnabledForMarket....................................................................................................4

2.2 RegisterAppforUser.....................................................................................................................6

2.3 IsAppRegisteredForUser..............................................................................................................8

2.4 GetRegistrationDataForPhoneNumber......................................................................................10

2.5 UploadTags................................................................................................................................11

2.6 RetrieveTags..............................................................................................................................16

2.7 BackupAppUserData..................................................................................................................18

2.8 RestoreAppUserData.................................................................................................................19

2.9 Lookup.............................................................................................................................................20

2.10 SendFeedbackforLookup...........................................................................................................22

2.11 UnRegisterAppForUser..............................................................................................................24

Cognito Unified API Specification1. APIS

1.1 Description of Headers used by the service

AppId The appId to be used for verifying the client as well as logging and monitoring

AppTicket A ticket scoped to our service that can securely identify an app to the service. Not supported currently.

RequestId An id string given by client for each request, it can be current time as string or any other string unique such that we are able to track that request based on it

AuthType This can be set to NONE, MSA, MSAPHONEONLY(?). Currently, only None or MSA are supported.

MSAAuthTicket Required when AuthType = MSA.MSA ticket scope to our service (lw.basic.phonebook.cloudapp.net) with MBI_SSL policy.

PhoneVerificationType Technique to verify phone number. Can be set to “MSA”, “ABCH”

ABCHAuthTicket Ticket to access the user profile from ABCH, used for phone verification

Office365AccessToken The access token for accessing contacts from the Office 365 on behalf of the user as a part of Sync Calls.

AppVersion (?) The calling app’s version, to/can be used for stats/debug purpose.

DeviceID Unique Device on the mobile phone.

Locale Locale string (should reflect the language in which the user provides tag and address book names)

1.2 Response Objects

The following response codes are used

// this code is sent when the api is successfulSUCCESSFUL,//When Only Location is Sent in Lookup

SUCCESSFUL_ONLY_LOCATION

// The customer Id from the MSA token and the one mentioned in ABCH profile did not matchFAILURE_MSA_AND_ABCH_USER_NOT_MATCHED,

// The input MSA ticket has expiredFAILURE_EXPIRED_MSA_TICKET,

// For now we are not using this error codeFAILURE_FORBIDDEN,

// The ABCH profile of the user does not have Phone number or we face issue while parsing the profileFAILURE_INVALID_ABCH_PROFILE,

// The input ABCH ticket is not validFAILURE_INVALID_ABCH_TICKET,

// This error will be thrown by lookUP api when we dont have any information about the looked up phone numberFAILURE_NO_INFORMATION,

// The input MSA ticket is not validFAILURE_INVALID_MSA_TICKET,

// The input parameter has failed validation or is missing. For now we are validating only the bounding values for paramFAILURE_INVALID_PARAMETER,

// The Authentication ticket was not present in the header// Client library is sending the input tickets as headers to the service. This error code most likely indicates bug in client libraryFAILURE_MISSING_TICKET,

// The status of the user phone number passed as input is not verifiedFAILURE_PHONE_NUMBER_NOT_VERIFIED,

// The service failed to deserialize the contact list, block list or ABCH profileFAILURE_SERIALIZATION_ERROR,

// There is error in the service configuration. This means a potential issue on server sideFAILURE_SERVICE_ERROR,

// The input user phone number does not match with any of the verified numbers in user's ABCH profile// So we conclude user is not authorize to send requests for input numberFAILURE_USER_NOT_AUTHORIZED,

// This error code will be thrown when we get error from Volley. Normally I have seen this error come only when Volley is not able to deserialize response as per format// requested by return callback. e.g If callback is expecting JSON and we get string from serverFAILURE_VOLLEY_ERROR,

// The API failed as network connectivity is not present// Please note this can be due to either network not being present or user's network preferenceFAILURE_NO_NETWORK_CONNECTIVITY,

// The user is not registeredFAILURE_UN_REGISTERED_USER,

// Invalid application idFAILURE_INVALID_APPID,

// The called API failed with an un-known errorFAILURE_UNKNOWN,

// User Not Registered For Notification ServiceFAILURE_NOTIFICATION_UN_REGISTERED_USERFAILURE_AUTHENTICATION_REQUIRED – RegisterUser, GetRegisterationInfo,Backup and Restore, UploadTags in general all the API which requires AUTH

FAILURE_INVALID_ABCH_TICKET – same as above, where there is user phone number passed

FAILURE_INVALID_AUTHTYPE – the passed authtype is invalid, all API which pass authtype

FAILURE_INVALID_PHONEVERIFICATIONTYPE – the passed phone verificaiton type is invalid, all api which pass phone verification type

FAILURE_INVALID_COUNTRY_INFO – passed market identifier or its type is invalid, apis which takes marketIdentifier and its type like GetServiceEnabled, Lookup, upload tags

FAILURE_MISSING_ABCH_TICKET - the passed phone verificaiton type is ABCH but ABCH ticket is missing, all api which pass phone verification type as ABCH

PARTIAL_SUCCESS – passed by UploadTags when some tag upload happened successfully but failed for some tag

FAILURE_REACHED_MAX_LIMIT_FOR_SYNC – passed by UploadTags when tag upload reached the limit like only 100 blockedCall numbers can be uploaded

TAG_UPLOAD_FAILED – when uploadtag failed for all tagdata

FAILURE_UPLOAD_NOT_ALLOWED_MKT – Returned by upload tags when some tag upload (like address book upload) is not allowed in that market

FAILURE_USER_BLOCKED – return by all api when a user is blocked (by ADMINS if detected as malicious user) and calls the api

FAILURE_USER_UNLISTED – return by all api when user phone number is unlisted from lookup then that user is not allowed to call any api.

FAILURE_UNSUPPORTED_CLIENT_VERSION – returned by all API if the current appversion is not supported by the Service, in this case user should be asked to update to latest app.

FAILURE_NO_BACKUP_FOUND – returned by RestoreAppUserData if no backup data found for that user

2 Core APIs

2.1 GetServicesEnabledForMarket

An application can call this API to get a list of services enabled and available in a given market. This also allows us to address privacy concerns, where certain markets do not allow collection of certain classes of user data or use of such data.

The following is the complete list of services provided:

LocalBusinessCallerIdSpamDetectionLocalSearchPersonalCallerId

ReportAppTagsReportAddressBookTagsRetrieveTags [TBD: is that really a separate service??]

PresenceBuddyDiscoveryInvite

Cognito Services accept two kinds of data; App tag data and user Addressbook data. App Tag data is the association that a user makes for a given tgt entity in the context of the app. Based on both it provides for a set of services. In general, if ReportAddressBookTags is disabled for a market; PersonalCallerId will be disabled as well. However, it is possible for ReportAddressBookTags to be enabled and PersonalCallerID to be disabled, if there are precision issues.

Url https://phonebook-int.cloudapp.net/PhonebookService.svc/GetServiceEnabledForMarket

Method GETBODY Type Application/jsonHeaders AppId(Mandatory), RequestId(M),

AppVersion(M), AppTicket(0)

ReturnType JsonReturn Members

ResponseCode()

Access Points

Environment

Service URI

Test https://phonebook-int.cloudapp.net/PhonebookService.svc/GetServicesEnabledForMarket

Production https://www.bing.com/local/PhonebookService.svc/GetServicesEnabledForMarket

Parameters

Name Required Type Example Description

marketIdentifier Yes string IN Market Identifer and Identifer Value must be provided.

type Yes string CC Types can be either CountryCode (CC), MobileCountryCode (MCC), MarketLocale (Locale)

Response

EnabledForMarket:{ ServicesEnabled : { SpamDetectionService: Yes PersonalCallerId : No BusinessCallerID : Yes ReportAppTags : Yes ReportAddressBookTags : Yes RetrieveTags : Yes BusinessCallerId: Yes Presence: No BuddyDiscovery: }"TagsConfiguredForApp" : { "AddressBookName" : "Public", "SuggestedName" : "Public", "BusinessCategory" : "Public", "BlockedCall" : "Public", "BlockedSms" : "Public", "PromotionSms" : "Public" }

TagsEnabled: { SuggestedName : {

UploadAllowed=TRUE/FALSEUsed = TRUE/FALSE}

BlockedCall : {UploadAllowed = TRUE/FALSEUsed = TRUE/FALSE}

BlockedSMS : {

UploadAllowed = TRUEUsed = FALSE}

AddressBookName : {UploadAllowed = FALSENameUploadAllowed = TRUE/FALSE; in some markets only phone numbers will be

uploaded to enable buddy discovery and presence.Used = FALSE

}

}Note on ReportTags: If ReportTags is enabled, then the service uses Tag data for inferencing purposes. If not, then it doesn’t use the tag data. However, tag data can still be uploaded to Cognito for synchronization purposes.

TBD: Do we really need to tell the app whether the tag will be used or not used? Or is it an internal setting. Seems more like an internal setting. InternalPolicy

2.2 RegisterUserForApp

An application user can register with PhoneBook Service if he can be authenticated. This API is idempotent. The App must call it with the same credentials where there is a change of ‘Name’ or if there is a different address book upload flag or if the device id changed or if a new phone number is detected by the application or if the user updates his app profile and adds the phone number to it. But values there were provided earlier that are not changing must be provided again. If the app detects that the old phone number has been replaced by a new phone number on the same device, it is recommended that the App call UnRegisterUser() and then call RegisterUser again with the new phone number.

This API must be called in order for the user to upload tags to the service or to provide any kind of data to the service. [TBD: Currently we assume that lookup can be called without calling RegisterUserForApp(), privacy wise???]

An Entity is created/updated for a given user with the appropriate application registration information. An entity that is created by calling RegisterUser is also marked as “Registered”. Note that the same entity may be registered by multiple apps, Cognito remembers each one independently.

Url https://phonebook-int.cloudapp.net/PhonebookService.svc/RegisterUserForAppMethod POSTBODY Type Application/jsonHeaders AppId(Mandatory), RequestId(M), AuthType (M), PhoneVerificationType(M),

AppVersion(M), Office365AccessToken(Optional), DeviceTicket (0), If AuthType = MSA, MSAAuthTicket is (M)If PhoneVerificationType = ABCH, ABCHAuthTicket is (M)If PhoneVerificationType = MSA, then MSA signin should be phonenumber signin and should match with given phone number

ReturnType JsonReturn Members

Response Code

Access Points

Environment

Service URI

Test https://phonebook-int.cloudapp.net/PhonebookService.svc/RegisterUserForApp

Production https://www.bing.com/local/PhonebookService.svc/RegisterUserForApp

BodyParameters

Name Required Type Example Description

userPhoneNumber No string +919999999999 userPhoneNumber is verified at the time of registration. If not provided, a Phone Entity Node with a PUID ID is created.

Additional Identity information will be extracted from the ticket and saved along with this registration. This will include the LoginId(PUID) and AccountName. DeviceID and other aliases may be

optionally retrieved from the ticket.

username N string Vinay Surana Name of the registering user.

contactsUploaded Y bool TRUE/FALSE

Whether this phone number owner had agreed to upload contact book details.

deviceId Y string Device ID is validated against a device ticket if present

2.3 IsAppRegisteredForUser

This returns information around app registrations done in context of a given authenticated user.

What are the use cases for this API? For now, RegisterUser() is idempotent, so we don’t feel this API is required.

An application can check if the user has registered with the same app. If the app user provides the same MSA credentials, the set of registrations against that user can be discovered by the application.

Needs secure app id. Does not need secure device ids as that is treated like a parameter. A different app should not be able to phish for registration information.

Url https://phonebook-int.cloudapp.net/PhonebookService.svc/IsRegisteredUserMethod POSTBODY Type Application/jsonHeaders AppId(Mandatory), RequestId(M), AuthType (M), PhoneVerificationType(M),

AppVersion(M), Office365AccessToken(Optional), DeviceTicket (0), If AuthType = MSA, MSAAuthTicket is (M)If PhoneVerificationType = ABCHVerificationTpe, ABCHAuthTicker is (M)

ReturnType JsonReturn Members

Response Code

Access Points

Environment

Service URI

Test https://phonebook-int.cloudapp.net/PhonebookService.svc/IsAppRegisteredforUser

Production https://phonebook.cloudapp.net/PhonebookService.svc/IsAppRegisteredforUser

BodyParameters

Name Required Type Example Description

userPhoneNumber No string +919999999999 userPhoneNumber is optional but when provided is verified. Appropriate headers for phone verification must be set.

The MSA identity information is extracted from the MSA ticket

deviceID N string nbkhghejgwjhg DeviceID

Response

All existing registrations for a given MSA user will be returned in the response body. A registration is identified as:

//app uninstalled and reinstalled UserAlreadyRegistered : MSA Identity, Phone Number and device ID matches exactly with the

previous registration. If phone number is not supplied, the other two match then this type is returned as well.

//SIM Changed on the same device UserRegisteredOnDevice: MSA Identity and DeviceID match, phone number is different,

whether it is optionally provided or not//SIM moved to another phone UserRegisteredWithSamePhoneNumber : MSA identity and phone number match, device id is

different//same user, two devices UserRegisteredNoMatch : MSA identity match, neither the phone number nor the device id

match

TBD: Is there a need to return the pExistingRegistrations:{

Count: 2

List: {

{

Type: UserAlreadyRegistered UserName: “Vinay Surana”

}

{

Type: UserRegisteredWithSamePhoneNumber

//the same app is installed by this user on another device

UserName : “Vinary

}

{

2.4 GetRegistrationDataForPhoneNumber

This API allows application to retrieve the app user registration information, which was used for a prior app registration that was done in context of this phone number. AuthType is mandatory and AuthNone is not supported. PhoneVerificationMethod is mandatory. The phone number will be verified. The data is returned only if the PUID of the prior registration matches.

Url https://phonebook-int.cloudapp.net/PhonebookService.svc/GetRegistrationDataforPhoneNumber

Method GETBODY Type Application/jsonHeaders AppId(Mandatory), RequestId(M), AuthType (M), PhoneVerificationType(M),

AppVersion(M), Office365AccessToken(Optional), DeviceTicket (0), If AuthType = MSA, MSAAuthTicket is (M)If PhoneVerificationType = ABCHVerificationTpe, ABCHAuthTicker is (M)

ReturnType JsonReturn Members

Response Code

Access Points

Environmen Service URI

t

Test https://phonebook-int.cloudapp.net/PhonebookService.svc/GetRegisterationDataForPhoneNumber

Production https://www.bing.com/local/PhonebookService.svc/GetRegistrationDataForPhoneNumber

Parameters

Name Required Type Example Description

userPhoneNumber Y string +919999999999 userPhoneNumber for which registration info in required

deviceID N string nbkhghejgwjhg DeviceID

contactsUploaded Y bool TRUE/FALSE

Response

The following json is returned in the response body.

PhoneNumberRegistrationInfo :{

username: “Sunita Shrivastava”

deviceId : nkhjkshjkhf

contactsUploaded : TRUE/FALSE

}

2.5 UploadTagsTags are attributes that a user on a given device can assign to a target entity. The target entity is usually a phone number. (will we support sender tags?).

This API is used to upload tags to the Cognito service in context of an app user. The intent of the UploadTags() and Retrieve Tags is to provide a sync service to application across devices and applications for the user. If “ReportTags” is disabled for a given tag in a market(the market to which the user belongs), the tag data for that tag will not be accepted through the UploadTags API. However, the

“Backup/Restore” API will be accepted. If ‘”ReportAddressBook” is disabled, the address book tags will not be accepted.

It is assumed that the client keeps a cache of tag data locally and uploads only tags, which have changed since the last upload. Note that it is possible for a user to set tags from multiple devices. A client keeps the local cache in sync by applying the changes locally to the cache if there are changes pending, locking the local cache, doing an UploadTags followed by a RetrieveTags. At this point, it can unlock the cache for further updates.

Here is the suggested sequence to synchronize the local copy of the tags with that in the Cognito Cloud:

{LockLocalTagsCacheUpload Changed Tags (Use UploadTags(incremental) to upload tags which haven’t been uploaded)RetrieveTagsUnlockLocalTagsCache

}

It is recommended that an app periodically perform this sequence to keep its local copy in sync. It is also advised that App not try and perform the synchronization operation during an incoming call but simply use the values in the local cache to avoid latency issues.

The following schema is advised for keeping track of the tag data locally. Possible values for Action are C(Created), U (Updated), D(Deleted). Once a deleted value is uploaded, it can be deleted from the local cache.

<TagName, DstPhoneNumber, CurrentTagValue, OldTagValue(?), Action, IsChangeUploaded>

AddressbookName a Special Tag

AddressbookName is a special tag which can only be only uploaded and not retrieved. Cognito can use these tags for inferencing but is not responsible for synchronization. An app should monitor changes to the address book and upload the change incrementally. For the multi device case, the second upload in fails with an error

{StartMonitoringChanges()CreateLocalCacheForName()RetCode = UploadAllContacts() (use UploadTags in snapshot mode, with force flag false)

If (RetCode == AlreadyExists){

//assume another device has uploaded this data and just send the changes you are //tracking//however, this can result in loss, unless snapshot uploads are coupled with an etag //like version number

}}

ChangeToAddressBook(){

LockNameCache()

UpdateLocalCacheForName() //modify entries and set ChangeUploaded to be falseUnlockNameCache()

}

UploadChangedContacts{

UploadTags(in incremental mode)

}

TagTypes

There are two types of tags, public and read-only. An app can set a public tag, if is OK for the app user to be able to modify these tags in the context of different apps. An app can set a read-only tag, if it is willing for other apps to read the tags but would not like other apps to overwrite the tags that the user has created in its context. This may be true for applications that ship natively on the device.

TBD: Should we support private tags as well.

Modes of Upload

Two modes of upload are supported: incremental and snapshot. The snapshot removes and replaces the cloud tags with the ones provided in the API and should be used with caution.

The following tag names are supported and may be uploaded to the service:

AddressBookName BusinessCategory BlockedCall BlockedSMS SuggestedName

Here are the tag values that are used for each of the above tags.

Tag Name ValueAddressBookName Contact: {

ContactName : Sunita Shrivastava (Optional) Source : Outlook }

Business Category String (e.g. “Bakery”)BlockedCall Null (the name suggested for a caller that is

blocked is sent separately with suggested name)BlockedSMS NULLSuggestedName suggested_name

Url https://phonebook-int.cloudapp.net/PhonebookService.svc/UploadTags

Method POSTBODY Type Application/jsonHeaders AppId(Mandatory), RequestId(M), AuthType (M), PhoneVerificationType(M),

AppVersion(M), Office365AccessToken(Optional), DeviceTicket (0), If AuthType = MSA, MSAAuthTicket is (M)If PhoneVerificationType = ABCHVerificationTpe, ABCHAuthTicker is (M), Locale(M)

ReturnType JsonReturn Members

ResponseCode(SUCCESSFUL/PARTIAL_SUCCESS/TAG_UPLOAD_FAILED), ErrorMessage

AccessPoints

Environment

Service URI

Test https://phonebook-int.cloudapp.net/PhonebookService.svc/UploadTags

Production https://www.bing.com/local/PhonebookService.svc/UploadTags

Body

Json object of the body parameters

Body Parameters

Name Required Type Example Description

userPhoneNumber

N string +919999999999 If userPhoneNumber is provided, it is verified.

tagData No string TagData : [{ TagName: Mode: “incremental/snapshot” { dstPN: Action:”Create/Update/Delete”,UpdateTime:epochTS TagValue: } { }}]

If tagdata is empty and office365AcccessToken is provided, then the service will sync the contact data from Office and TagData doesn’t need to be specified. If Action is Snapshot, the action is assumed to be create. All existing tags with that tagName are deleted.

deviceID Y string "123" Used for identification of source entity.

marketIdentifier Yes string IN Market Identifer and Identifer Value must be provided.

marketIdentifierType Yes string CC Types can be either CountryCode (CC), MobileCountryCode (MCC), MarketLocale (Locale)

Sample Request Tag Data Object{

"TagData" : {

"TagDataItems" : [{

"Mode" : "incremental",

"TagList" : [{

"Action" : "C",

"UpdateTime" : 1461311757,

"Value" : "",

"dstPN" : "9000498404"

}, {

"Action" : "D",

"UpdateTime" : 1461311757,

"Value" : "",

"dstPN" : "9000498405"

}

],

"TagName" : "BlockedCall"

}, {

"Mode" : "incremental",

"TagList" : [{

"Action" : "C",

"UpdateTime" : 1461311757,

"Value" : "testcat",

"dstPN" : "9000498404"

}, {

"Action" : "D",

"UpdateTime" : 1461311757,

"Value" : "spamcat",

"dstPN" : "9000498405"

}

],

"TagName" : "BusinessCategory"

}, {

"Mode" : "incremental",

"TagList" : [{

"Action" : "C",

"UpdateTime" : 1461311757,

"Value" : "{\\" ContactName \\ ":\\" testName \\ ",\\" Source \\ ":\\" testing \\ "}",

"dstPN" : "9000498404"

}, {

"Action" : "C",

"UpdateTime" : 1461311757,

"Value" : "{\\" ContactName \\ ":\\" sandeep \\ ",\\" Source \\ ":\\" testing \\ "}",

"dstPN" : "9000498405"

}

],

"TagName" : "AddressBookName"

}

]

}

}

Response------------

1) PARTIAL_SUCCESS

{

"ResponseCode" : "PARTIAL_SUCCESS",

"PerTagResponse" : [{

"Key" : "AddressBookName",

"Value" : {

"ErrorMessage" : "Addressbook upload not supported: User puid#deviceId",

"ResponseCode" : "FAILURE_FORBIDDEN"

}

}]

}

2) SUCCESSFUL{

"ResponseCode" : "SUCCESSFUL",

"PerTagResponse" : []

}

3) FAILURE{

"ResponseCode" : "TAG_UPLOAD_FAILED",

"PerTagResponse" : [{

"Key" : "AddressBookName",

"Value" : {

"ErrorMessage" : "Addressbook upload not supported: User puid#deviceId",

"ResponseCode" : "FAILURE_FORBIDDEN"

}

},

{

"Key" : "BusinessCategory",

"Value" : {

"ErrorMessage" : "BusinessCategoryupload not supported for this market",

"ResponseCode" : "FAILURE_MKT_NOT_SUPPORTED"

}

}]

}

2.6 RetrieveTagsAn app user can query for a set of tags that emanate from Source Entities corresponding to his user Identity. Optionally, he can get tags from Source Entities, for which he has valid ownership proof through authentication. E.g. <A2, p1, d1> <A2, p2, d1> registrations will create two different user registrations. User, with the PUID corresponding to A2, can query for the set of tags that emanate from any of the entity nodes, which have a matching PUID. AuthType NONE will result in failure; the caller must be authenticated.

Url https://phonebook-int.cloudapp.net/PhonebookService.svc/RetrieveTagsMethod GETBODY Type Application/jsonHeaders AppId(Mandatory), RequestId(M), AuthType (M), PhoneVerificationType(M),

AppVersion(M), Office365AccessToken(Optional), DeviceTicket (0), If AuthType = MSA, MSAAuthTicket is (M)If PhoneVerificationType = ABCHVerificationTpe, ABCHAuthTicker is (M)

ReturnType JsonReturn Members

ResponseCode, Error Message, tagData

Access Points

Environment Service URI

Test https://phonebook-int.cloudapp.net/PhonebookService.svc/RetrieveTags/{tagfilter=All}& {userPhoneNumber=} & {SrcEntityScope = MatchedPUID}

Production https://www.bing.com/local/PhonebookService.svc/RetrieveTags

Body Parameters

Name Required Type Example Description

UserPhoneNumber N string PhoneNumber: +919999999999

If a Phone Number is provided, it must verified.

Tagfilter Yes List TagList: { BlockedSMS, BlockedCall}

One or more of the tags supported by the ontology. Get is not supported on the “AddressBookName” Tag.

AppIDfilter No int Can be set to one of: MyAppIDOnly MyAppFamilyOnly All

The service will filter tags based on which appid context they were set in. If ‘All’ is chosen, then all public tags are made available as well.

dstEntityFilter No List dstList{ PhoneNumber: SenderName : }

If specified, then only tags that refer to that target phone numbers or sender name are returned. If this is not specified, the tags are not filtered by destination.

Response

TagData will be returned as follows:

TagData:{ TagName : Category

TagCount: 3 Tags: { TagValue: “Grocery” dstPN: TimeLastModified: DeviceID: } { TagValue : “Electrical Supplies”:……….dstPN: TimeListModified: } {

TagValue:

} TagDataFromSrc{ SrcEntity{ } TagCount: Tags{}

Response Format

Standard serverResponse object for success or failure.

2.7 BackupAppUserDataBackup allows an application to backup some user data in the context of a user.

The main purpose of backup is to be able to restore User data in scenarios

where the device is reset and app needs to be reinstalled when the SIM changes and user registers with a new phone number on the same device when the device is lost and the user moves the SIM to a new device and installs the app when the user installs the app on an additional device

AuthType NONE is not supported. An app can have at most 20 data types. An app can create at most 10 backups with a particular data type in the context of an app.

A backup is annotated with <AppId, PUID, DeviceId, PhoneNumber>. Phone Number is optional.

Url https://phonebook-int.cloudapp.net/PhonebookService.svc/BackupAppUserDataMethod POST

BODY Type Application/jsonHeaders AppId(Mandatory), RequestId(M), AuthType (M), PhoneVerificationType(M),

AppVersion(M), DeviceTicket (0), If AuthType = MSA, MSAAuthTicket is (M)If PhoneVerificationType = ABCHVerificationTpe, ABCHAuthTicker is (M)

ReturnType JsonReturn Members

Basic ResponseCode, ErrorMessage

AccessPoints

Environment

Service URI

Test https://phonebook-int.cloudapp.net/PhonebookService.svc/BackupAppUserData

Production https://www.bing.com/local/PhonebookService.svc/BackupAppUserData

Body

Json object of the body parameters

Body Parameters

Name Required Type Example Description

userPhoneNumber

N string +919999999999 If userPhoneNumber is provided, it is verified. Also, the backup is marked as being saved in the context of this phone number.

dataType Y int 4 This is opaque to Cognito

deviceId Y string The backup is marked as being saved in context of this device id.

data Y string The data (can encrypted text, or hashed text, etc.)to upload to cloud. It is an opaque blob for the user.

2.8 RestoreAppUserData

App can call this to use Restore user specific application data that was backup earlier. This is useful, if an app is being installed/enabled on a device after reset, moving the SIM to another device or a SIM change on the same device.

Reset or Moving the SIM to another device

After reset, the device id may change. If the user continues to use the same phone number as before, the app can retrieve the tags he had used by calling RestoreAppUserData() and providing the same phone number. If the user hadn’t provided a phone number, it will try and restore the app data which was saved with the same PUID:deviceId. If that is not found, then it will restore the user data, from the same PUID but with a different device id. If multiple such backups exist, it will return the most recent one of those.

Installing the app on a Second Device

An app can get use this API to restore the user application data on another device. RestoreAppUserData will make a copy of the user data from another backup, if one exists, and make a copy for the new device id.

The service keeps a mapping of backups performed in the context of a PUID.

Url https://phonebook-int.cloudapp.net/PhonebookService.svc/RestoreAppUserDataMethod POSTBODY Type Application/jsonHeaders AppId(Mandatory), RequestId(M), AuthType (M), PhoneVerificationType(M),

AppVersion(M), DeviceTicket (0), If AuthType = MSA, MSAAuthTicket is (M)If PhoneVerificationType = ABCHVerificationTpe, ABCHAuthTicker is (M)

ReturnType Response Code, JsonReturn Members

ResponseCode, Data

AccessPoints

Environment

Service URI

Test https://phonebook-int.cloudapp.net/PhonebookService.svc/RestoreAppUserData

Production https://www.bing.com/local/PhonebookService.svc/RestoreAppUserData

Body

Json object of the body parameters

Body Parameters

Name Required Type Example Description

userPhoneNumber

N string +919999999999 If userPhoneNumber is provided, it is verified. A backup that matches this PUID+Phone number is returned, if it exists. Else, a backup with PUID+DeviceID match is returned.

datatype Y int 4 This is opaque to Cognito. Data type for which the backup should be returned.

deviceId Y string

Response Format

{ “ResponseCode”: “SUCCESSFUL” “Data” : “jakjjhdjkhsfjkh”}

{ “ResponseCode”: “FAILURE_NO_BACKUP_FOUND” “Data” : null}

2.9 LookupLookup returns the inferred tags or properties for an entity.

AuthType header is needed. If AuthType is None you can only get business caller Id and spam count without spam name. If AuthType is MSA and an MSA token is provided, you can get personal caller ID assuming phone book is being uploaded (as per user consent and registration).

Each data center does inferencing in each locale for which it has data for a phone number. It also does locale agnostic inferencing. If locale specific inferenced name are not found, the locale agnostic inferenced names will be returned.

Url https://phonebook-int.cloudapp.net/PhonebookService.svc/LookUpMethod GETBODY Type ---Headers AppId(Mandatory), RequestId(M), AuthType (M), PhoneVerificationType(O),

AppVersion(M), Office365AccessToken(Optional), DeviceTicket (0),

If AuthType = MSA, MSAAuthTicket is (M)If PhoneVerificationType = ABCHVerificationTpe, ABCHAuthTicker is (M)

ReturnType JsonReturn Members

ResponseCode, Entity

AccessPoints

Environment

Service URI

Test https://phonebook-int.cloudapp.net/PhonebookService.svc/LookUp ? lookUpNumber={Phone}&userPhoneNumber={userPhoneNumber(Optional)}&locale={Locale(Mandatory)}&marketIdentifierType={MarketIdentifier}&marketIdentifier={MarketValue}

Production

https://www.bing.com/local/PhonebookService.svc/LookUp? lookUpNumber={Phone}&userPhoneNumber={userPhoneNumber(Optional)}&locale={Locale(Mandatory)}&marketIdentifierType={MarketIdentifier}&marketIdentifier={MarketValue}

Sample Requests:https://www.bing.com/local/PhonebookService.svc/LookUp?lookUpNumber=%2B8613911057528&userPhoneNumber=%2B8613911057528&locale=en-us&marketIdentifierType=MCC&marketIdentifier=405

https://www.bing.com/local/PhonebookService.svc/LookUp?lookUpNumber=%2B8613911057528&userPhoneNumber=%2B8613911057528&locale=zh-cn&marketIdentifierType=CC&marketIdentifier=CN

https://www.bing.com/local/PhonebookService.svc/LookUp?lookUpNumber=%2B8613911057528&userPhoneNumber=%2B8613911057528&locale=zh-cn&marketIdentifierType=Locale&marketIdentifier=zh-cn

Without User Phone Number

https://phonebook-int.cloudapp.net/PhonebookService.svc/LookUp?lookUpNumber=%2B8613911057528&locale=zh-cn&marketIdentifierType=Locale&marketIdentifier=zh-cn Response Format

JsonObject with Message and EntityData (PhoneNumberEntity)

Entity : {

Number:string,Number given in lookupIsSpam : boolean, whether the entity has been inferred to be SpamSpamCount: unsigned long, number of people marked this as spamInferredName: string, the name inferred by cloud service

RegisteredName: string, the name registered by a service (TBD: Privacy Concern: restrict by app?)BingName: string, the name for local businesses from BING BingCategoryName:string , category name from bingCity:string, City of the userState:string, State of the userCountry:string, Country of the userLocality:string, Locality of the USERInferredCategory:string, Category of phone number if businessCategoryCount:unsigned long, number of people choosing the above inferred category for this phone numberLocalBusiness: bool, is this a local business

}

Sample Response :

Success Response:

{"ResponseCode":"SUCCESSFUL","Entity":{"BingCategoryName":"Finance","BingName":"LocalBank","IsSpam":true,"LocalBusiness":true,"Number":"+8613911057528","SpamCount":5}}

No Information Response:{"ResponseCode":"FAILURE_NO_INFORMATION"}

EntityData{

IsSpam : boolean, whether the entity has been inferred to be SpamentityIdentifier : The entity as identified by the caller (additional identity is not revealed)SpamCount: unsigned long, number of people marked this as spamInferredName: string, the name inferred by cloud serviceBingName: string, the name for local businesses from BING City:string, City of the userLocality:string, Locality of the USERInferredCategory:string, Category of phone number if businessCategoryCount: LocalBusiness: bool, is this a local business

}

2.10 SendFeedbackforLookup

This API allows an app user to indicate that the information returned as a part of lookup was not satisfactory and propose a new value for it. The target can be a phone number or a sender tag.

The caller will be authenticated.

The feedback is queued for evaluation and will not impact inferred values instantaneously. TBD: Do we want the user to implicitly tag these. Without expiry? Currently the thought is no.

Url https://phonebook-int.cloudapp.net/PhonebookService.svc/SendFeedbackForLookup

Method POSTBODY Type Application/jsonHeaders AppId(Mandatory), RequestId(M), AuthType (M), PhoneVerificationType(M),

AppVersion(M), DeviceId (M), Office365AccessToken(Optional), If AuthType = MSA, MSAAuthTicket is (M)If PhoneVerificationType = ABCHVerificationTpe, ABCHAuthTicker is (M)

ReturnType JsonReturn Members

ResponseCode, ErrorMessage

AccessPoints

Environment

Service URI

Test https://phonebook-int.cloudapp.net/PhonebookService.svc/SendFeedbackForLookup

Production https://www.bing.com/local/PhonebookService.svc/SendFeedbackForLookup

Body Parameters

Name Required Type Example Description

marketIdentifier N string “CN” Market Identifier Value

marketIdentifierType N String “CC”| “ MCC”| “Locale” Types can be CountryCode, MobileCountryCode, MarketLocale

locale Y string “zh-cn” Locale for which feedback is given

targetId Yes string “123” Entity which was looked up. This

can either be a phone number of a sender tag.

entityFeedback Y string {\"Comment\":\"Sample\",\"AttributeSuggestions\":[{\"AttributeName\":\"BingCity\",\"Returned\":\"India\",\"Recommended\":\"Alto\"},{\"AttributeName\":\"BingCity2\",\"Returned\":\"India\",\"Recommended\":\"Alto\"}]}

Only values for which recommendations are being made need to be sent.

Json Formatted String

Response Format{"ResponseCode":"SUCCESSFUL"}

Sample Request and Response:POST https://phonebook-int.cloudapp.net/PhonebookService.svc/SendFeedbackForLookup

HTTP/1.1User-Agent: FiddlerHost: phonebook-int.cloudapp.netContent-Length: 317Content-Type: application/jsonAppId: TestAppVersion: 1.0.32ClientVersion: 1.0.32RequestId: 1234567AuthType: NONEDeviceId: 1234

{"marketIdentifier":"CN","marketIdentifierType":"CC","locale":"zh-cn","targetId":"123","entityFeedback":"{\"Comment\":\"Sample\",\"AttributeSuggestions\":[{\"AttributeName\":\"BingCity\",\"Returned\":\"India\",\"Recommended\":\"Alto\"},{\"AttributeName\":\"BingCity2\",\"Returned\":\"India\",\"Recommended\":\"Alto\"}]}"}

HTTP/1.1 200 OKCache-Control: privateContent-Length: 29Content-Type: application/json; charset=utf-8Server: Microsoft-IIS/8.5X-AspNet-Version: 4.0.30319X-Powered-By: ASP.NETDate: Mon, 25 Apr 2016 05:10:24 GMT

{"ResponseCode":"SUCCESSFUL"}

2.11 UnRegisterUserForApp

Should be called before uninstall.

An app user can unregister from the PhoneBookService. MSAAuthType NONE is not supported for this API.

Url https://phonebook-int.cloudapp.net/PhonebookService.svc/UnRegister UserForApp

Method POSTBODY Type Application/jsonHeaders AppId(Mandatory), RequestId(M), AuthType (M), PhoneVerificationType(M),

AppVersion(M), Office365AccessToken(Optional), DeviceTicket (0), If AuthType = MSA, MSAAuthTicket is (M)If PhoneVerificationType = ABCH, ABCHAuthTicker is (M)If PhoneVerificationType = MSA, MSA signin should phone number same as user phone number

ReturnType JsonReturn Members

Standard ResonseCode

Body Parameters

Name Required Type Example Description

userPhoneNumber

No string PhoneNumber: +919999999999 As provided in the RegisterUser() API.

deleteAllData Yes bool TRUE/FALSE If deleteAllData is true, all uploaded tags are deleted.

deviceId Yes