Introduction

Annex Cloud provides an integrated customer loyalty platform, designed to tackle complex challenges related to customer acquisition, retention, and advocacy. The platform utilizes advanced solutions and a dedicated team of customer success managers to help businesses develop customer loyalty and generate impactful user-generated content. The platform can be used both individually and as a part of a broader suite to create authentic relationships with customers.

Purpose

This document serves as a guide to facilitate the integration of CRM data so that customer representatives can easily access information to answer client queries. It outlines instructions for CRM data push and provides a set of instructions to follow for integrating loyalty program data.

High-Level Design

The integration is designed to seamlessly connect the loyalty program with CRM systems, enabling customer service teams to access and manage loyalty-related data effectively.

Revision History

Prerequisites for Installation

• Client Name: Zoho CRM
• Site ID: XXXXXX (Annex Cloud will provide)
• Access Token: XXXXXXX (Annex Cloud will provide)

Steps to Create Annex Cloud Loyalty Access Token

1. Create a JSON array with the loyalty token and site ID:
   {"site_id": "XXXXXX” (Annex Cloud will provide), "loyaltyToken": "XXXXXXX” (Annex Cloud will provide)} 
2. Encode the JSON using the base64_encode() function.

Loyalty Program Version

Annex Cloud - Loyalty V3 API 3.0.0

• Sign in to the Sigma Account:
  Log in to the provided sigma account for Zoho integration.
  • URL: https://sigma.Zoho.com
  • Username: XXXXXXXX (Provided by the client for their sandbox environment)
  • Password: XXXXXXXX (Provided by the client for their sandbox environment)
    
• Create a new extension for Zoho CRM contacts.
• Click on the New Extension button and select the extension type for the Zoho CRM contact module.
  
• Fill in extension details.
  
• Once the extension is created, click Save as Draft to store the extension setup.
• Now we can see the created extension for Zoho CRM. 
  

Edit Extension for Loyalty Information:

• Click Edit Extension to modify the extension for displaying loyalty program details.
• After clicking on the Edit Extension button, a new tab opens for Zoho Developer. 
  

Create a Button for Loyalty Information:

• Under the Components tab, create a button to show loyalty information on Zoho CRM contact pages.
  
• Click on the Links and Buttons tab and click on Create New Button.
  
• Fill in the button info for Contact module and click on Save button. 
  
  

Using Dynamic Variables in URL for Button

To create a URL for the button, use Dynamic Variables, which can be found in the Fields drop-down box. Follow these steps:

1. Select the variable you need.
2. Click on the option to insert it into the URL.

Example URL:

https://api.socialannexuat.com/zoho/v3/getUserAcHistory.php?token=XXXXXXXXXXXXXXXXX&externalID=${Contacts. Email}&pageid=1&firstName=${Contacts. First Name}&lastName=${Contacts. Last Name}

As mentioned above, refer to #access token to create an access token.

• Once this is done, the button for the contact page will be created.
  

Publish the Changes:

• Click the Publish button, located in the left sidebar at the bottom
  
  
• Once published, check the changes in the components. For example, write a comment and click the Confirm button to confirm your changes.
  
• A pop-up will appear with a URL. Copy the URL and click OK.
  
• Test the URL:
  • Paste the copied URL into a new browser tab and press Enter.
  • You should see a screen with checkboxes. Select the checkboxes and click the Continue to Upgrade button.
    
• Select the radio button, Install for all users, and click the Confirm button.
  
• After this, you’ll see a confirmation screen.
  
• Verify the Contact Page:
  • Click the Main Contact Tab.
    
• Open any contact’s page.
  
• Click the AC Loyalty Info button to see the loyalty iFrame in a new tab, which will display the Annex Cloud loyalty info dashboard.
  
  

Steps for Creating an Authorization Code

To generate an authorization code, follow these steps:

• Use the URL provided below to create an authorization code.

https://www.Zoho.com/crm/developer/docs/api/v2.1/scopes.html

• This URL is linked to the web-based client type in the Annex Cloud account.

https://api-console.Zoho.com/client/1000.CV2ZVA76I5MPMVV3ZTGWNQ0J7U93XG

• The following details will be available after setup:
  • Client ID
  • Client Secret Key
    
• Ensure to select all Multi DC settings.
  
• Authorization Code URL:

https://accounts.Zoho.com/oauth/v2/auth?response_type=code&client_id=1000.CV2ZVA76I5MPMVV3ZTGWNQ0J7U93XG&scope=ZohoCRM.modules.contacts.CREATE,ZohoCRM.modules.contacts.READ,ZohoCRM.modules.contacts.UPDATE,ZohoCRM.modules.contacts.DELETE&redirect_uri=https://api.socialannexuat.com/zoho/connect.php&access_type=offline 

Add the required parameters below to the above URL.

• Response_type 
• Client_id 
• Scope 
• Redirect_uri 
• Access_type 
• Paste the URL into a new browser tab and select the Production Annex Cloud radio button. Click Submit.

• After submitting, you will see a new screen. Click the Accept button.
  
• Get the Authorization Code:

Copy the authorization code from the URL.

Generating Access and Refresh Tokens Using Postman

1. Generate Access Token and Refresh Token:
   Use the authorization code and other details in Postman to generate the access token and refresh token.
2. Use the Access Token in the Contact Add API:
3. Test the acess token by using it in the contact add API and check the response.
   

Use Cases for the Loyalty Program Integration with Zoho CRM

Enroll a Customer in the Loyalty Program

• Support agents can enroll a customer in the loyalty program directly from Zoho CRM.
  
• A customer account must exist in Zoho CRM.
• The customer should not already be enrolled in theloyalty program. 

Check if a Customer is Enrolled in the Loyalty Program

A support agent can check if a customer is part of the loyalty program by reviewing the Annex Cloud Loyalty Section within Zoho CRM.

• A customer account must exist in Zoho CRM.
• Annex Cloud loyalty must be integrated with Zoho CRM.

Award Loyalty Points Upon Opting-in a Customer to the Loyalty Program

• Upon enrolling a customer into the loyalty program, the system automatically awards loyalty points based on predefined criteria or actions.
  

View Customer’s Loyalty Membership Details

• Support agents can view the customer’s loyalty membership details, including the loyalty user and membership information, in the loyalty dashboard’s information tab. The dashboard displays:
  1. Loyalty Membership Info
  2. Earn Tab
  3. Claimed Rewards
  4. Loyalty Activity

Manage Loyalty Points

Support agents can manage the loyalty points of enrolled customers. This includes adjusting point balances, awarding points for specific actions, and reviewing point redemption activity.

Integration Flow

The integration flow diagram, High level design mentioned at the beginning of this document, will depict how Annex Cloud communicates with Zoho CRM, facilitating data exchange and providing the necessary functionality for the customer service representatives to manage loyalty program data effectively.

Installation Steps at the Platform

1. Staging Path: The platform's staging environment is used for testing the integration before moving to production.
2. Production Path: After successful testing, the integration is moved to the production environment

Installation of Loyalty Program

List of APIs/Data Push/Trigger Setup

API Methods:

Several methods are used to push data from Annex Cloud to Zoho CRM, such as:

Installation of Loyalty Program

List of APIs/Data Push/Trigger Setup

API Methods:

Several methods are used to push data from Annex Cloud to Zoho CRM, such as:

Add or Update Contact($dataArray):

This method updates or adds customer contact details.

{ 
  "data": [ 
  { 
 "Company": "Zylker", 
"Last_Name": "Daly", 
"First_Name": "Paul", 
"Email": "p.daly4@zylker.com", 
 "State": "Texas" 
}, 
{ 
"Company": "Villa Margarita", 
"Last_Name": "Dolan", 
"First_Name": "Brian", 
"Email": "brian4@villa.com", 
"State": "Texas" 
 } 
], 
"duplicate_check_fields": [ 
"Email" 
], 
"trigger":[ "workflow"] 
} 

This API setup helps ensure the data is correctly pushed from Annex Cloud into the Zoho CRM, keeping the CRM data updated with loyalty program information.

Get Lists($dataArray)

Retrieves a list of contacts.

$dataArray = [ 
"getList" => "Yes" 
]; 

Delete Contact($dataArray)

$dataArray = [ 
"userDetails" => [ 
"data" => [ 
[ 
"id" => "5134112000000627003" 
] 
] 
] 
]; 

Below is the list of APIs which are used to push data AC to Zoho CRM: 

Add or Update Contact

API Endpoint:
https://www.zohoapis.com/crm/v2.1/Contacts/upsert

Method: POST

Content-Type: application/json

Authorization:
Zoho OAuth Token:
Zoho-oauthtoken1000.e1b3c6b28e930222958e8d969088d0ea.3b99d934893b3e779a203f6cbea4445f
(Note: The authorization key is refreshed each time the API is used.)

Request Body : 

{ 
  "data": [ 
  { 
 "Company": "Zylker", 
"Last_Name": "Daly", 
"First_Name": "Paul", 
"Email": "p.daly4@zylker.com", 
 "State": "Texas" 
}, 
{ 
"Company": "Villa Margarita", 
"Last_Name": "Dolan", 
"First_Name": "Brian", 
"Email": "brian4@villa.com", 
"State": "Texas" 
 } 
], 
"duplicate_check_fields": [ 
"Email" 
], 
"trigger":[ "workflow"] 
}

Response:

 "data": [ 
        { 
            "code": "SUCCESS", 
            "duplicate_field": "Email", 
            "action": "update", 
            "details": { 
                "Modified_Time": "2022-03-17T12:34:52+05:30", 
                "Modified_By": { 
                   "name": "Dhananjay D Waghchaure ", 
                    "id": "5134112000000348001" 
                }, 
                "Created_Time": "2022-02-23T14:32:01+05:30", 
                "id": "5134112000000596010", 
                "Created_By": { 
                    "name": "Dhananjay D Waghchaure ", 
                    "id": "5134112000000348001" 
                } 
            }, 
            "message": "record updated", 
            "status": "success" 
        }, 
        { 
            "code": "SUCCESS", 
            "duplicate_field": "Email", 
            "action": "update", 
            "details": { 
                "Modified_Time": "2022-03-17T12:34:52+05:30", 
                "Modified_By": { 
                    "name": "Dhananjay D Waghchaure ", 
                    "id": "5134112000000348001" 
                }, 
                "Created_Time": "2022-02-23T14:32:01+05:30", 
                "id": "5134112000000596011", 
                "Created_By": { 
                    "name": "Dhananjay D Waghchaure ", 
                    "id": "5134112000000348001" 
                } 
            }, 
            "message": "record updated", 
            "status": "success" 
        } 
    ] 
} 

Get Contact Lists

• API Endpoint:
  https://www.zohoapis.com/crm/v2.1/Contacts
• Method: GET
• Authorization:
  Zoho OAuth Token:
  Zoho-oauthtoken1000.e1b3c6b28e930222958e8d969088d0ea.3b99d934893b3e779a203f6cbea4445f
  (Note: The authorization key is refreshed each time the API is used.)

Response:

{ 
    "data": [ 
        { 
            "code": "SUCCESS", 
            "duplicate_field": "Email", 
            "action": "update", 
            "details": { 
                "Modified_Time": "2022-03-17T12:34:52+05:30", 
                "Modified_By": { 
                    "name": "Dhananjay D Waghchaure ", 
                    "id": "5134112000000348001" 
                }, 
                "Created_Time": "2022-02-23T14:32:01+05:30", 
                "id": "5134112000000596010", 
                "Created_By": { 
                    "name": "Dhananjay D Waghchaure ", 
                    "id": "5134112000000348001" 
                } 
            }, 
            "message": "record updated", 
            "status": "success" 
        }, 
        { 
            "code": "SUCCESS", 
            "duplicate_field": "Email", 
            "action": "update", 
            "details": { 
                "Modified_Time": "2022-03-17T12:34:52+05:30", 
                "Modified_By": { 
                    "name": "Dhananjay D Waghchaure ", 
                    "id": "5134112000000348001" 
                }, 
                "Created_Time": "2022-02-23T14:32:01+05:30", 
                "id": "5134112000000596011", 
                "Created_By": { 
                    "name": "Dhananjay D Waghchaure ", 
                    "id": "5134112000000348001" 
                } 
          }, 
            "message": "record updated", 
            "status": "success" 
        } 
    ] 
}

Delete Contact

• API Endpoint:
  https://www.zohoapis.com/crm/v2.1/Contacts?ids=5134112000000611001
• Method: POST
• Content-Type: application/json
• Authorization:
  Zoho OAuth Token:
  Zoho-oauthtoken1000.e1b3c6b28e930222958e8d969088d0ea.3b99d934893b3e779a203f6cbea4445f
  (Note: The authorization key is refreshed each time the API is used.)

Response: 

{ 
    "data": [ 
        { 
            "code": "SUCCESS", 
            "details": { 
                "id": "5134112000000716001" 
            }, 
            "message": "record deleted", 
            "status": "success" 
        } 
    ] 
}

APIs for iFrame Operations

Join Loyalty Program (Button)

• API Endpoint:
  https://s15.socialannex.net/api/3.0/users
• Method: POST
• Request Object: Not blank
• Function Location in Extension: ANNEXCLOUDV3SERVICE
• Input Parameters:
  • Customer: Email or User ID
  • AnnexCloudModel: Site details
  • Status: YES or NO
    This API will create a member and opt them into the loyalty program. It will display member details such as the name, opt-in status, phone number, birthdate, anniversary date, and so on.

Request: 

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 member and opt in that member for the loyalty program and will display the details which include member name, opt in status, phone, birthdate, anniversary date, and so on.

Output Fields: 

Sample Positive Response: 

Sample Error Response: 

Info Tab (Fetch Member Details)

• API Endpoint:
  https://s15.socialannex.net/api/3.0/users/{id}
• Method: GET
• Request Object: Not blank
• Function Location in Extension: ANNEXCLOUDV3SERVICE
• Input Parameter:
  • Customer: Email or User ID
    This API fetches details about the member.

Sample Request: 

/users/user@domain.com 

Response: 

This will display all the details of the member. 

Output Fields:

Sample Positive Response: 

Sample Error Response: 

Subscribe to Newsletter

• API Endpoint:
  https://s15.socialannex.net/api/3.0/users/{id}
• Method: PATCH
• Request Object: Not blank
• Function Location in Extension: ANNEXCLOUDV3SERVICE
• Input Parameter:
  • Customer: Email or User ID.
    This API updates the member's details to subscribe them to the newsletter.

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/product_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 member. 

Output Fields: 

Sample Positive Response: 

Sample Error Response: 

.

Manage User Tier

• Purpose: This API updates the member’s tier.
• API Endpoint: https://s15.socialannex.net/api/3.0/users/{id}
• Method: PATCH
• Request Object: Not blank
• Function Location in Extension: ANNEXCLOUDV3SERVICE
• Input Parameter: Customer (Email or ID)

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/product_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 member. 

Output fields: 

Sample Positive Response: 

Sample Error Response:

Freeze User Account

• Purpose: This method is used to block user IDs and domains, contributing to enhanced security and control measures.
• API Endpoint: https://s15.socialannex.net/api/3.0/blocklist
• Method: POST
• Request Object: Not blank
• Function Location in Extension: ANNEXCLOUDV3SERVICE
• Input Parameter: Customer (Email or ID)

Sample Request: 

{ 
"blocklistDomains": 
"
example.co.in, example.com, 
example.in,  
exampledomains.com
 
", 
"blocklistUsers":"testUsr@lorem.com, 
testUsr@lorema.com, 
testUsr@loremb.com,covid@19.com,  
amitdomain1.com, 
user1234", 
blockedBy":amit.wade@immply.com 
} 

Response: 

If no members or domain already exists. 

Output Fields: 

Sample Positive Response: 

Sample Error Response: 

Response: 

If members or domains already exist. 

Output Fields: 

Sample Positive Response: 

Sample Error Response: 

Unfreeze User Account

• Purpose: This method is used for removing user IDs and domains from the Blocklist on the Annex Cloud site.
• API Endpoint: https://s15.socialannex.net/api/3.0/blocklistdelete
• Method: POST
• Request Object: Not blank
• Function Location in Extension: ANNEXCLOUDV3SERVICE
• Input Param

Sample Request/payload: eter: Customer (Email or ID)

{ 
"deleteBlocklistDomains": 
"
example.co.in, example.com, 
example.in,  
exampledomains.com
", 
"blocklistUsers":"testUsr@lorem.com, 
testUsr@lorema.com, 
", 
"deleteBlocklistUsers": 
"testUsr@lorem.com, 
testUsr@lorema.com,  
testUsr@loremb.com,  
covid@19.com,  
amitdomain1.com" 
} 

Response: 

This will displays requested members or domains or both data for deleting from blocklist. 

Output Fields:

Sample Positive Response: 

",  
example.co.in, example.com, 
example.in,  
exampledomains.com
", 
"blocklistUsers":"testUsr@lorem.com, 
testUsr@lorema.com, 

Earn Tab

• Purpose: This API retrieves the status of all actions performed by a particular member.
• API Endpoint: https://s15.socialannex.net/api/3.0/actions
• Method: POST
• Request Object: Not blank
• Function Location in Extension: ANNEXCLOUDV3SERVICE
• Input Parameter: Customer (Email or ID)

Sample Request:

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

Response: 

This will display the action-wise status of the member.

Output Fields: 

Sample Positive Response:

Sample Error Response: 

Manage Reward Tab

• Purpose: This API fetches the reward information for a member.
• API Endpoint: https://s15.socialannex.net/api/3.0/users/{id}/reward
• Method: GET
• Request Object: Not blank
• Function Location in Extension: ANNEXCLOUDV3SERVICE
• Input Parameter: Customer (Email or ID)

Sample Request: 

Response: 

This will display an array containing all the eligible rewards of the specific member. 

Output Fields: 

Sample Positive Response: 

Sample Error Response: 

Claimed Reward

• Purpose: This API displays details of all rewards claimed by the member.
• API Endpoint: https://s15.socialannex.net/api/3.0/users/{id}/usedreward
• Method: GET
• Request Object: Not blank
• Function Location in Extension: ANNEXCLOUDV3SERVICE
• Input Parameter: Customer (Email or ID)

Request: 

Sample Request for All Actions Details: 

Response: 

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

Output Fields: 

Sample Positive Response: 

Sample Error Response: 

• Purpose: This API retrieves the details of all activities performed by the member, including points debited or credited to their account.
• API Endpoint: https://s15.socialannex.net/api/3.0/users/{id}/activity
• Method: GET
• Request Object: Not blank
• Function Location in Extension: ANNEXCLOUDV3SERVICE
• Input Parameter: Customer (Email or ID)

Request: 

Sample Request: 

Response: 

This will display an array of all activities performed by the member. Which includes activity name, activity date, points balanced till that activity, order ID(will be displayed only for purchase activities) and redemption amount.

Output Fields: 

 Sample Positive Response: 

Sample Error Response: 

Manage Points

• Purpose: This API allows you to give, redeem, or award loyalty points to the member.
• API Endpoint: https://s15.socialannex.net/api/3.0/points
• Method: POST
• Request Object: Not blank
• Function Location in Extension: ANNEXCLOUDV3SERVICE
• Input Parameter: Customer (Email or ID)

To give points:

To redeem points: 

To redeem custom points: 

To award or deduct custom points:

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 custom points: 

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

To award custom points: 

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

To deduct custom points: 

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

Response: 

This will display a success response with the details of the points that are added or redeemed from the member’s account.

Output Fields: 

Sample Positive Response: 

Sample Error Response: 

Response Codes