Managing Guest using Engage REST API in Sitecore CDP – Developer Guide

In real time scenario, when you are working on projects, sometime for testing purpose you might have to perform some actions on the guest profile in Sitecore XM Cloud stored in CDP. In this case, I have found the Engage API becomes very useful to add/update or manage the CDP guest profile using the REST APIs.

Example:

Suppose you are working on some Decision Model which need to return some offer based on some Guest Extension Properties. But in order to put the values under the extension properties you might have to build a complete form to push the values into CDP.

Rather going that path, it would be easier to push the Guest and their properties using Engage API and running the test on Decision Model on the same guest, showing the results and lowering the dependency on other teams.

In this blog, I will show how you can setup the APIs quickly using Postman and run the GUEST REST API using it.

 

Setup API Access Key Token

Before we proceed further you need to create a Client Key and API Token which will serve as username and password in Postman as Basic Authorization. Without this you will not be able to fetch any records

Step 1: Login into XM Cloud portal and go to your CDP Instance

 

 Step 2: Click on Settings icon which could be find at right corner side

Now click on API access.

Step 3: Add New Client Key

Please make sure you have set to Active.

Keep this client key and API token with you, we will use it later.

 

Know your Region

Engage API url consists of the environment or region based on your setup. To find out, go to your cdp instance and click on settings icon on right corner

Click on the Company Information

So the region is AP and based on that, the engage api url should be like below:

 

Exploring the GUEST Engage REST API

Step 1: Setup Authorization in Postman

Setup using Basic Auth and your Client Key is username and API token is your password. 

 

Request 1: Create Guests

Response:

Ref is the guest reference id which is primary value for that particular customer.

Request Type: POST

{

  "guestType": "customer",//visitor

  "channel": "WEB",

  "type": "IDENTITY",//Add in case you want to identifiy the guest

  "language": "EN",

  "firstName": "Arjun",

  "lastName": "Arora",

  "identifiers": [

    {

      "provider": "Mobile",

      "id": "917485485419"

    }

  ],

  "phoneNumbers": ["917485485419"]

}

Lets see what we got in CDP:

Open the guest:

 

Request 2: Create guest extensions

NOTE: please keep a note of PUT and PATCH while operating on extensions.

PUT will remove all the existing extension property for that guest and will keep the ones which you are providing, PATCH will update the values for existing properties values, keeping others as it is.

Request 3: Update Extensions

Note: we are using PATCH here, After Update:

Request 4: Get Guest using Identifiers

You must set the guest as customer if you have any identifier value like mobile or email address. This will allow you to fetch the customer using their provider and id.

Provider => Identifier Name

ID => Value

If you have noticed in the first request, I have use type as Identity, which will trigger Identity event and make the guest known along with identifier.

Request 5: Get Guest using guest ref

Request 6: Get Guest extensions using Guest Ref

 

Request 7: Delete Guest

Summary

In this blog I have shown how you can use the Sitecore Guest REST API to do CRUD operations on guest. This you can use specially when you are simulating the real scenarios based on CDP guest data.

References

https://api-docs.sitecore.com/cdp/guest-rest-api


Comments

Post a Comment

Popular posts from this blog

Working with Device Detection Module in Sitecore

Image
  What is Device Detection in Sitecore? Sitecore has an in-built feature called Device Detection which helps to detect at which device the content is shown into. When I say in-built that means its included as a standard feature in Sitecore XP 9.0 and later. This feature is also present in Sitecore XM Cloud , hence you do not need to buy a separate add-on or module to utilize device detection features.   The information gather from Device Detection Module can help content makers, allowing them to tailor the website experience based on the device type they are accessing it with, such as by displaying different layouts or content depending on screen size and capabilities. For Example, An iPhone and Android users might be looking at different content on same page.   Moreover, developers uses the same mechanism to personalize the components based on the device specific audience. They can setup Device Layout based on specific device parameters or can use the in-built rules...
Read more

Setup A/B Testing in Sitecore - Part 1

Image
  Setup A/B Testing in Sitecore - Part 1 In this article we will understand What is A/B Testing, Types of Testing in Sitecore, Actual Use Case and later we will see how we can setup A/B Testing in Sitecore XP solution with Rendering having different data source items.   Before we go further, lets understand WHAT IS A/B Testing ? A/B testing, also known as split testing, is a method used in marketing and product development to compare two versions of something to determine which one performs better. In an A/B test, two versions, A and B, are created, with one varying element between them. This element could be anything from the wording of an email subject line, the design of a web page, the placement of a button, or even the pricing of a product.   The versions, A and B, are then randomly  shown to similar audiences or users, and their responses are measured and compared. The version that performs better in terms of predefined metrics (such as click-through rate, conv...
Read more

Resolving: Failed to start service Sitecore Marketing Automation Engine Error

Image
  Description: In this blog, I will try to show you that how you can solve the common issue you might face while installing Sitecore 10.4 version XP Single On Premises. Sitecore Download Link: https://developers.sitecore.com/downloads/Sitecore_Experience_Platform/104/Sitecore_Experience_Platform_104 During installation of Sitecore 10.4 on my new device I got below error:   Misconceptions : Since the installation gets interrupted and we get only one option to close the Sitecore Install Assistance tool, The common mis conception arises while re-installing the Sitecore is that should I provide new Solr service name again? And/or should I provide new Sitecore instance name? The answer is NO . You can simply skip Install Solr Service Step: Then on next window provide the same Sitecore prefix or instance name which you provided earlier: Sitecore will override new files on previously created folders or services. Point to remember: Before you re-start you...
Read more