Sitecore CDP Guest REST API (v2.1)

Creates a data extension for a guest. You can create up to six data extensions.

To avoid creating key-value pairs in a data extension that already exist within a guest profile, first retrieve a guest's collection of data extensions to check that the keys you intend to create are unique.

Creating the request body

In the request body, you must provide one object. This object represents the data extension. Note the following about the object:

• Can contain primitive values only. You cannot nest objects. If you need to group key-value pairs, use prefixes for the key names.
• Can contain a maximum of 100 key-value pairs.
• Must contain the name key. This is the name of the data extension.
  • If you send extension data from one source, set the value for name to ext.
  • If you send extension data from multiple sources, you can create up to six data extensions by setting the value for name to one of the following: ext, ext1, ext2, ext3, ext4, ext5.
• The other key-value pairs you include in the object become the extension data. For example, if you include "loyaltyTier": "level2" in the object, Loyalty Tier with the value of level2 becomes extension data.
• Supported data types for the values:
  • string, for example "level2"
  • boolean, for example true
  • integer, for example 9
  • floating-point number, for example 99.9

Naming keys

The keys you enter in the request body must be:

• Alphanumeric [A-Z,a-z,0-9] as per the JSON RFC 7159 specification.
• In camel case.
• Unique across all data extensions within a guest profile. For example, if ext contains the vipMember key, you must not use that key in any other data extensions for the same guest.

Example request body

Here's an example request body:

{
"name": "ext",
"vipMember": true,
"loyaltyTier": "level2",
"rewardBalance": 5012.25,
"loyaltyNumber": 3452
}

This creates four key-value pairs in the ext data extension for the guest.

Multiple sources

You can send extension data from multiple sources. For example, your organization might want to send extension data both from a loyalty system to capture loyalty data, and from a Customer Relationship Management (CRM) system to capture email preferences, alternative mailing addresses, and so on.

To send data from multiple sources, we recommend that you use a different data extension name for each source system. For example, use the ext data extension for the loyalty system data, and use the ext1 data extension for the CRM data.

Retrieves the URLs for each of the guest's data extensions.

We recommend that you retrieve the URLs using the expand=true query parameter to check that the keys you intend to create when you Create a data extension are unique. This is because keys must be unique across all data extensions within a guest profile.

In the response, each URL in items.href corresponds to one data extension. Use this URL to interact with the guest's data extension, for example, to retrieve or update it.

Retrieves a data extension for a guest.

Fully updates a data extension for a guest, replacing the entire resource including all the key-value pairs with the data you send in the request.

To update certain key-value pairs only, use the Partially update a data extension endpoint instead.

Partially updates a data extension for a guest, replacing only those key-value pairs in the resource that you provide in the request.

If multiple source systems use the same data extension, use this endpoint to safely update the key-value pairs from a specific source system without accidentally overwriting the key-value pairs from other source systems.

Deletes the data extension for a guest, including all the key-value pairs in the data extension.

To delete certain key-value pairs only, use the Delete key-value pairs from a data extension endpoint instead.

Deletes the key-value pairs you provide in the name query parameter from a data extension for a guest.

For example, if your data extension contains the vipMember and loyaltyMember keys, you can delete both keys and their values by making the following request:

{baseURL}/v2.1/guests/{guestRef}/extensions/{dataExtensionName}/fields?name=vipMember|loyaltyMember

If you don't provide the query parameter, this operation will empty the data extension: the data extension itself will not be deleted, but all the key-value pairs in it will.