Guest data extension REST API v2 (legacy)

Important

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 be ext. Or, if you are sending guest extension data from multiple sources, it must be ext1, ext2, ext3, ext4 or ext5.
The key attribute must be default.
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.

RequestResponse

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.

Warning

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:

POSTv2/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.

Note

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:

Accessing guest data extensions in batch segmentation

In this example, memberCardBalance, memberCardCategory, and memberCardType become guest data extensions sent from your orgnaization's loyalty system.

RequestResponse

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"
}'

Do you have some feedback for us?

If you have suggestions for improving this article,