Guest data extension REST API v2 (legacy)
A newer version of this REST API (v2.1) is available. If you're new to the Guest REST API, use the new version. Alternatively, if you're already using the old version, read about the differences between v2 and v2.1 so you can upgrade.
A guest data extension is an array that enables you to specify whatever name/value pairs (attributes) you want. Guest data extensions are optional and enable your organization to capture more robust information about your guests. You can then use the guest data in batch segmentation and view it in the guest profile.
When you create a guest data extension, you send an object of attributes of your choice to Sitecore CDP.
If your organization wants to send all guest data extensions in one request from a single system, use the following endpoint:
POST v2/guests/<guestRef>/extext
The name of the key in the key-value pair becomes a guest data extension. Sitecore CDP then stores the object in the guest profile and makes it available for selection in the batch segmentation UI.
Alternatively, if your organization wants to send guest data extensions from multiple source systems, you must use guest data extension groups to ensure data from other source systems isn't overwritten with each request.
The following is a list of guidelines for using the guest data extension:
-
Place the data extension data in the
extensions
array of objects. -
The
name
attribute must beext
. Or, if you are sending guest extension data from multiple sources, it must beext1
,ext2
,ext3
,ext4
orext5
. -
The
key
attribute must bedefault
. -
A guest data extension has a maximum of 100 attributes.
The following is a list of guidelines for using attributes in the data extension:
-
The attribute name must be alphanumeric [A-Z,a-z,0-9] as per the JSON RFC 7159 specification.
-
You must write the attribute name of the data extension in camel case.
-
The attribute name must be unique.
-
We recommend making the attribute name meaningful.
In this example, loyaltyTier
, rewardBalance
, vipMember
, and loyaltyNumber
become guest data extensions.
curl -X POST '<baseURL>/v2/guests/3bc77f6e-368a-4343-bb75-222f8d5e77a8/extext' \
-u '<username>:<password>' \
-H 'Accept: application/json' \
--data-raw '
{
"key": "default",
"loyaltyTier": "level2",
"rewardBalance": 5012.25,
"vipMember": true,
"loyaltyNumber": 3452
}'
Sending guest extension data from multiple source systems
Your organization can send guest extension data from multiple source systems to Sitecore CDP. You can include a maximum 100 custom attributes in each guest data extension group.
For example, your organization might want to send guest data extensions from a loyalty system to capture loyalty data and a Customer Relationship Management (CRM) system to capture email preferences, alternative mailing addresses, and so on.
To send data from multiple source systems, you must use a different extension group name for each source system. If you do not do this, each time a source system sends guest extension data to Sitecore CDP, it will overwrite guest extension data sent from other source systems. This is because the guest data extension REST API overwrites all the key-value pairs included in the request and deletes any key-values that are not included in the API request.
Your organization can use a maximum of six guest data extension groups. Each group name represents a different source system. You must use the extension group names as follows:
-
ext
-
ext1
-
ext2
-
ext3
-
ext4
-
ext5
You must include the name of the guest data extension group in the endpoint. You do not need to include it in the body of the request.
The following request uses ext2
as the guest data extension group name:
POST
v2/guests/guestRef/extext2
For example, if you want to send data from a loyalty system to Sitecore CDP, your organization must always use the same guest extension group name in the endpoint. Do not use the same guest extension group name to send extensions from other source systems.
Use a consistent prefix in the key name of the key-value pair. This helps users quickly find all guest data extensions from a particular source system in the batch segmentation UI. For example, if you use member
as a prefix, all member
guest data extensions display together in the UI in alphabetical order. This also ensures that you do not overwrite key-value pairs sent from other source systems. For example, a key with number
might exist for a loyalty membership and CRM system.
Users can access guest data extensions in batch segmentation, as shown in the following example:
In this example, memberCardBalance
, memberCardCategory
, and memberCardType
become guest data extensions sent from your orgnaization's loyalty system.
curl -X POST '<baseURL>/v2/guests/3bc77f6e-368a-4343-bb75-222f8d5e77a8/extext2' \
-u '<username>:<password>' \
-H 'Accept: application/json' \
--data-raw '
{
"key": "default",
"memberCardBalance": 8938,
"memberCardCategory": "promoter",
"memberCardType": "platinum"
}'