Cognito Unified API Specification

September 7, 2016pg. 0
COGNITO API SPECIFICATION
Cognito APIS
Sunita Shrivastava(SunitaS), VinaSura, KaSandee,
[Email address]
Abstract
Cognito APIs allowmobileapplicationsto get upload user tagged information about callersboth
phone/instantmessage sender to the Cognito Cloud serviceto enable user migration and crowd
sourced inferencingscenarioss

Contents
1. 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..............................................................................................................7
2.3 IsAppRegisteredForUser.......................................................................................................9
2.4 GetRegistrationDataForPhoneNumber................................................................................11
2.5 UploadTags .......................................................................................................................12
2.6 RetrieveTags......................................................................................................................19
2.7 BackupAppUserData..........................................................................................................21
2.8 RestoreAppUserData .........................................................................................................22
2.9 Lookup ...................................................................................................................................24
2.10 SendFeedbackforLookup....................................................................................................26
2.11 UnRegisterAppForUser.......................................................................................................28

Cognito Unified API Specification
1. APIS
1.1 Description of Headers used by the service
AppId The appId to be usedforverifying the clientaswell asloggingand
monitoring
AppTicket A ticketscopedtoour service thatcan securelyidentifyanapptothe
service.Notsupportedcurrently.
RequestId An idstringgivenbyclientforeachrequest,itcan be current time as
stringor any otherstringunique suchthatwe are able to track that
requestbasedonit
AuthType Thiscan be setto NONE,MSA, MSAPHONEONLY(?). Currently,only
None or MSA are supported.
MSAAuthTicket RequiredwhenAuthType =MSA.
MSA ticketscope to our service (lw.basic.phonebook.cloudapp.net)with
MBI_SSL policy.
PhoneVerificationType Technique toverifyphone number. Canbe setto “MSA”, “ABCH”
ABCHAuthTicket Ticketto accessthe userprofile fromABCH,usedforphone verification
Office365AccessToken The access tokenforaccessingcontacts fromthe Office 365 onbehalf of
the useras a part of Sync Calls.
AppVersion(?) The callingapp’sversion,to/canbe usedforstats/debugpurpose.
DeviceID Unique Device onthe mobile phone.
Locale Locale string (shouldreflectthe language inwhichthe userprovidestag
and addressbooknames)
1.2 Response Objects
The followingresponse codesare used
// this code is sent when the api is successful
SUCCESSFUL,

//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 match
FAILURE_MSA_AND_ABCH_USER_NOT_MATCHED,
// The input MSA ticket has expired
FAILURE_EXPIRED_MSA_TICKET,
// For now we are not using this error code
FAILURE_FORBIDDEN,
// The ABCH profile of the user does not have Phone number or we face issue while parsing the profile
FAILURE_INVALID_ABCH_PROFILE,
// The input ABCH ticket is not valid
FAILURE_INVALID_ABCH_TICKET,
// This error will be thrown by lookUP api when we dont have any information about the looked up phone number
FAILURE_NO_INFORMATION,
// The input MSA ticket is not valid
FAILURE_INVALID_MSA_TICKET,
// The input parameter has failed validation or is missing. For now we are validating only the bounding values for param
FAILURE_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 library
FAILURE_MISSING_TICKET,
// The status of the user phone number passed as input is not verified
FAILURE_PHONE_NUMBER_NOT_VERIFIED,
// The service failed to deserialize the contact list, block list or ABCH profile
FAILURE_SERIALIZATION_ERROR,
// There is error in the service configuration. This means a potential issue on server side
FAILURE_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 number
FAILURE_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 server
FAILURE_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 preference
FAILURE_NO_NETWORK_CONNECTIVITY,
// The user is not registered
FAILURE_UN_REGISTERED_USER,
// Invalid application id
FAILURE_INVALID_APPID,
// The called API failed with an un-known error
FAILURE_UNKNOWN,

// User Not Registered For Notification Service
FAILURE_NOTIFICATION_UN_REGISTERED_USER
FAILURE_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.1GetServicesEnabledForMarket
An applicationcancall thisAPIto geta listof servicesenabledandavailable inagivenmarket. Thisalso
allowsusto addressprivacyconcerns,where certainmarketsdonotallow collectionof certainclassesof
userdata or use of such data.
The followingisthe completelistof servicesprovided:
LocalBusinessCallerId
SpamDetection

LocalSearch
PersonalCallerId
ReportAppTags
ReportAddressBookTags
RetrieveTags [TBD: is that reallya separate service??]
Presence
BuddyDiscovery
Invite
CognitoServicesaccepttwokindsof data;App tag data and userAddressbookdata. AppTagdata is the
associationthata usermakesfor a giventgtentityinthe contextof the app. Basedon bothit provides
for a setof services. Ingeneral,if ReportAddressBookTagsisdisabledforamarket;PersonalCallerIdwill
be disabledaswell. However,itispossible forReportAddressBookTagstobe enabledand
PersonalCallerIDtobe disabled,if there are precisionissues.
Url https://phonebook-
int.cloudapp.net/PhonebookService.svc/GetServiceEnabledForMarket
Method GET
BODY Type Application/json
Headers AppId(Mandatory), RequestId(M),
AppVersion(M), AppTicket(0)
ReturnType Json
Return
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 Identiferand
IdentiferValue mustbe
provided.
type Yes string CC Typescan 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/FALSE
Used = TRUE/FALSE
}
BlockedCall :{
UploadAllowed=TRUE/FALSE
Used= TRUE/FALSE
}
BlockedSMS: {
UploadAllowed=TRUE
Used= FALSE

}
AddressBookName :{
UploadAllowed=FALSE
NameUploadAllowed=TRUE/FALSE; insome marketsonlyphone numberswillbe
uploadedtoenable buddydiscoveryandpresence.
Used= FALSE
}
}
Note on ReportTags:If ReportTagsisenabled,thenthe serviceusesTagdata forinferencingpurposes.
If not, thenitdoesn’tuse the tag data. However,tagdata can still be uploadedtoCognitofor
synchronizationpurposes.
TBD: Do we reallyneedto tell the app whetherthe tag will be usedor not used?Or is it an internal
setting. Seemsmore like an internal setting. InternalPolicy
2.2RegisterUserForApp
An applicationusercanregisterwithPhoneBookService if he canbe authenticated. ThisAPIis
idempotent. The Appmustcall it withthe same credentialswhere there isachange of ‘Name’or if
there isa differentaddressbookuploadflagorif the device idchangedorif a new phone numberis
detectedbythe applicationorif the userupdateshisappprofile andaddsthe phone numbertoit. But
valuesthere were providedearlierthatare not changingmustbe providedagain. If the appdetectsthat
the oldphone numberhasbeenreplacedbya new phone numberonthe same device,itis
recommendedthatthe Appcall UnRegisterUser() andthencall RegisterUseragainwiththe new phone
number.
ThisAPImust be calledinorderfor the userto uploadtags to the service orto provide anykindof data
to the service.[TBD: Currentlywe assume that lookupcan be calledwithoutcalling
RegisterUserForApp(),privacywise???]
An Entityiscreated/updatedforagivenuserwiththe appropriate applicationregistrationinformation.
An entitythatiscreatedby callingRegisterUserisalsomarkedas“Registered”. Note thatthe same
entitymaybe registeredbymultiple apps,Cognitorememberseachone independently.
Url https://phonebook-int.cloudapp.net/PhonebookService.svc/RegisterUserForApp
Method POST
Headers AppId(Mandatory), RequestId(M), AuthType (M),PhoneVerificationType(M),
AppVersion(M),Office365AccessToken(Optional), DeviceTicket(0),
If AuthType = MSA, MSAAuthTicketis(M)

If PhoneVerificationType = ABCH, ABCHAuthTicketis(M)
If PhoneVerificationType =MSA,thenMSA signinshouldbe phonenumbersignin
and shouldmatchwithgivenphone number
ReturnType Json
Return
Members
Response Code
Access Points
Test https://phonebook-int.cloudapp.net/PhonebookService.svc/RegisterUserForApp
Production https://www.bing.com/local/PhonebookService.svc/RegisterUserForApp
BodyParameters
userPhoneNumber No string +919999999999 userPhoneNumberis
verifiedatthe time of
registration.If not
provided,aPhone
EntityNode witha PUID
ID iscreated.
Additional Identity
informationwill be
extractedfromthe
ticketandsavedalong
withthisregistration.
Thiswill include the
LoginId(PUID) and
AccountName.
DeviceIDandother
aliasesmaybe
optionallyretrieved
fromthe ticket.
username N string VinaySurana Name of the registering
user.

contactsUploaded Y bool TRUE/FALSE Whetherthisphone
numberownerhad
agreedto upload
contact bookdetails.
deviceId Y string Device IDis validated
againsta device ticketif
present
2.3IsAppRegisteredForUser
Thisreturnsinformationaroundappregistrationsdone incontextof agivenauthenticateduser.
What are the use cases for this API? For now, RegisterUser() isidempotent,sowe don’t feel thisAPI
is required.
An applicationcancheckif the userhas registeredwiththe same app. If the app userprovidesthe same
MSA credentials,the setof registrationsagainstthatusercan be discoveredbythe application.
Needssecure app id. Does not needsecure device idsas that is treated like a parameter. A different
app should not be able to phishfor registrationinformation.
Url https://phonebook-int.cloudapp.net/PhonebookService.svc/IsRegisteredUser
Method POST
If AuthType = MSA, MSAAuthTicketis (M)
If PhoneVerificationType = ABCHVerificationTpe,ABCHAuthTickeris(M)
ReturnType Json
Return
Members
Response Code
Access Points
Test https://phonebook-int.cloudapp.net/PhonebookService.svc/IsAppRegisteredforUser
Production https://phonebook.cloudapp.net/PhonebookService.svc/IsAppRegisteredforUser
BodyParameters

userPhoneNumber No string +919999999999 userPhoneNumberis
optional butwhen
providedisverified.
Appropriate headers
for phone verification
mustbe set.
The MSA identity
informationis extracted
fromthe MSA ticket
deviceID N string nbkhghejgwjhg DeviceID
Response
All existingregistrationsforagivenMSA userwill be returnedinthe response body. A registrationis
identifiedas:
//appuninstalledandreinstalled
 UserAlreadyRegistered:MSA Identity,Phone Numberanddevice IDmatchesexactlywiththe
previousregistration. If phone numberisnotsupplied,the othertwomatchthenthistype is
returnedaswell.
//SIMChangedonthe same device
 UserRegisteredOnDevice:MSA IdentityandDeviceIDmatch,phone numberisdifferent,
whetheritisoptionallyprovidedornot
//SIMmovedtoanotherphone
 UserRegisteredWithSamePhoneNumber:MSA identityandphone numbermatch,device idis
different
//same user,twodevices
 UserRegisteredNoMatch:MSA identitymatch,neitherthe phone numbernorthe device id
match
TBD: Is there a needto return the p
ExistingRegistrations:{
Count:2
List:{
{

Type:UserAlreadyRegistered
UserName: “VinaySurana”
}
{
Type:UserRegisteredWithSamePhoneNumber
//the same appis installedbythisuseronanotherdevice
UserName :“Vinary
}
{
2.4GetRegistrationDataForPhoneNumber
ThisAPIallowsapplicationtoretrievethe appuserregistrationinformation,which wasusedfora prior
app registrationthatwasdone incontextof thisphone number. AuthType ismandatoryandAuthNone
isnot supported. PhoneVerificationMethodismandatory. The phone numberwill be verified. The
data isreturnedonlyif the PUID of the priorregistrationmatches.
int.cloudapp.net/PhonebookService.svc/GetRegistrationDataforPhoneNumber
Method GET
ReturnType Json
Return
Members
Response Code
Access Points
Environmen
t
Service URI
int.cloudapp.net/PhonebookService.svc/GetRegisterationDataForPhoneNumber

Production https://www.bing.com/local/PhonebookService.svc/GetRegistrationDataForPhoneNum
ber
Parameters
userPhoneNumber Y string +919999999999 userPhoneNumberfor
whichregistrationinfo
inrequired
deviceID N string nbkhghejgwjhg DeviceID
contactsUploaded Y bool TRUE/FALSE
Response
The followingjsonisreturnedinthe response body.
PhoneNumberRegistrationInfo:{
username:“SunitaShrivastava”
deviceId :nkhjkshjkhf
contactsUploaded:TRUE/FALSE
}
2.5UploadTags
Tags are attributesthata useron a givendevice canassignto a targetentity. The target entityisusually
a phone number.(willwe supportsendertags?).
ThisAPIis usedto uploadtagsto the Cognitoservice incontextof anapp user. The intentof the
UploadTags() andRetrieve Tagsisto provide asyncservice toapplicationacrossdevicesand
applicationsforthe user. If “ReportTags”isdisabledfora giventagina market(the markettowhichthe
userbelongs),the tagdatafor that tag will notbe acceptedthroughthe UploadTagsAPI. However,the
“Backup/Restore”APIwill be accepted. If ‘”ReportAddressBook”is disabled,the addressbooktagswill
not be accepted.
It isassumedthat the clientkeepsacache of tag data locallyanduploadsonlytags,whichhave changed
since the lastupload. Note thatit is possibleforauser to settags frommultiple devices. A clientkeeps

the local cache insync by applyingthe changeslocallytothe cache if there are changespending,locking
the local cache, doinganUploadTags followedbyaRetrieveTags. Atthispoint,itcanunlockthe cache
for furtherupdates.
Here is the suggestedsequence tosynchronize the local copyof the tags withthatin the CognitoCloud:
{
LockLocalTagsCache
Upload Changed Tags (Use UploadTags(incremental) to upload tags which haven’t been
uploaded)
RetrieveTags
UnlockLocalTagsCache
}
It isrecommendedthatanapp periodicallyperformthissequence tokeepitslocal copyinsync. It is
alsoadvisedthatAppnot try and performthe synchronizationoperationduringanincomingcall but
simplyuse the valuesinthe local cache to avoidlatency issues.
The followingschemaisadvisedforkeepingtrackof the tag data locally. PossiblevaluesforActionare
C(Created),U(Updated),D(Deleted). Once adeletedvalueisuploaded,itcanbe deletedfromthe local
cache.
<TagName,DstPhoneNumber,CurrentTagValue,OldTagValue(?),Action,IsChangeUploaded>
AddressbookName a Special Tag
AddressbookName isaspecial tagwhichcan onlybe onlyuploadedandnotretrieved. Cognitocanuse
these tagsfor inferencingbutisnotresponsibleforsynchronization.Anappshouldmonitorchangesto
the addressbookand uploadthe change incrementally. Forthe multi device case,the seconduploadin
failswithanerror
{
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 false
UnlockNameCache()
}
UploadChangedContacts{

UploadTags(inincremental mode)
}
TagTypes
There are twotypesof tags, publicandread-only. Anappcan seta publictag,if isOK for the app user
to be able to modifythese tagsinthe contextof differentapps. Anappcan seta read-onlytag,if itis
willingforotherappsto read the tags butwouldnotlike otherappsto overwrite the tagsthatthe user
has createdinitscontext. This maybe true for applicationsthatshipnativelyonthe device.
TBD: Shouldwe supportprivate tagsaswell.
Modesof Upload
Two modesof uploadare supported:incremental andsnapshot. The snapshotremovesandreplaces
the cloudtags withthe onesprovidedinthe APIandshouldbe usedwithcaution.
The followingtagnamesare supportedandmaybe uploadedtothe service:
 AddressBookName
 BusinessCategory
 BlockedCall
 BlockedSMS
 SuggestedName
Here are the tag valuesthatare usedfor eachof the above tags.
Tag Name Value
AddressBookName Contact: {
ContactName : SunitaShrivastava(Optional)
Source : Outlook
}
Business Category String(e.g. “Bakery”)
BlockedCall Null (the name suggestedforacallerthatis
blockedissentseparatelywithsuggestedname)
BlockedSMS NULL
SuggestedName suggested_name
Url https://phonebook-int.cloudapp.net/PhonebookService.svc/UploadTags
Method POST

If PhoneVerificationType = ABCHVerificationTpe,ABCHAuthTickeris(M),
Locale(M)
ReturnType Json
Return
Members
ResponseCode(SUCCESSFUL/PARTIAL_SUCCESS/TAG_UPLOAD_FAILED),
ErrorMessage
AccessPoints
Test https://phonebook-int.cloudapp.net/PhonebookService.svc/UploadTags
Production https://www.bing.com/local/PhonebookService.svc/UploadTags
Body
Jsonobjectof the bodyparameters
Body Parameters
userPhoneNumber N string +919999999999 If userPhoneNumberis
provided,itisverified.
tagData No string TagData : [{
TagName:
Mode:
“incremental/snapshot”
{
dstPN:
Action:”Create/Update/Delete”,
UpdateTime:epochTS
TagValue:
}
{
}
}]
If tagdata is empty and
office365AcccessToken
isprovided,thenthe
service will syncthe
contact data fromOffice
and TagData doesn’t
needtobe specified. If
ActionisSnapshot,the
actionis assumedtobe
create. All existingtags
withthat tagName are
deleted.
deviceID Y string "123" Usedfor identificationof
source entity.
marketIdentifier Yes string IN Market Identiferand
IdentiferValue mustbe
provided.

marketIdentifierType Yes string CC Typescan be either
CountryCode (CC),
MobileCountryCode
(MCC),MarketLocale
(Locale)
Sample RequestTag Data Object
{
"TagData" : {
"TagDataItems": [{
"Mode" : "incremental",
"TagList" : [{
"Action": "C",
"UpdateTime":1461311757,
"Value": "",
"dstPN": "9000498404"
}, {
"Action": "D",
"Value": "",
"dstPN": "9000498405"
}
],
"TagName": "BlockedCall"
}, {
"TagList" : [{
"Action": "C",
"Value": "testcat",

"dstPN": "9000498404"
}, {
"Action": "D",
"Value": "spamcat",
"dstPN": "9000498405"
}
],
"TagName": "BusinessCategory"
}, {
"TagList" : [{
"Action": "C",
"Value": "{"ContactName ":"testName
","Source ":"testing"}",
"dstPN": "9000498404"
}, {
"Action": "C",
"Value": "{"ContactName ":"sandeep
","Source ":"testing"}",
"dstPN": "9000498405"
}
],
"TagName": "AddressBookName"
}
]
}

}
Response
------------
1) PARTIAL_SUCCESS
{
"ResponseCode":"PARTIAL_SUCCESS",
"PerTagResponse":[{
"Key": "AddressBookName",
"Value":{
"ErrorMessage": "Addressbookuploadnotsupported:Userpuid#deviceId",
"ResponseCode":"FAILURE_FORBIDDEN"
}
}]
}
2) SUCCESSFUL
{
"ResponseCode":"SUCCESSFUL",
"PerTagResponse":[]
}
3) FAILURE
{
"ResponseCode":"TAG_UPLOAD_FAILED",
"PerTagResponse": [{
"Key": "AddressBookName",
"Value":{
"ErrorMessage": "Addressbookuploadnotsupported:Userpuid#deviceId",
"ResponseCode":"FAILURE_FORBIDDEN"
}

},
{
"Key": "BusinessCategory",
"Value":{
"ErrorMessage": "BusinessCategoryuploadnotsupportedforthismarket",
"ResponseCode":"FAILURE_MKT_NOT_SUPPORTED"
}
}]
}
2.6RetrieveTags
An appusercan queryfora setof tags that emanate fromSource Entitiescorrespondingtohisuser
Identity. Optionally,he cangettags fromSource Entities,forwhichhe hasvalidownershipproof
throughauthentication. E.g.<A2, p1, d1> <A2, p2, d1> registrationswillcreate twodifferentuser
registrations. User,withthe PUID correspondingtoA2, can queryforthe set of tags that emanate from
any of the entitynodes,whichhave amatchingPUID. AuthType NONEwill resultinfailure;the caller
mustbe authenticated.
Url https://phonebook-int.cloudapp.net/PhonebookService.svc/RetrieveTags
Method GET
ReturnType Json
Return
Members
ResponseCode,ErrorMessage,tagData
Access Points
int.cloudapp.net/PhonebookService.svc/RetrieveTags/{tagfilter=All}&
{userPhoneNumber=} & {SrcEntityScope = MatchedPUID}
Production https://www.bing.com/local/PhonebookService.svc/RetrieveTags

Body Parameters
Response
TagData will be returnedas follows:
TagData:{
TagName : Category
TagCount:3
Tags: {
TagValue:“Grocery”
dstPN:
TimeLastModified:
DeviceID:
UserPhoneNumber N string PhoneNumber:
+919999999999
If a Phone Numberis
provided,itmust
verified.
Tagfilter Yes List TagList: {
BlockedSMS,
BlockedCall
}
One or more of the tags
supportedbythe
ontology.Getisnot
supportedonthe
“AddressBookName”
Tag.
AppIDfilter No int Can be setto one of:
MyAppIDOnly
MyAppFamilyOnly
All
The service will filter
tags basedonwhich
appidcontextthey
were setin. If ‘All’is
chosen,thenall public
tags are made available
as well.
dstEntityFilter No List dstList{
PhoneNumber:
SenderName :
}
If specified,thenonly
tags that refertothat
target phone numbers
or sendername are
returned. If thisisnot
specified,the tagsare
not filteredby
destination.

}
{
TagValue :“Electrical Supplies”:
……….dstPN:
TimeListModified:
}
{
TagValue:
}
TagDataFromSrc{
SrcEntity{
}
TagCount:
Tags{
}
Response Format
StandardserverResponse objectforsuccessorfailure.
2.7BackupAppUserData
Backup allowsanapplicationtobackupsome userdata inthe contextof a user.
The main purpose of backupisto be able torestore User data inscenarios
 where the device isresetandappneedstobe reinstalled
 whenthe SIMchangesand userregisterswithanew phone numberonthe same device
 whenthe device islostandthe usermovesthe SIMto a new device andinstallsthe app
 whenthe userinstallsthe apponan additional device
AuthType NONEisnotsupported. An app can have at most 20 data types. Anapp can create at most
10 backupswitha particulardata type in the contextof an app.
A backupis annotatedwith<AppId, PUID,DeviceId,PhoneNumber>. Phone Numberisoptional.
Url https://phonebook-int.cloudapp.net/PhonebookService.svc/BackupAppUserData
Method POST
AppVersion(M), DeviceTicket(0),
ReturnType Json

Return
Members
Basic ResponseCode,ErrorMessage
AccessPoints
Test https://phonebook-int.cloudapp.net/PhonebookService.svc/BackupAppUserData
Production https://www.bing.com/local/PhonebookService.svc/BackupAppUserData
Body
Body Parameters
userPhoneNumber N string +919999999999 If userPhoneNumberis
provided,itisverified.
Also,the backupis
markedas beingsavedin
the contextof thisphone
number.
dataType Y int 4 Thisis opaque toCognito
deviceId Y string The backup ismarked as
beingsavedincontextof
thisdevice 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.8RestoreAppUserData
Appcan call thisto use Restore userspecificapplication datathatwasbackupearlier. Thisisuseful,if an
app isbeinginstalled/enabledonadevice afterreset,movingthe SIMtoanotherdevice ora SIMchange
on the same device.

Reset or Movingthe SIM to another device
Afterreset,the device idmaychange.If the usercontinuestouse the same phone numberasbefore,
the app can retrieve the tagshe had usedbycallingRestoreAppUserData()andprovidingthe same
phone number. If the userhadn’tprovidedaphone number,itwill tryandrestore the app data which
was savedwiththe same PUID:deviceId. If that isnot found,thenitwill restore the userdata,fromthe
same PUID but witha differentdeviceid. If multiplesuchbackupsexist,itwill returnthe mostrecent
one of those.
Installingthe app on a SecondDevice
An appcan getuse thisAPIto restore the userapplicationdataonanotherdevice. RestoreAppUserData
will make acopy of the userdata fromanotherbackup,if one exists,andmake a copyfor the new
device id.
The service keepsamappingof backupsperformedinthe contextof aPUID.
Url https://phonebook-int.cloudapp.net/PhonebookService.svc/RestoreAppUserData
Method POST
AppVersion(M), DeviceTicket(0),
ReturnType Response Code,Json
Return
Members
ResponseCode,Data
AccessPoints
Test https://phonebook-int.cloudapp.net/PhonebookService.svc/RestoreAppUserData
Production https://www.bing.com/local/PhonebookService.svc/RestoreAppUserData
Body
Body Parameters
userPhoneNumber N string +919999999999 If userPhoneNumberisprovided,itis
verified. A backupthat matchesthis

PUID+Phone numberisreturned,if it
exists. Else,abackupwithPUID+DeviceID
match isreturned.
datatype Y int 4 Thisis opaque toCognito. Data type for
whichthe backupshouldbe returned.
deviceId Y string
Response Format
{
“ResponseCode”:“SUCCESSFUL”
“Data” : “jakjjhdjkhsfjkh”
}
{
“ResponseCode”:“FAILURE_NO_BACKUP_FOUND”
“Data” : null
}
2.9 Lookup
Lookupreturnsthe inferredtagsor propertiesforanentity.
AuthType headerisneeded.If AuthTypeisNone youcanonlygetbusinesscallerIdand spamcount
withoutspamname. If AuthType isMSA and an MSA tokenisprovided,youcangetpersonal callerID
assumingphone bookisbeinguploaded(asperuserconsentandregistration).
Each data centerdoesinferencingineachlocale forwhichithas data fora phone number. Italsodoes
locale agnosticinferencing. If locale specificinferencedname are notfound,the locale agnostic
inferencednameswillbe returned.
Url https://phonebook-int.cloudapp.net/PhonebookService.svc/LookUp
Method GET
BODY Type ---
Headers AppId(Mandatory), RequestId(M), AuthType (M),PhoneVerificationType(O),
ReturnType Json
Return
Members
ResponseCode, Entity
AccessPoints

Enviro
nmen
t
Service URI
Test https://phonebook-int.cloudapp.net/PhonebookService.svc/LookUp?
lookUpNumber={Phone}&userPhoneNumber={userPhoneNumber(Optional)}&locale={Local
e(Mandatory)}&marketIdentifierType={MarketIdentifier}&marketIdentifier={MarketValue}
Produ
ction
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&user
PhoneNumber=%2B8613911057528&locale=en-us&marketIdentifierType=MCC&marketIdentifier=405
PhoneNumber=%2B8613911057528&locale=zh-cn&marketIdentifierType=CC&marketIdentifier=CN
PhoneNumber=%2B8613911057528&locale=zh-cn&marketIdentifierType=Locale&marketIdentifier=zh-
cn
WithoutUser Phone Number
https://phonebook-
int.cloudapp.net/PhonebookService.svc/LookUp?lookUpNumber=%2B8613911057528&locale=zh-
cn&marketIdentifierType=Locale&marketIdentifier=zh-cn
Response Format
JsonObjectwithMessage andEntityData(PhoneNumberEntity)
Entity: {
Number:string,Numbergiveninlookup
IsSpam: boolean,whetherthe entityhasbeen inferredtobe Spam
SpamCount:unsignedlong,numberof people markedthisasspam
InferredName:string,the name inferredbycloudservice
RegisteredName:string,the name registeredbyaservice (TBD:Privacy Concern: restrict by app?)
BingName:string,the name forlocal businessesfromBING
BingCategoryName:string,categoryname frombing
City:string,Cityof the user
State:string,State of the user
Country:string,Country of the user
Locality:string,Localityof the USER
InferredCategory:string,Categoryof phone numberif business
CategoryCount:unsignedlong,numberof people choosingthe above inferredcategoryforthis
phone number

LocalBusiness:bool,isthisalocal business
}
Sample Response :
SuccessResponse:
{"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,whetherthe entityhasbeeninferredtobe Spam
entityIdentifier:The entityasidentifiedbythe caller(additional identityisnotrevealed)
SpamCount:unsignedlong,numberof people markedthisasspam
InferredName:string,the name inferredbycloudservice
BingName:string,the name forlocal businessesfromBING
City:string,Cityof the user
Locality:string,Localityof the USER
InferredCategory:string,Categoryof phone numberif business
CategoryCount:
LocalBusiness:bool,isthisalocal business
}
2.10SendFeedbackforLookup
This APIallowsanapp userto indicate thatthe informationreturnedasa part of lookupwasnot
satisfactoryandpropose a newvalue forit. The targetcan be a phone numberora sendertag.
The callerwill be authenticated.
The feedbackisqueuedforevaluationandwill notimpactinferredvaluesinstantaneously. TBD: Do we
want the user to implicitlytag these. Withoutexpiry? Currently the thought is no.
int.cloudapp.net/PhonebookService.svc/SendFeedbackForLookup
Method POST

AppVersion(M), DeviceId (M), Office365AccessToken(Optional),
ReturnType Json
Return
Members
ResponseCode,ErrorMessage
AccessPoints
Test https://phonebook-int.cloudapp.net/PhonebookService.svc/SendFeedbackForLookup
Production https://www.bing.com/local/PhonebookService.svc/SendFeedbackForLookup
Body Parameters
marketIdentifier N string “CN” Market Identifier
Value
marketIdentifierType N String “CC”| “ MCC”| “Locale” Typescan be
CountryCode,
MobileCountryCod
e,MarketLocale
locale Y string “zh-cn” Locale for which
feedbackisgiven
targetId Yes string “123” Entitywhichwas
lookedup. This
can eitherbe a
phone numberof a
sendertag.
entityFeedback Y string {"Comment":"Sampl
e","AttributeSuggestio
ns":[{"AttributeName
":"BingCity","Returne
d":"India","Recomm
ended":"Alto"},{"Att
ributeName":"BingCit
y2","Returned":"Indi
a","Recommended":
"Alto"}]}
Onlyvaluesfor
which
recommendations
are beingmade
needtobe sent.
JsonFormatted
String

Response Format
{"ResponseCode":"SUCCESSFUL"}
Sample Request and Response:
POST https://phonebook-int.cloudapp.net/PhonebookService.svc/SendFeedbackForLookupHTTP/1.1
User-Agent: Fiddler
Host: phonebook-int.cloudapp.net
Content-Length: 317
Content-Type: application/json
AppId: Test
AppVersion: 1.0.32
ClientVersion: 1.0.32
RequestId: 1234567
AuthType: NONE
DeviceId: 1234
{"marketIdentifier":"CN","marketIdentifierType":"CC","locale":"zh-
cn","targetId":"123","entityFeedback":"{"Comment":"Sample","AttributeSuggestions":[{"AttributeName":"BingCity","Returned":"Indi
a","Recommended":"Alto"},{"AttributeName":"BingCity2","Returned":"India","Recommended":"Alto"}]}"}
HTTP/1.1200 OK
Cache-Control: private
Content-Length: 29
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/8.5
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Mon, 25Apr201605:10:24GMT
{"ResponseCode":"SUCCESSFUL"}
2.11 UnRegisterUserForApp
Shouldbe calledbefore uninstall.
An appusercan unregisterfromthe PhoneBookService. MSAAuthType NONEisnotsupportedforthis
API.
int.cloudapp.net/PhonebookService.svc/UnRegisterUserForApp
Method POST
If AuthType = MSA, MSAAuthTicketis(M)
If PhoneVerificationType = ABCH,ABCHAuthTickeris(M)

If PhoneVerificationType =MSA, MSA signinshouldphone numbersame asuser
phone number
ReturnType Json
Return
Members
StandardResonseCode
Body Parameters
userPhoneNumber No string PhoneNumber:+919999999999 As provided
inthe
RegisterUser()
API.
deleteAllData Yes bool TRUE/FALSE If
deleteAllData
istrue,all
uploadedtags
are deleted.
deviceId Yes

Cognito Unified API Specification

Recommandé

Recommandé

Contenu connexe

En vedette

En vedette (18)

Similaire à Cognito Unified API Specification

Similaire à Cognito Unified API Specification (20)

Plus de Sunita Shrivastava

Plus de Sunita Shrivastava (7)

Cognito Unified API Specification