Sitecore CDP Guest REST API (v2.1)

Use the Guest REST API to create, retrieve, update, and delete guest data in Sitecore CDP.

This REST API lets you interact with:

  • The guest object. The guest object is the core entity of Sitecore CDP. It stores the personal data of a customer, and all relevant transactional and behavioral data is linked in a guest profile.
  • The guest data extension object. A guest data extension is an object that lets you specify any key-value pairs you want. Guest data extensions are optional and enable your organization to capture more robust information about your guests.

After capturing guest information, Sitecore CDP users can:

Note the following:

  • To use this REST API, you must authenticate your API requests.
  • All API requests are made in your production environment.
  • This reference documentation describes Sitecore CDP functionality for data model 2.1.

For more information, see the official Sitecore CDP developer documentation.

Authentication

The Guest REST API uses basic authentication.

Basic authentication involves sending a user name and a password with every request.

To find your user name and password, in Sitecore CDP, on the navigation pane, click Settings > API access:

  • The user name is the Client key.
  • The password is the API token.

You must include the user name and password in every request you make. For example:

curl -X GET '{baseURL}/v2/guests' \
-u '{YOUR_USERNAME}:{YOUR_PASSWORD}' \
-H 'Accept: application/json'


Download OpenAPI description
Overview
License Apache 2.0
Languages
Servers
Production server AP
https://api-engage-ap.sitecorecloud.io/
Production server EU
https://api-engage-eu.sitecorecloud.io/
Production server JP
https://api-engage-jpe.sitecorecloud.io/
Production server US
https://api-engage-us.sitecorecloud.io/

Guest

The guest object is the core entity of Sitecore CDP. It stores the personal data of a customer, and all relevant transactional and behavioral data is linked in a guest profile.

To get started with this API, create a guest then find it in Sitecore CDP.

Operations

Guest data extension

A guest data extension is an object that lets you specify any key-value pairs you want. Guest data extensions are optional and enable your organization to capture more robust information about your guests.

To get started with this API, create a data extension for the guest you previously created, then find the data in Sitecore CDP in the guest profile.

Operations

Create a data extension

Request

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.

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.

Path
guestRefstringrequired

The guest reference. This is a unique identifier of the guest record. If you don't know the guest reference, first retrieve guests.

Example: f7aabbca-1c1b-4fc2-be72-3e16294a4f03
Bodyapplication/json
namestringrequired

The name of the data extension.

Enum"ext""ext1""ext2""ext3""ext4""ext5"
Example: "ext1"
{exampleKey1}string

A key-value pair of your choice. Example: "vipMember": true

Example: "{exampleValue1}"
{exampleKey2}string

A key-value pair of your choice. Example: "loyaltyTier": "level2"

Example: "{exampleValue2}"
curl -i -X POST \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/guests/{guestRef}/extensions' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "ext1",
    "{exampleKey1}": "{exampleValue1}",
    "{exampleKey2}": "{exampleValue2}"
  }'

Responses

Successful operation.

Bodyapplication/json
hrefstring

The URL of the guest extension.

Example: "https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/ext1"
refstring

Guest extension reference.

Example: "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2"
namestring

The name of the data extension. You can only use a name once in a collection.

Example: "ext"
keystring

You must set this to default.

Example: "default"
createdAtstring(date-time)

The date and time when the resource was created in Sitecore CDP.

Example: "2024-01-01T16:17:16.000Z"
modifiedAtstring(date-time)

The date and time when the resource was last updated in Sitecore CDP.

Example: "2024-01-01T16:17:16.000Z"
{exampleKey1}string

A key-value pair in the data extension. Example: "vipMember": true

Example: "{exampleValue1}"
{exampleKey2}string

A key-value pair in the data extension. Example: "loyaltyTier": "level2"

Example: "{exampleValue2}"
guestobject(GuestHref)
Response
application/json
{ "href": "https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/ext1", "ref": "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2", "name": "ext", "key": "default", "createdAt": "2024-01-01T16:17:16.000Z", "modifiedAt": "2024-01-01T16:17:16.000Z", "{exampleKey1}": "{exampleValue1}", "{exampleKey2}": "{exampleValue2}", "guest": { "href": "https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03" } }

Retrieve a guest's collection of data extensions

Request

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.

Path
guestRefstringrequired

The guest reference. This is a unique identifier of the guest record. If you don't know the guest reference, first retrieve guests.

Example: f7aabbca-1c1b-4fc2-be72-3e16294a4f03
Query
offsetobject(Offset)

Collection responses use offset pagination. The offset query parameter is used to exclude from a response the first N items of the entire resource collection.

Default 0
Example: offset=10
limitobject(Limit)[ 10 .. 100 ]

Collection responses use offset pagination. This query parameter lets you adjust the maximum number of collection items to return for a single request.

Default 10
Example: limit=40
expandArray of strings(Expand)

You can expand items in a collection by setting expand=true. This eliminates the need to send multiple follow-up requests (one for the collection and another for each of its items). This also helps you check if the data you intend to create already exists.

Example: expand=true
curl -i -X GET \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/guests/{guestRef}/extensions?expand=true&limit=40&offset=10'

Responses

Successful operation.

Bodyapplication/json
offsetinteger(int32)

Request's offset.

Example: 0
limitinteger(int32)

Request's limit.

Example: 10
hrefstring

Request's URL.

Example: "https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/extensions?offset=0&limit=10"
itemsArray of objects(Link)

List of guests for the current request.

Example: [{"href":"https://api-engage-eu.sitecorecloud.io/v2.1/guests/c6cf690f-8384-4734-ab2d-6caa53b6308c/extensions/ext"},{"href":"https://api-engage-eu.sitecorecloud.io/v2.1/guests/1c5e13e7-8b97-4f12-9ab5-d30a6fa13d1aextensions/ext1"}]
Response
application/json
{ "offset": 0, "limit": 10, "href": "https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/extensions?offset=0&limit=10", "items": [ { … }, { … } ] }

Retrieve a data extension

Request

Retrieves a data extension for a guest.

Path
guestRefstringrequired

The guest reference. This is a unique identifier of the guest record. If you don't know the guest reference, first retrieve guests.

Example: f7aabbca-1c1b-4fc2-be72-3e16294a4f03
dataExtensionNamestringrequired

The name of the data extension. If you don't know this value, first retrieve the guest's collection of data extensions.

Enum"ext""ext1""ext2""ext3""ext4""ext5"
Example: ext1
Query
expandArray of strings

You can expand items in a collection by setting expand=true. This eliminates the need to send multiple follow-up requests (one for the collection and another for each of its items). This also helps you check if the data you intend to create already exists.

Example: expand=true
curl -i -X GET \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/guests/{guestRef}/extensions/{dataExtensionName}?expand=true'

Responses

Successful operation.

Bodyapplication/json
hrefstring

The URL of the guest extension.

Example: "https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/ext1"
refstring

Guest extension reference.

Example: "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2"
namestring

The name of the data extension. You can only use a name once in a collection.

Example: "ext"
keystring

You must set this to default.

Example: "default"
createdAtstring(date-time)

The date and time when the resource was created in Sitecore CDP.

Example: "2024-01-01T16:17:16.000Z"
modifiedAtstring(date-time)

The date and time when the resource was last updated in Sitecore CDP.

Example: "2024-01-01T16:17:16.000Z"
{exampleKey1}string

A key-value pair in the data extension. Example: "vipMember": true

Example: "{exampleValue1}"
{exampleKey2}string

A key-value pair in the data extension. Example: "loyaltyTier": "level2"

Example: "{exampleValue2}"
guestobject(GuestHref)
Response
application/json
{ "href": "https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/ext1", "ref": "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2", "name": "ext", "key": "default", "createdAt": "2024-01-01T16:17:16.000Z", "modifiedAt": "2024-01-01T16:17:16.000Z", "{exampleKey1}": "{exampleValue1}", "{exampleKey2}": "{exampleValue2}", "guest": { "href": "https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03" } }

Update a data extension

Request

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.

Path
guestRefstringrequired

The guest reference. This is a unique identifier of the guest record. If you don't know the guest reference, first retrieve guests.

Example: f7aabbca-1c1b-4fc2-be72-3e16294a4f03
dataExtensionNamestringrequired

The name of the data extension. If you don't know this value, first retrieve the guest's collection of data extensions.

Enum"ext""ext1""ext2""ext3""ext4""ext5"
Example: ext1
Bodyapplication/json
{exampleKey1}string

A key-value pair of your choice. Example: "vipMember": true

Example: "{exampleValue1}"
{exampleKey2}string

A key-value pair of your choice. Example: "loyaltyTier": "level2"

Example: "{exampleValue2}"
curl -i -X PUT \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/guests/{guestRef}/extensions/{dataExtensionName}' \
  -H 'Content-Type: application/json' \
  -d '{
    "{exampleKey1}": "{exampleValue1}",
    "{exampleKey2}": "{exampleValue2}"
  }'

Responses

Successful operation.

Bodyapplication/json
hrefstring

The URL of the guest extension.

Example: "https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03/ext1"
refstring

Guest extension reference.

Example: "6a5cb3c2-1a4a-56d8-8a01-1ede232b9db2"
namestring

The name of the data extension. You can only use a name once in a collection.

Example: "ext"
keystring

You must set this to default.

Example: "default"