Microsoft D365 Customer Service - Integration Document

Written By Devin O'Neill ()

Updated at April 16th, 2025

Introduction 

Annex Cloud’s integration with Microsoft D365 Customer Service enables availability of customer loyalty data, which will assist Customer Service Rep to Customer Service aims to help users deliver excellent, personalized customer service to their customers, at any time, on any channel. 

Purpose 

This document explains the key steps and processes followed for integrating Annex Cloud’s Loyalty Program with Microsoft D365 Customer Service. 

Integration Flow 

Revision History

Version  Date  Description
1.0  19th Aug 2021  Included Screenshots & Steps of Integration.

Prerequisites for Installation 

  • Client Name: Microsoft 
  • Site ID: XXXXXX // Annex cloud will provide your site id.
  • Access Token: XXXXXXX 

Steps to creating an Access token: 

  • Step 1: Create JSON array with Loyalty Token and Site id.
  • Step 2: Encode with function of base64_encdoe ().

Configuration Steps 

Steps of creating Iframe in D365 

  1. Log in to D365 Power App. 
  2. Click the setting icon, in the top right corner. 
  3. Click on Advanced Settings.
  4. Click the Setting dropdown and select Customizations.
  5. Click on Customize the System.
  6. Click on Entities.
  7. Click Contact and Open Forms and select Annex Cloud Customer Service.
  8. Click on Annex Loyalty Info Tab.
  9. Click on Insert Tab and Select Iframe as shown in the above image.

10. Fill in the information on Iframe and Click the Ok button.

Create JavaScript Library for Iframe 

Steps for Creating JavaScript Library for Iframe 

  1. Log in to D365 Power App. 
  2. Click the setting icon, in the top right corner. 
  3. Click on Advanced Settings.
  4. Click the Setting dropdown and select Customizations.
  5. Click on Customize the System.
  6. Click on Entities.
  7. Click Contact and Open Forms and select Annex Cloud Customer Service.
  8. Click on Annex Loyalty Info Tab.
  9. Click on Form Properties.
  10. Click Add button for the new library.
  11. Click the New button on the Lookup Record page.
  12. Fill inthe information on the Web Resource form and click Text Editor.
  13. In the EditContent form, add the below JavaScript code, and click the Ok button. function 
    annexLoyalty_info(executionContext)
    {
    var formContext = executionContext.getFormContext();
    var value = formContext.getAttribute("emailaddress1").getValue(); var fname = formContext.getAttribute("firstname").getValue();
    var lname = formContext.getAttribute("lastname").getValue(); var user_info = {"firstName":fname,"lastName":lname};
    var user_info_encode = btoa(JSON.stringify(user_info)); var newTarget = "";
    switch (value) { case 100000001:
    newTarget = "https://api.socialannex.com/msdservice/v3/getUserAcHistory.php"; break;
    default:
    newTarget = "https://api.socialannex.com/msdservice/v3/getUserAcHistory.php"; break;
    }
    var IFrame = Xrm.Page.ui.controls.get("IFRAME_test_iframe_vi"); var Url = IFrame.getSrc();
    var params = Url.substr(Url.indexOf("?"));
    newTarget = newTarget + '?token=XXXAnnex cloud will provide you&externalID='+value+'&pageid=1&userinfo='+user_info_encode+''; IFrame.setSrc(newTarget);
    }
  14. On Web Resource Form. Click on Save and Publish buttons.
  15. Select the Created Library, the Lookup Record form, and click on the Add button.
  16. Select the Created library from the Event List’s Form Libraries.
  17. The Event Handlers section selects the Iframe which we have created, and the Event will auto-select, then click Add button.
  18. Handler Properties form, Select the JavaScript Library which we have created on a web resource and write a JavaScript Function name in, Function Input Field. Click the Checkbox of Pass execution context as the first parameter, and click the Ok button.
  19. Save and Publish, and check the form changes on the Customer Service Hub page.
  20. Open the Power app page, and select the Customer Service Hub page.
  21. Click on Contacts.
  22. Click any contact and view the records.
  23. Click the Annex Loyalty Info tab and the loyalty information.

List of APIs/Data Push/Setting up Trigger

List of APIs used for Loyalty Dashboard

  1. Join Loyalty Button

API: https://s15.socialannex.net/api/3.0/users Method- POST

Request Object: Not Blank

Function Location In Extension: ANNEXCLOUDV3SERVICE

Input Param- customer (EMAIL OR ID), AnnexCloudModel (Site details), status (YES, NO)

Request:

Method URL
POST /users
Parameter Parameter Description Parameter Type

id (Mandatory) email firstName lastName optInStatus

status phone birthdate createDate

anniversaryDate

userProfileImage Url

extendedAttribute

Enter the user’s unique id. Enter the user’s email address. Enter the user’s first name.

Enter the user’s last name.

Pass the opt-in status as YES for opt-in and NO for opt-out. By default, it will be YES.

Pass the user status as active (default) or inactive

Enter the user’s phone number. Enter the user’s birth date.

Enter the create date of the user

Enter the anniversary date, which can be either birth date or loyalty program joining date.

Enter the user’s profile image url

Enter the attribute keys and their values apart from the ones which are mentioned above. (According to client’s request)

string string string string string

string

string

date (yyyy-mm-dd) date (yyyy-mm-dd) date (yyyy-mm-dd)

string string

Sample Request:

{
"id": "user@domain.com", "email": "user@domain.com", "firstName": "John",
"lastName": "Doe",
"zipCode": "90002", "optInStatus": "YES", "status": "ACTIVE", "phone": ""123-123-4567",
"birthDate": "2018-04-01T00:00:00-0700",
"anniversaryDate": "2018-04-01T00:00:00-0700", "userProfileImageUrl":
"https://www.socialannex.com/public/manageoptionsdesign16/images/product_landing/loyalty-
hover.png",
"createDate": "2018-04-01T00:00:00-0700", "updateDate": "2018-04-01T00:00:00-0700",
"extendedAttribute": ["KEY1": "VALUE1", "KEY2": "VALUE2"]
}

Response:

This will create a user and opt-in that user for the loyalty program and will return the details which include username, opt-in status, phone, birthdate, anniversary date, etc.

Output fields:

  • id: Return the unique id.
  • email: Returns the email address of the user.
  • firstName: Returns the first name of the user.
  • lastName: Returns the last name of the user.
  • optInStatus: Return the opt-in status of the user.
  • status: Returns the status of the user if the user is active or inactive. By default, it will be active and can be changed to inactive if the client requests.
  • phone: Returns the phone number of the user.
  • birthDate: Returns the birthdate of the user in yyyyMM-dd'T'HH:mm:ssZ format.
  • anniversaryDate: Returns the anniversary date of the user in yyyyMM-dd'T'HH:mm:ssZ format.
  • userProfileImageUrl: Returns the url of the user’s profile image only if this parameter is
  • passed while creating the user.
  • createDate: Returns the date & time in yyyyMM-dd'T'HH:mm:ssZ format in which the user was created.
  • updateDate: Returns the date & time in yyyyMM-dd'T'HH:mm:ssZ format on which the user was updated.
  • extendedAttribute: Displays the extra user attributes which are added as per the client’s
  • request.
  • errorCode: Display only when the API request fails. This will denote the type of error.
  • errorMessage : Displays the reason why the API request has failed.

Sample Positive Response:

Status code Response
200

An example of a positive response is:

{ "id": "user@domain.com", "email": "user@domain.com", "firstName": "John",

"lastName": "Doe",

"zipCode": "90002", "optInStatus": "YES", "status": "ACTIVE", "phone": ""123-123-4567",

"birthDate": "2018-04-01T00:00:00-0700",

"anniversaryDate": "2018-04-01T00:00:00-0700",

"userProfileImageUrl": "https://www.socialannex.com/public/manageoptionsdesign16/images/pr oduct_landing/loyalty-hover.png",

"createDate": "2018-04-01T00:00:00-0700", "updateDate": "2018-04-01T00:00:00-0700",

"extendedAttribute": ["KEY1": "VALUE1", "KEY2": "VALUE2"]}

Sample Error Response:

Status code Response
AC1002

An example of an error response is:

{ "errorCode": "AC1001",

"errorMessage": "Oops! Something went wrong." }

  • Info Tab

This API is used to fetch the details of the user.

Method URL
GET /users/{id}

Sample Request:

/users/user@domain.com

Response:

This will return all the details of the user.

Output fields:

  • id: Returns a unique identifier (in the SA system) used to identify the user.
  • email: Returns the email address of the user.
  • firstName: Displays the first name of the user.
  • lastName: Displays the last name of the user.
  • zipCode: Displays the zip code of the user’s location.
  • status: Returns the status of the user if the user is active or inactive. By default, it will be active and can be changed to inactive if the client requests.
  • phone: Displays the phone number of the user.
  • birthDate: Displays the birthdate of the user in yyyyMM-dd'T'HH:mm:ssZ format.
  • anniversaryDate: Displays the anniversary date of the user in yyyyMM-dd'T'HH:mm:ssZ format.
  • userProfileImageUrl: Returns the url of the user’s profile image. If this field is not passed
  • while creating the user, then this field’s response will be blank.
  • createDate: Displays the date on which the user is created in yyyyMM-dd'T'HH:mm:ssZ format.
  • updateDate: Displays the date on which the user details are updated in yyyyMM- dd'T'HH:mm:ssZ format.
  • totalSpendCurrency: Displays the total currency spent by the user.
  • extendedAttribute: Displays the extra user attributes which will vary according to the client.
  • errorCode: Display only when the API request fails. This will denote the type of error.
  • errorMessage: Displays the reason why the API request has failed.

Sample Positive Response:

Status code Response
200

An example of a positive response is:

{

"id": "user@domain.com",
 

"email": "user@domain.com",
 

"firstName": "John",

"lastName": "Doe",

"zipCode": "90002",

"optInStatus": "YES",

"status": "ACTIVE",

"phone": "123-123-4567",

"birthDate": "2018-04-01T00:00:00-0700",

"anniversaryDate": "2018-04-01T00:00:00-0700", "userProfileImageUrl":

"https://www.socialannex.com/public/manageoptionsdesi gn16/images/product_landing/loyalty-hover.png",

"createDate": "2018-04-01T00:00:00-0700", "updateDate": "2018-04-01T00:00:00-0700",

"totalSpendCurrency": "150",

"extendedAttribute": ["KEY1": "VALUE1", "KEY2": "VALUE2"]

}

Sample Error Response:

Status code Response
AC1002 / AC1005

An example of an error response is:

{

"errorCode": "AC1002",

"errorMessage": "Request Not Authorized"

}

If data is not found!!

{

"errorCode": "AC1005", "errorMessage": "No data found"

}

  • Subscribe to Newsletter

This API is used to update the user details.

API: https://s15.socialannex.net/api/3.0/users/{id} Method- PATCH

Request Object: Not Blank

Function Location in Extension: ANNEXCLOUDV3SERVICE

Input Param: customer (EMAIL OR ID)

Method URL
PATCH /users/{id}
Parameter Parameter Description Parameter Type

email updateId firstName lastName optInStatus

status

phone birthdate

createDate

anniversaryDate

userProfileImageUrl extendedAttribute

Enter the user’s email address. Pass the user’s new email address. Enter the user’s first name.

Enter the user’s last name.

Pass the opt-in status as YES for opt-in and NO for opt-out. By default, it will be YES.

Pass the user status as active (default) or inactive

Enter the user’s phone number.

Enter the user’s birthdate.

Enter the create date of the user

Enter the anniversary date, which can be either birthdate or a loyalty program joining date.

Enter the user’s profile image URL.

Enter the attribute keys and their values apart from the ones which are mentioned above (according to the client’s request).

string string string string string

string

string

date (yyyy-mm- dd)

date (yyyy-mm- dd)

date (yyyy-mm- dd)

string string

Sample Request:

{
"id": "user@domain.com",
"updateId": "user_1@domain.com"
"email": "user@domain.com",
"firstName": "John",
"lastName": "Doe",
"zipCode": "90002",
"optInStatus": "YES",
"status": "ACTIVE",
"phone": ""123-123-4567",
"birthDate": "2018-04-01T00:00:00-0700",
"anniversaryDate": "2018-04-01T00:00:00-0700",
"userProfileImageUrl": "https://www.socialannex.com/public/manageoptionsdesign16/images/prod uct_landing/loyalty-hover.png",
"createDate": "2018-04-01T00:00:00-0700",
"updateDate": "2018-04-01T00:00:00-0700",
"extendedAttribute": ["NewsLetterOptIn ": "YES"]
}

Response:

This will update the details of the user.

Output fields:

  • id: Returns a unique identifier (in the SA system) used to identify the user.
  • email: Returns the email address of the user.
  • firstName: Displays the first name of the user.
  • lastName: Displays the last name of the user.
  • zipCode: Displays the zip code of the user’s location.
  • status: Returns the status of the user if the user is active or inactive. By default, it will be active and can be changed to inactive if the client requests.
  • phone: Displays the phone number of the user.
  • birthDate: Displays the birthdate of the user in yyyyMM-dd'T'HH:mm:ssZ format.
  • anniversaryDate: Displays the anniversary date of the user in yyyyMM-dd'T'HH:mm:ssZ format.
  • userProfileImageUrl: Returns the url of the user’s profile image.
  • createDate: Displays the date on which the user is created in yyyyMM-dd'T'HH:mm:ssZ format.
  • updateDate: Displays the date on which the user details are updated in yyyyMM- dd'T'HH:mm:ssZ format.
  • extendedAttribute: Displays extra user attributes which will vary according to the client.
  • errorCode: Display only when the API request fails. This will denote the type of error.
  • errorMessage: Displays the reason why the API request has failed.

Sample Positive Response:

Status code Response
200

An example of a positive response is:

{

"id": "user_1@domain.com", "email": "user_1@domain.com", "firstName": "John",

"lastName": "Doe",

"zipCode": "90002", "optInStatus": "YES", "status": "ACTIVE",

"phone": "123-123-4567",

"birthDate": "2018-04-01T00:00:00-0700",

"anniversaryDate": "2018-04-01T00:00:00-0700", "userProfileImageUrl":

"https://www.socialannex.com/public/manageoptionsdesi gn16/images/product_landing/loyalty-hover.png",

"createDate": "2018-04-01T00:00:00-0700",

"updateDate": "2018-04-01T00:00:00-0700",

"extendedAttribute": [["NewsLetterOptIn ": "YES"]

}

Sample Error Response:

Status code Response
AC1002

An example of error response is:

{

"errorCode": "AC1002",

"errorMessage": "Request Not Authorized"

}

  • Manage Tier:

This API is used to update the user Tier.

API- https://s15.socialannex.net/api/3.0/users/{id} Method- PATCH

Request Object- Not Blank

Function Location In Extension- ANNEXCLOUDV3SERVICE Input Param- customer (EMAIL OR ID)

Method URL
PATCH /users/{id}
Parameter Parameter Description Parameter Type
email updateId firstName Enter the user’s email address. Pass the user’s new email address. Enter the user’s first name. string string string

lastName optInStatus

status

phone birthdate

createDate

anniversaryDate

userProfileImageUrl extendedAttribute

Enter the user’s last name.

Pass the opt-in status as YES for opt-in and NO for opt-out. By default, it will be YES.

Pass the user status as active (default) or inactive

Enter the user’s phone number. Enter the user’s birth date.

Enter the create date of the user

Enter the anniversary date, which can be either birthdate or a loyalty program joining date.

Enter the user’s profile image URL

Enter the attribute keys and their values apart from the ones which are mentioned above. (According to client’s request)

string string

string

string

date (yyyy-mm- dd)

date (yyyy-mm- dd)

date (yyyy-mm- dd)

string string

Sample Request:

{
"id": "user@domain.com",
"updateId": "user_1@domain.com"
"email": "user@domain.com",
"firstName": "John",
"lastName": "Doe",
"zipCode": "90002",
"optInStatus": "YES",
"status": "ACTIVE",
"phone": ""123-123-4567",
"birthDate": "2018-04-01T00:00:00-0700",
"anniversaryDate": "2018-04-01T00:00:00-0700",
"userProfileImageUrl": "https://www.socialannex.com/public/manageoptionsdesign16/images/prod uct_landing/loyalty-hover.png",
"createDate": "2018-04-01T00:00:00-0700",
"updateDate": "2018-04-01T00:00:00-0700",
"extendedAttribute": ["UserTier ": "Platinum"]
}

Response:

This will update the details of the user.

Output fields:

  • id: Returns a unique identifier (in the SA system) used to identify the user.
  • email: Returns the email address of the user.
  • firstName: Displays the first name of the user.
  • lastName: Displays the last name of the user.
  • zipCode: Displays the zip code of the user’s location.
  • status: Returns the status of the user if the user is active or inactive. By default, it will be active and can be changed to inactive if the client requests.
  • phone: Displays the phone number of the user.
  • birthDate: Displays the birthdate of the user in yyyyMM-dd'T'HH:mm:ssZ format.
  • anniversaryDate: Displays the anniversary date of the user in yyyyMM-dd'T'HH:mm:ssZ format.
  • userProfileImageUrl: Returns the url of the user’s profile image.
  • createDate: Displays the date on which the user is created in yyyyMM-dd'T'HH:mm:ssZ format.
  • updateDate: Displays the date on which the user details are updated in yyyyMM- dd'T'HH:mm:ssZ format.
  • extendedAttribute: Displays extra user attributes which will vary according to the client.
  • errorCode: Display only when the API request fails. This will denote the type of error.
  • errorMessage: Displays the reason why the API request has failed.

Sample Positive Response:

Status code Response
200

An example of a positive response is:

{

"id": "user_1@domain.com",
 

"email": "user_1@domain.com",
 

"firstName": "John",

"lastName": "Doe",

"zipCode": "90002",

"optInStatus": "YES",

"status": "ACTIVE",

"phone": "123-123-4567",

"birthDate": "2018-04-01T00:00:00-0700",

"anniversaryDate": "2018-04-01T00:00:00-0700", "userProfileImageUrl":

"https://www.socialannex.com/public/manageoptionsdesi gn16/images/product_landing/loyalty-hover.png",

"createDate": "2018-04-01T00:00:00-0700",

"updateDate": "2018-04-01T00:00:00-0700",

"extendedAttribute": ["UserTier ": "Platinum"]

}

Sample Error Response:

Status code Response
AC1002

An example of an error response is:

{

"errorCode": "AC1002",

"errorMessag

Freeze User Account

This API is used to block user accounts and domains.

  • API- https://s15.socialannex.net/api/3.0/blocklist Method- POST
  • Request Object-: Not Blank
  • Function Location In Extension: ANNEXCLOUDV3SERVICE
  • Input Param: customer (EMAIL OR ID)
Method URL
POST /blocklist
Parameter Parameter Description Parameter Type

blockedBy (Mandatory)

blocklistDomains

blocklistUsers

Enter the user email id who is going to add users, domains, or both into the blocklist.

Enter the list of domains that need to be added to the blocklist.

Enter the list of domains that need to be added to the blocklist.

String String String

Sample Request:

{
"blocklistDomains":
"xyz.co.in, qwe, 1234, werzz.com, adssdsadsa12345.com,
qwerty.in, abc.co.uk, loremy.com, domain.in, ak.com, domain.co.in",
"blocklistUsers":"testUsr@lorem.com, testUsr@lorema.com, testUsr@loremb.com,covid@19.com, amitdomain1.com,
user1234",
blockedBy":amit.wade@immply.com
}

Response:

If no users or domains already exist.

Output fields:

  • userBlocklistedData: Displays the list of users who are requested and added to the blocklist.
  • newlyAddedUserIntoBlocklist: Displays the list of users who are newly added to the blocklist.
  • domainBlocklistedData: Displays the list of domains that are requested and added to the blocklist.
  • newlyAddedDomainIntoBlocklist: Displays the list of domains that are newly added to the blocklist.
  • inValidDomain: Displays invalid domains from the requested list.

Sample Positive Response:

Status code Response
201

An example of a positive response is:

{

"userBlocklistedData": { "newlyAddedUserIntoBlocklist": [

"testUsr@lorem.com, testUsr@lorema.com, testUsr@loremb.com, covid@19.com, amitdomain1.com, user1234"

]

},

"domainBlocklistedData": {

"newlyAddedDomainIntoBlocklist": [

"xyz.co.in, werzz.com, adssdsadsa12345.com, qwerty.in, abc.co.uk, loremy.com, domain.in, ak.com, domain.co.in"

],

"inValidDomain": [ "qwe, 1234"

]

},

"blockedBy": "amit.wade@immply.com"
 

}

Sample Error Response:

Status code Response
AC1001

An example of error response is:

{

"errorCode": "AC1001",

"errorMessage": "Oops! Something went wrong."

}

Response:

If users or a domain already exists.

Output fields:

  • userBlocklistedData: Displays the list of users who are requested and added to the blocklist.
  • newlyAddedUserIntoBlocklist: Displays the list of users who are newly added to the blocklist.
  • domainBlocklistedData: Displays the list of domains that are requested and added to the blocklist.
  • newlyAddedDomainIntoBlocklist: Displays the list of domains that are newly added to the blocklist.
  • inValidDomain: Displays invalid domains from the requested list.

Sample Positive Response:

Status code Response
201

An example of a positive response is:

{

"userBlocklistedData":

"alreadyBlocklistedUser": [

"testUsr@lorem.com, testUsr@lorema.com,
 

testUsr@loremb.com, covid@19.com,
 

amitdomain1.com, user1234"

]

},

"domainBlocklistedData": {

"alreadyBlocklistedDomain": [

"xyz.co.in, werzz.com, adssdsadsa12345.com,

qwerty.in, abc.co.uk, loremy.com, domain.in,

ak.com, domain.co.in"

],

"inValidDomain": [

"qwe, 1234"

]

},

"blockedBy": "amit.wade@immply.com"
 

}

Sample Error Response:

Status code Response
AC1001

An example of error response is:

{

"errorCode": "AC1001",

"errorMessage": "Oops! Something went wrong."

}

  • Unfreeze User Account:

This API is used to unblock user accounts and domains.

  • API: https://s15.socialannex.net/api/3.0/blocklistdelete
  • Method: POST
  • Request Object: Not Blank
  • Function Location In Extension: ANNEXCLOUDV3SERVICE
  • Input Param: customer (EMAIL OR ID)
Method URL
POST /blocklistdelete
Parameter Parameter Description Parameter Type

deleteBlocklistDomains

deleteBlocklistUsers orderDetail

Enter the list of domains that need to be deleted from the blocklist.

Enter the list of users they need to delete from the blocklist

String 
String

Sample Request/payload:

{
"deleteBlocklistDomains":
"xyz.co.in,
1234, asdf, werzz.com,
adssdsadsa12345.com, qwerty.in, abc.co.uk,
loremy.com, domain.in,
ak.com, domain.co.in",
"deleteBlocklistUsers":
"testUsr@lorem.com,
testUsr@lorema.com,
testUsr@loremb.com,
covid@19.com,
amitdomain1.com"
}

Response:

This will display requested users or domains or both data for deleting from the blocklist.

Output fields:

  • deletedUserData: Displays deleted user’s data from the blocklist is requested by the user.
  • userNotExistedInBlocklist: Displays users which have not existed in the blocklist requested by the user.
  • deletedDomainData: Displays deleted domain data from the blocklist which is requested by the user.
  • domainNotExistedInBlocklist: Displays domains that have not existed in the blocklist requested by the user.

Sample Positive Response:

Status code Response
201

An example of a positive response is:

{

"deletedUserData": {

"deletedUserFromBlocklist": [

"testUsr@lorem.com, testUsr@lorema.com,
 

testUsr@loremb.com, covid@19.com,
 

amitdomain1.com"

]

},

"deletedDomainData":

{

"deletedDomainFromBlocklist": [ "loremy.com, ak.com"

],

"domainNotExistedInBlocklist": [

"xyz.co.in, 1234, asdf, werzz.com,

adssdsadsa12345.com, qwerty.in, abc.co.uk,

domain.in, domain.co.in"

]

}

}

  • Earn Tab

This API is used to get the status of all the actions against a particular user.

Method URL
POST /actions
Parameter Parameter Description Parameter Type
id (mandatory) Pass the user’s unique id string

Sample Request:

{
"id":"joyroy.sa@gmail.com",
}

Response:

This will return the action-wise status of the user.

Output fields:

  • actionId: Displays the unique action id.
  • actionName: Displays the name of the action.
  • actionPoints: Displays the number of points that can be earned by performing this action.
  • maxPoints: Displays the number of maximum points that can be earned by performing this action.
  • period: Displays the period of the action.
  • ratio: Displays the ratio of the action.
  • status: Displays the status of the action whether it is active or not.
  • expireInDays: Displays the number of days after which the action will expire.
  • holdDays: Displays the number of days points would be on hold.
  • actionPerformStatus: Displays the status to be complete/ incomplete of the action performed
  • actionNameDisplay: Displays the display name of the action.
  • actionLimitDisplay: Displays the action limit.
  • requiredCount: Displays the required action count.
  • completedCount: Displays the completed action count.
  • pendingCount: Displays the pending action count.
  • actionLimitReachedFlag: Displays the updated status flag when it reaches the action limit.
  • actionLimitReachedStatus: Displays the remaining time to earn points if the action limit is reached
  • createDate: Displays the date on which the action is created.
  • updateDate: Displays the date on which the action is updated.
  • pages: Display the total number of pages. (This parameter will be displayed for multiple action details).
  • currentPage: Displays the current page number. (This parameter will be displayed for multiple action details).
  • errorCode: Displays only when the API request fails. This will denote the type of error.
  • errorMessage: Displays the reason why the API request has failed.

Sample Positive Response:

Status code Response
201

An example of a positive response is:

{

"allActionDetails": [

{

"actionId": "987",

"actionName": "Test 1",

"actionPoints": "20",

"maxPoints": "40",

"period": "70",

"ratio": "30",

"status": "ACTIVE",

"expireInDays": "0",

"holdDays": "50",

"actionPerformStatus": "0",

"actionNameDisplay": "10",

"actionLimitDisplay": "188",

"requiredCount": "2",

"completedCount": "2",

"pendingCount": "0",

"actionLimitReachedFlag": "1",

"actionLimitReachedStatus": "Limit

reached. Points can be earned in the next 20 days",

"createDate": "2019-12-12T10:12:54+0000",

"updateDate": "2019-12-12T10:15:16+0000"

},

{

"actionId": "114",

"actionName": "Twitter Share",

"actionPoints": "20",

"maxPoints": "100",

"period": "0",

"ratio": "0",

"status": "ACTIVE",

"expireInDays": "0",

"holdDays": "0",

"actionPerformStatus": "0",

"actionNameDisplay": "inner display",

"actionLimitDisplay": "",

"requiredCount": "5",

"completedCount": "0",

"pendingCount": "5",

"actionLimitReachedFlag": "0",

"actionLimitReachedStatus": "",

"createDate": "2019-08-31T13:19:29+0000",

"updateDate": "2020-01-25T09:42:51+0000"

}

}

Sample Error Response:

Status code Response
AC1002

An example of an error response is:

{

"errorCode": "AC1002",

"errorMessage": "Request Not Authorized"

}

Method URL
GET /users/{id}/reward

Sample Request:

/users/user@domain.com/reward

Response:

This will return an array containing all the eligible rewards of the specific user.

Output fields:

  • creditsToCurrencyRatio: Displays the points to currency ratio.
  • creditsToCurrencyValue: Displays the converted value of credits to currency according to the ratio.
  • rewardDetails: It will return an array of all loyalty rewards, with the following parameters:
    • rewardId: Returns the specific reward id.
    • rewardCategory: Returns the reward category.
    • displayText: Returns the reward display text.
    • creditRequired: Returns the credit (points) required to redeem that reward.
    • eligible: Returns 0 if the user is eligible to redeem the reward, else returns 1.
    • rewardUrl: Returns the reward url.
    • rewardImageUrl: Returns the image url of the reward.
    • productId: Returns the product id.
  • errorCode: Displays only when the API request fails. This will denote the type of error.
  • errorMessage: Displays the reason why the API request has failed.

Sample Positive Response:

Status code Response
200

An example of a positive response is:

{

"creditsToCurrencyRatio":"0.05", "creditsToCurrencyValue":5, "rewardDetail": [

{

"rewardId": "111", "rewardCategory": "", "displayText": "$5 off gift card", "creditRequired": "500", "eligible":"1",

"rewardUrl":"www.example.com/reward", "rewardImageUrl":"www.example.com/example.png"

},

{

"rewardId": "112", "rewardCategory": "", "displayText": "XYZ product", "creditRequired": "1000", "eligible":"0",

"rewardUrl":"www.example.com/reward", "rewardImageUrl":"www.example.com/example.png", "productId": "P1"

}

]

}

Sample Error Response:

Status code Response
AC1002 / AC1005

An example of an error response is:

{

"errorCode": "AC1002",

"errorMessage": "Request Not Authorized"

}

If data is not found!!

{

"errorCode": "AC1005", "errorMessage": "No data found"

}

Request:

Method URL
GET /users/{id}/usedreward

Sample Request for All actions details:

/users/user@domain.com/usedreward

Response:

This will return the details of the rewards used by the customer.

Output fields:

  • rewardCode: Displays the reward code.
  • pointsUsed: Displays the points used to redeem that reward.
  • rewardName: Displays the name of the reward.
  • rewardStatus: Displays the status of the reward.
  • reason: Displays the reason.
  • createDate: Displays the date on which the reward is claimed.
  • pages: Display the total number of pages.
  • currentPage: Displays the current page number.
  • errorCode: Displays only when the API request fails. This will denote the type of error.
  • errorMessage: Displays the reason why the API request has failed.

Sample Positive Response:

Status code Response
200

An example of a positive response is:

{

"rewardDetail": [

{

"rewardCode": "Code001",

"pointsUsed": "100",

"rewardName": "$5 coupon",

"rewardStatus": "Claimed", "reason": "",

"createDate": "2019-06-10T06:22:58+0000"

},

{

"rewardCode": "Code002",

"pointsUsed": "200",

"rewardName": "$10 Reward",

"rewardStatus": "Claimed",

"reason": "",

"createDate": "2019-06-10T07:22:54+0000"

}

],

"pages": 1,

Sample Error Response:

Status code Response
AC1002

An example of an error response is:

{

"errorCode": "AC1002",

"errorMessage": "Request Not Authorized"

}

  • Activity Tab:

This API is used to fetch the details of all the activities performed by the user, including the points debited/credited from the account.

Request:

Method URL
GET /users/{id}/activity

Sample Request:

/users/user@domain.com/activity

Response:

This will return an array of all activities performed by the user. This includes activity name, activity date, points balanced till that activity, order id (will be returned only for purchase activities) & redemption amount.

Output fields:

  • activityDetail: Returns an array of all activity details in the following fields.
  • actionId: Returns a unique action identifier (in the SA system) used to identify a user action/event.
  • rewardId: Returns a unique reward identifier (in the SA system) used to identify the reward.
  • activity: Returns the name of the activity.
  • credit/debit: Return the number of points credited or debited from the user's account.
  • displayText: Returns the display text of the activity.
  • createDate: Returns the date at yyyy-mm-dd & time on which the points are awarded to the user.
  • expireDate: Returns the date in yyyy-mm-dd & time on which the points will expire.
  • pointStatus: Displays the point status as Hold, Redeemed, Release, etc.
  • holdPointReleaseDate(yyyymm-dd): Displays the date on which it will be released
  • pages: Displays the number of pages present in the user activity response. Every page will contain 10 activities performed by the user. If there are more than 10 activities, then the response will be more than 1 page.
  • currentPage: Displays the current page number. If there are 2 pages of response, then to access the response on the 2nd page, pass the following URL:

http://s15.socialannex.net/api/3.0/users/user@domain.com/activity?page=2

  • errorCode: Display only when the API request fails. This will denote the type of error.
  • errorMessage: Displays the reason why the API request has failed.

Sample Positive Response:

Status code Response
200

An example of a positive response is:

 

 

{

"activityDetail": [

{

"actionId": "105",

"activity": "CREDIT",

"credit": "100",

"displayText": "Join Rewards Program",

"createDate": "2018-08-08T07:35:01+0000",

"expireDate": "2019-08-08T23:59:59+0000"

},

{

"rewardId": "24",

"activity": "DEBIT",

"debit": "100",

"displayText": "$5 coupon",

"createDate": "2018-08-08T07:55:30+0000"

},

{

"actionId": "100",

"activity": "CREDIT",

"credit": "100",

"pointStatus": "Released",

"displayText": "Manual Credit/Debit",

"createDate": "2019-04-23T12:14:29+0000",

"expireDate": "2019-08-08T23:59:59+0000"

},

{

"actionId": "109",

"activity": "CREDIT",

"credit": "50",

"pointStatus": "Released",

"displayText": "Purchase", "orderId": "TESTORDER04",

"createDate": "2018-08-13T05:48:46+0000", "expireDate": "2019-08-15T23:59:59+0000"

},

{

"actionId": "109",

"activity": "CREDIT",

"credit": "50",

"pointStatus": "Hold", // "Released", "Redeem" , "Return", "Cancel", "Custom deduction

"displayText": "Purchase",

"orderId": "TESTORDER04",

"createDate": "2018-08-13T05:48:46+0000",

"expireDate": "2019-08-15T23:59:59+0000",

"holdPointsReleaseDate": "2018-08-13T05:48:46+0000"

}

],

"pages": 1,

"currentPage": 1

Sample Error Response:

Status code Response
AC1002

An example of an error response is:

{

"errorCode": "AC1002",

"errorMessage": "Request Not Authorized"

}

  • Manage Points

This API is used to give, redeem, and award loyalty points to the user.

Method URL
POST /points

To give points:

Parameter Parameter Description Parameter Type

id (Mandatory)

actionId (Mandatory)

activity (Mandatory)

orderId (optional)

reason

Enter the user’s unique id.

Enter the action id (it is mandatory if the action id is set at the site admin).

Enter the activity as CREDIT or DEBIT. If the activity is DEBIT,

pass the order id

Enter the reason for adding or removing the points. (If the actionId is not passed then the reason is mandatory)

string

string

string

string

string

To redeem points:

Parameter Parameter Description Parameter Type

id (Mandatory)

rewardId (Mandatory)

activity (Mandatory)

orderId (optional)

reason

source (optional)

Enter the user’s unique id.

Enter the reward id (it is mandatory if the reward id is set at the site admin).

Enter the activity as CREDIT or DEBIT

If the activity is DEBIT.

pass the order id

Enter the reason for adding or removing the points (If the rewardId is not passed then the reason is mandatory)

Enter the source as web or store.

string

string

string

string

string

string

To redeem customs points:

Parameter Parameter Description Parameter Type

id (Mandatory)

activity (Mandatory)

orderId (optional)

debit (Mandatory)

reason (mandatory)

source (optional)

Enter the user’s unique id.

Enter the activity as DEBIT

If the activity is DEBIT,

pass the order id.

Displays the number of debit points.

Enter the reason for adding or removing the points.

Enter the source as web or store.

string

string

string

string

string

string

To award/deduct custom points:

Parameter Parameter Description Parameter Type

id (Mandatory)

actionId (Mandatory)

activity (Mandatory)

orderId (optional)

credit/debit (Mandatory)

reason

Enter the user’s unique id.

Enter the action id. (it is mandatory if the action id is set at the site admin)

Enter the activity as CREDIT or DEBIT If the activity is DEBIT,

pass the order id

Enter the number of credited/debited points

Enter the reason for adding or removing the points (If the actionId is not passed then the reason is mandatory)

string

string

string

string

string

string

Sample Request:

To give points:

{
"id": "user@domain.com",
"actionId": "100", "activity": "CREDIT", "reason": "aj Bonus", "credit": “50”
}

  • To redeem points:

{
"id": "user@domain.com",
"rewardId": "111",
"activity": "DEBIT",
"orderId": "OD001",
"reason":"claim"
"source":"web"
}

  • To redeem customs points:

{
"id": "user@domain.com",
"activity": "DEBIT",
"orderId": "OD001",
"debit": "500", "reason":"used for purchase" "source":"web"
}

  • To award customs points:

{
"id": "user@domain.com",
"actionId": "100", "activity": "CREDIT", "credit": "50",
"reason":"bonus"
}

  • To deduct customs points:

{
"id": "user@domain.com",
"actionId": "100",
"activity": "DEBIT",
"orderId": "OD001",
"debit": "50", "reason":"adjustment"
}

Response:

This will return a successful response with the details of the points that are added/redeemed.

from the user’s account.

Output fields:

  • id: Displays the unique customer id.
  • actionId: Return the particular action id.
  • activity: Displays action like credit or debit.
  • credit: Displays the number of points credited in the user's account.
  • pointsAwarded: Displays the number of points awarded.
  • updatedUserTier: Returns the updated user tier after the points are awarded/removed.
  • updatedAvailablePoints: Displays the number of updated available points.
  • updatedLifetimePoints: Displays the number of updated lifetime points.
  • updatedUserTier: Displays the updated user tier.
  • releaseDate: Displays the release date in yyyymm-dd format on which the hold points will be released.
  • reason: Displays the reason for adding or removing the points.
  • errorCode: Displays only when the API request fails. This will denote the type of error.
  • errorMessage: Displays the reason why the API request has failed.

Sample Positive Response:

Status code Response
200

An example of a positive response is:

Give points response:

{

"id": "johan28.sa@gmial.com",
 

"actionId": 100,

"activity": "CREDIT",

"credit": 50,

"pointsAwarded": 50,

"reason": "aj Bonus",

"updatedUserTier": "Gold",

"updatedAvailablePoints": "7561",

"updatedLifetimePoints": "7561"

}

Redeem points response:

{

"id": "user@domain.com",

"rewardId": "111",

"activity": "DEBIT",

"orderId": "OD001",

"debit": "500",

"reason":"claim",

"updatedUserTier": "Gold",

"updatedAvailablePoints": "4545",

"updatedLifetimePoints": "7860"

}

Redeem custom points response:

{

"id": "user@domain.com",
 

"activity": "DEBIT",

"orderId": "OD001",

"debit": "500",

"reason":"used for purchase",

"updatedUserTier": "Gold",

"updatedAvailablePoints": "4545",

"updatedLifetimePoints": "7860"

}

Add custom points response:

{

"id": "user@domain.com",
 

"actionId": "100",

"activity": "CREDIT",

"credit": "50",

"reason":"bonus",

"updatedUserTier": "Gold",

"updatedAvailablePoints": "4545",

"updatedLifetimePoints": "7860"

}

Deduct custom points response:

{

"id": "user@domain.com",
 

"actionId": "100",

"activity": "DEBIT",

"orderId": "OD001",

"debit": "50",

"reason":"adjustment",

"updatedUserTier": "Gold",

"updatedAvailablePoints": "4545",

"updatedLifetimePoints": "7860"

}

Sample Error Response:

Status code Response
AC1002

An example of an error response is:

{

"errorCode": "AC1002",

"errorMessage": "Request Not Authorized"

}

Instructions for Resolving Run-Time Errors

Issue 1st: After creating Iframe, you need to fetch the Iframe URL and need to the dynamic as per our Token, User Email ID, First Name, and Last Name. So, I have found that code on MSD365 documentation and changed it as per our requirements. The code and steps are below:

 
 
 
 
 
 
 
 

  1. Click Annex Loyalty Info Tab.
  2. Click Form Properties.
  3. Click Add button for a new library.
  4. Click the New button on the Lookup Record page.
  5. Fill in the information on the Web Resource form and click Text Editor.
  6. In Edit, Content form add the below JavaScript code and click the Ok button. function 
    annexLoyalty_info(executionContext)

{
var formContext = executionContext.getFormContext();
var value = formContext.getAttribute("emailaddress1").getValue(); var fname = formContext.getAttribute("firstname").getValue();
var lname = formContext.getAttribute("lastname").getValue();
var user_info = {"firstName":fname,"lastName":lname}; var user_info_encode = btoa(JSON.stringify(user_info));
var newTarget = ""; switch (value) {
case 100000001:
newTarget = "https://api.socialannex.com/msdservice/v3/getUserAcHistory.php"; break;
default:
newTarget = "https://api.socialannex.com/msdservice/v3/getUserAcHistory.php"; break;
}
var IFrame = Xrm.Page.ui.controls.get("IFRAME_test_iframe_vi"); var Url = IFrame.getSrc();
var params = Url.substr(Url.indexOf("?"));
newTarget = newTarget + '?token=XXXAnnex Cloud will provide you&externalID='+value+'&pageid=1&userinfo='+user_info_encode+'';
IFrame.setSrc(newTarget);
}

  1. On Web Resource Form, Click Save and Click Publish buttons.
  2. Select the Created Library from the Lookup Record form and click on Add button.
  3. Select the Created library from the Event List’s Form Libraries.
  4. The Event Handlers section selects the Iframe which we have created, and the Event will auto-select and Click on Add button.
  5. Handler Properties form Select the JavaScript Library which we have created on web resource and write a JavaScript Function name in the Function Input Field OK and Click the Checkbox of Pass execution context as the first parameter and Click Ok button.
  6. Sava and Publish. And check the form changes on the Customer Service Hub page.

System and Security Requirements

NA

Appendix

NA

List of definitions (Abbreviations)

NA

Response Codes

NA