Unfortunately, this feature is not supported on mobile devices. For the best experience, please use a computer.

Retrieve a guest

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:

View the captured data in the guest profile.
Use the captured data to build segments of guests.
Export audience data to activate audiences outside Sitecore CDP.

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

index.json

index.yaml

Overview

License Apache 2.0

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

Create a guest

Request

Creates a guest. The REST API does not check whether a guest already exists in Sitecore CDP when you create a guest. To avoid creating duplicates, first retrieve guests by their email address or other identifying information.

In the response, the ref key contains the guest reference.

Find the guest in Sitecore CDP

You can also use the guest reference to find data about the guest in Sitecore CDP. In Sitecore CDP, click Guests. In the Search field, enter the guest reference, then click the Guest type: All filter. Then, Sitecore CDP lists the guest profile for the guest.

Bodyapplication/json

guestTypestring(lowercase)required

The level of identity obtained. The "traveller" value is only applicable to certain industries.

Enum"visitor""customer""traveller"

Example: "visitor"

hrefstring

The URL of the guest.

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

refstring

Guest's reference.

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

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 updated in Sitecore CDP.

Example: "2024-01-01T16:17:16.000Z"

firstSeenstring(date-time)

The first seen date for the guest.

Example: "2024-01-01T16:17:16.000Z"

lastSeenstring(date-time)

The last time the guest interacted with your brand. If the guest is currently online and is interacting with your brand, this returns the date and timestamp of when the current session started.

Example: "2024-01-01T16:17:16.000Z"

titlestring(title case)

The title of the guest.

Example values: "Br", "Brigadier", "Capt", "Colonel", "Dame", "Dr", "Elder", "Fr", "General", "Hon", "Judge", "Lord", "Master", "Miss", "Mr", "Mrs", "Ms", "Mstr", "Prof", "Rabbi", "Rev", "Shaikha", "Sheikh", "Sir", "Sister", "Sr"

Example: "Mr"

firstNamestring(title case)

The guest's first name.

Example: "John"

lastNamestring(title case recommended)

The guest's last name.

Example: "Doe"

genderstring(lowercase)

The guest's gender.

Example values: "male", "female", "unknown"

Example: "male"

dateOfBirthstring(date-time)

The guest's date of birth. Validation: Date must be in the past.

Example: "1991-01-01T16:17:16.000Z"

nationalitystring(title case)

The guest's nationality.

Example values: "Irish", "British", "Spanish", "French"

Example: "Irish"

passportNumberstring(uppercase)

The passport number of the guest.

Example: "PZ4A9565"

passportExpirystring(date-time)

The expiry date of the guest's passport.

Example: "2025-01-01T00:00:00.000Z"

emailsArray of strings

All the email addresses of the guest.

Example: ["john.doe@gmail.com"]

emailstring

The email address of the guest.

Example: "john.doe@gmail.com"

identifiersArray of objects(Identifier)

A list of identifiers for the guest.

phoneNumbersArray of strings

The phone numbers of the guest.

Example: ["+353161123345","+353161123346"]

streetArray of strings(title case strings)

The street address of the guest.

Example: ["Ashford House","Tara Street","Dublin 2"]

citystring(title case)

The guest's city.

Example values: "Dublin", "London", "Madrid", "Paris"

Example: "Dublin"

countrystring(2-letter ISO 3166-1 Alpha-2 country code)

The guest's country.

Example values: "IE", "GB", "ES", "FR"

Example: "IE"

postCodestring(uppercase)

The guest's zipcode.

Example: "D2"

statestring(title case)

The state (address) of the guest.

Example: "Oregon"

curl -i -X POST \
  -u <username>:<password> \
  https://api-engage-ap.sitecorecloud.io/v2.1/guests \
  -H 'Content-Type: application/json' \
  -d '{
    "href": "https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03",
    "ref": "f7aabbca-1c1b-4fc2-be72-3e16294a4f03",
    "createdAt": "2024-01-01T16:17:16.000Z",
    "modifiedAt": "2024-01-01T16:17:16.000Z",
    "firstSeen": "2024-01-01T16:17:16.000Z",
    "lastSeen": "2024-01-01T16:17:16.000Z",
    "guestType": "visitor",
    "title": "Mr",
    "firstName": "John",
    "lastName": "Doe",
    "gender": "male",
    "dateOfBirth": "1991-01-01T16:17:16.000Z",
    "nationality": "Irish",
    "passportNumber": "PZ4A9565",
    "passportExpiry": "2025-01-01T00:00:00.000Z",
    "emails": [
      "john.doe@gmail.com"
    ],
    "email": "john.doe@gmail.com",
    "identifiers": [
      {
        "provider": "ProfileSystem",
        "id": "B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41",
        "expiryDate": "2025-01-01T16:17:16.000Z"
      }
    ],
    "phoneNumbers": [
      "+353161123345",
      "+353161123346"
    ],
    "street": [
      "Ashford House",
      "Tara Street",
      "Dublin 2"
    ],
    "city": "Dublin",
    "country": "IE",
    "postCode": "D2",
    "state": "Oregon"
  }'

Responses

Resource successfully created.

Bodyapplication/json

guestTypestring(lowercase)required

The level of identity obtained. The "traveller" value is only applicable to certain industries.

Enum"visitor""customer""traveller"

Example: "visitor"

hrefstring

The URL of the guest.

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

refstring

Guest's reference.

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

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 updated in Sitecore CDP.

Example: "2024-01-01T16:17:16.000Z"

firstSeenstring(date-time)

The first seen date for the guest.

Example: "2024-01-01T16:17:16.000Z"

lastSeenstring(date-time)

The last time the guest interacted with your brand. If the guest is currently online and is interacting with your brand, this returns the date and timestamp of when the current session started.

Example: "2024-01-01T16:17:16.000Z"

titlestring(title case)

The title of the guest.

Example: "Mr"

firstNamestring(title case)

The guest's first name.

Example: "John"

lastNamestring(title case recommended)

The guest's last name.

Example: "Doe"

genderstring(lowercase)

The guest's gender.

Example values: "male", "female", "unknown"

Example: "male"

dateOfBirthstring(date-time)

The guest's date of birth. Validation: Date must be in the past.

Example: "1991-01-01T16:17:16.000Z"

nationalitystring(title case)

The guest's nationality.

Example values: "Irish", "British", "Spanish", "French"

Example: "Irish"

passportNumberstring(uppercase)

The passport number of the guest.

Example: "PZ4A9565"

passportExpirystring(date-time)

The expiry date of the guest's passport.

Example: "2025-01-01T00:00:00.000Z"

emailsArray of strings

All the email addresses of the guest.

Example: ["john.doe@gmail.com"]

emailstring

The email address of the guest.

Example: "john.doe@gmail.com"

identifiersArray of objects(Identifier)

A list of identifiers for the guest.

phoneNumbersArray of strings

The phone numbers of the guest.

Example: ["+353161123345","+353161123346"]

streetArray of strings(title case strings)

The street address of the guest.

Example: ["Ashford House","Tara Street","Dublin 2"]

citystring(title case)

The guest's city.

Example values: "Dublin", "London", "Madrid", "Paris"

Example: "Dublin"

countrystring(2-letter ISO 3166-1 Alpha-2 country code)

The guest's country.

Example values: "IE", "GB", "ES", "FR"

Example: "IE"

postCodestring(uppercase)

The guest's zipcode.

Example: "D2"

statestring(title case)

The state (address) of the guest.

Example: "Oregon"

Response

application/json

{
  "href": "https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03",
  "ref": "f7aabbca-1c1b-4fc2-be72-3e16294a4f03",
  "createdAt": "2024-01-01T16:17:16.000Z",
  "modifiedAt": "2024-01-01T16:17:16.000Z",
  "firstSeen": "2024-01-01T16:17:16.000Z",
  "lastSeen": "2024-01-01T16:17:16.000Z",
  "guestType": "visitor",
  "title": "Mr",
  "firstName": "John",
  "lastName": "Doe",
  "gender": "male",
  "dateOfBirth": "1991-01-01T16:17:16.000Z",
  "nationality": "Irish",
  "passportNumber": "PZ4A9565",
  "passportExpiry": "2025-01-01T00:00:00.000Z",
  "emails": [
    "john.doe@gmail.com"
  ],
  "email": "john.doe@gmail.com",
  "identifiers": [
    { … }
  ],
  "phoneNumbers": [
    "+353161123345",
    "+353161123346"
  ],
  "street": [
    "Ashford House",
    "Tara Street",
    "Dublin 2"
  ],
  "city": "Dublin",
  "country": "IE",
  "postCode": "D2",
  "state": "Oregon"
}

Retrieve guests

Request

Retrieves guests. We recommend that you retrieve guests by their email address or other identifying information using query parameters before you create a guest. This lets you check if a certain guest already exists in Sitecore CDP. If the guest exists, avoid creating duplicates. Instead, update the existing guest.

Query parameters

You can use the following query parameters to retrieve guests by some identifying information:

email
email.untouched
firstName
lastName
phoneNumber
identifiers.provider plus identifiers.id

Alternatively, you can use the expand=true query parameter to retrieve guests with all their key-value pairs listed.

Examples

Here's an example of how to use the email query parameter to retrieve guests by their email address:

{baseURL}/v2.1/guests?email=john.doe@gmail.com"

Here's an example of how to use the identifiers.provider and the identifiers.id query parameters to retrieve guests by their identifiers:

{baseURL}/v2.1/guests?identifiers.provider=ProfileSystem&identifiers.id=B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41"

If any of this returns a guest, avoid creating another guest with the same identifying information. Instead, update the existing guest.

Guest reference

In the response, in items.href, the guest reference is the string that follows the final slash:

"href": "{baseURL}/v2.1/guests/{guestRef}"

Example guest reference: f7aabbca-1c1b-4fc2-be72-3e16294a4f03

Use the guest reference to interact with the full guest record, for example, to retrieve or update it.

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

sortstring

You can sort search results by specifying a sort query parameter and a corresponding sort value (ASC or DESC case sensitive) on a collection resource URL.

The example query parameter shows how to return a resource in ascending chronological order of when the resource was created and descending order of the resource label.

Example: sort=createdAt::ASC|label::DESC

curl -i -X GET \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/guests?expand=true&limit=40&offset=10&sort=createdAt%3A%3AASC%2Clabel%3A%3ADESC'

Responses

Successful operation.

Bodyapplication/json

offsetinteger(int32)

Request's offset.

Example: 0

limitinteger(int32)

Request's limit.

Example: 10

Firstobject(First)

Request's first list of guests URL.

Nextobject(Next)

Request's next list of guests URL.

hrefstring

Request's URL.

Example: "https://api-engage-eu.sitecorecloud.io/v2.1/guests?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"},{"href":"https://api-engage-eu.sitecorecloud.io/v2.1/guests/1c5e13e7-8b97-4f12-9ab5-d30a6fa13d1a"}]

Response

application/json

{
  "offset": 0,
  "limit": 10,
  "First": {
    "href": "https://api-engage-eu.sitecorecloud.io/v2.1/guests?offset=0&limit=10"
  },
  "Next": {
    "href": "https://api-engage-eu.sitecorecloud.io/v2.1/guests?offset=0&limit=10"
  },
  "href": "https://api-engage-eu.sitecorecloud.io/v2.1/guests?offset=0&limit=10",
  "items": [
    { … },
    { … }
  ]
}

Retrieve a guest

Request

Retrieves the full guest record of a guest, including any guest data extensions.

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

expandArray of strings

Example: expand=true

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

Responses

Successful operation.

Bodyapplication/json

guestTypestring(lowercase)required

The level of identity obtained. The "traveller" value is only applicable to certain industries.

Enum"visitor""customer""traveller"

Example: "visitor"

hrefstring

The URL of the guest.

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

refstring

Guest's reference.

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

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 updated in Sitecore CDP.

Example: "2024-01-01T16:17:16.000Z"

firstSeenstring(date-time)

The first seen date for the guest.

Example: "2024-01-01T16:17:16.000Z"

lastSeenstring(date-time)

The last time the guest interacted with your brand. If the guest is currently online and is interacting with your brand, this returns the date and timestamp of when the current session started.

Example: "2024-01-01T16:17:16.000Z"

titlestring(title case)

The title of the guest.

Example: "Mr"

firstNamestring(title case)

The guest's first name.

Example: "John"

lastNamestring(title case recommended)

The guest's last name.

Example: "Doe"

genderstring(lowercase)

The guest's gender.

Example values: "male", "female", "unknown"

Example: "male"

dateOfBirthstring(date-time)

The guest's date of birth. Validation: Date must be in the past.

Example: "1991-01-01T16:17:16.000Z"

nationalitystring(title case)

The guest's nationality.

Example values: "Irish", "British", "Spanish", "French"

Example: "Irish"

passportNumberstring(uppercase)

The passport number of the guest.

Example: "PZ4A9565"

passportExpirystring(date-time)

The expiry date of the guest's passport.

Example: "2025-01-01T00:00:00.000Z"

emailsArray of strings

All the email addresses of the guest.

Example: ["john.doe@gmail.com"]

emailstring

The email address of the guest.

Example: "john.doe@gmail.com"

identifiersArray of objects(Identifier)

A list of identifiers for the guest.

phoneNumbersArray of strings

The phone numbers of the guest.

Example: ["+353161123345","+353161123346"]

streetArray of strings(title case strings)

The street address of the guest.

Example: ["Ashford House","Tara Street","Dublin 2"]

citystring(title case)

The guest's city.

Example values: "Dublin", "London", "Madrid", "Paris"

Example: "Dublin"

countrystring(2-letter ISO 3166-1 Alpha-2 country code)

The guest's country.

Example values: "IE", "GB", "ES", "FR"

Example: "IE"

postCodestring(uppercase)

The guest's zipcode.

Example: "D2"

statestring(title case)

The state (address) of the guest.

Example: "Oregon"

Response

application/json

{
  "href": "https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03",
  "ref": "f7aabbca-1c1b-4fc2-be72-3e16294a4f03",
  "createdAt": "2024-01-01T16:17:16.000Z",
  "modifiedAt": "2024-01-01T16:17:16.000Z",
  "firstSeen": "2024-01-01T16:17:16.000Z",
  "lastSeen": "2024-01-01T16:17:16.000Z",
  "guestType": "visitor",
  "title": "Mr",
  "firstName": "John",
  "lastName": "Doe",
  "gender": "male",
  "dateOfBirth": "1991-01-01T16:17:16.000Z",
  "nationality": "Irish",
  "passportNumber": "PZ4A9565",
  "passportExpiry": "2025-01-01T00:00:00.000Z",
  "emails": [
    "john.doe@gmail.com"
  ],
  "email": "john.doe@gmail.com",
  "identifiers": [
    { … }
  ],
  "phoneNumbers": [
    "+353161123345",
    "+353161123346"
  ],
  "street": [
    "Ashford House",
    "Tara Street",
    "Dublin 2"
  ],
  "city": "Dublin",
  "country": "IE",
  "postCode": "D2",
  "state": "Oregon"
}

Update a guest

Request

Fully updates 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 guest 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

Bodyapplication/json

guestTypestring(lowercase)

The level of identity obtained. The "traveller" value is only applicable to certain industries.

Enum"visitor""customer""traveller"

Example: "visitor"

titlestring(title case)

The title of the guest.

Example: "Mr"

firstNamestring(title case)

The guest's first name.

Example: "John"

lastNamestring(title case recommended)

The guest's last name.

Example: "Doe"

genderstring(lowercase)

The guest's gender.

Example values: "male", "female", "unknown"

Example: "male"

dateOfBirthstring(date-time)

The guest's date of birth. Validation: Date must be in the past.

Example: "1991-01-01T16:17:16.000Z"

nationalitystring(title case)

The guest's nationality.

Example values: "Irish", "British", "Spanish", "French"

Example: "Irish"

passportNumberstring(uppercase)

The passport number of the guest.

Example: "PZ4A9565"

passportExpirystring(date-time)

The expiry date of the guest's passport.

Example: "2025-01-01T00:00:00.000Z"

emailsArray of strings

All the email addresses of the guest.

Example: ["john.doe@gmail.com"]

phoneNumbersArray of strings

The phone numbers of the guest.

Example: ["+353161123345","+353161123346"]

identifiersArray of objects(Identifier)

A list of identifiers for the guest.

streetArray of strings(title case strings)

The street address of the guest.

Example: ["Ashford House","Tara Street","Dublin 2"]

citystring(title case)

The guest's city.

Example values: "Dublin", "London", "Madrid", "Paris"

Example: "Dublin"

countrystring(2-letter ISO 3166-1 Alpha-2 country code)

The guest's country.

Example values: "IE", "GB", "ES", "FR"

Example: "IE"

postCodestring(uppercase)

The guest's postcode.

Example: "D2"

statestring(title case)

The state (address) of the guest.

Example: "Oregon"

curl -i -X PUT \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/guests/{guestRef}' \
  -H 'Content-Type: application/json' \
  -d '{
    "guestType": "visitor",
    "title": "Mr",
    "firstName": "John",
    "lastName": "Doe",
    "gender": "male",
    "dateOfBirth": "1991-01-01T16:17:16.000Z",
    "nationality": "Irish",
    "passportNumber": "PZ4A9565",
    "passportExpiry": "2025-01-01T00:00:00.000Z",
    "emails": [
      "john.doe@gmail.com"
    ],
    "phoneNumbers": [
      "+353161123345",
      "+353161123346"
    ],
    "identifiers": [
      {
        "provider": "ProfileSystem",
        "id": "B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41",
        "expiryDate": "2025-01-01T16:17:16.000Z"
      }
    ],
    "street": [
      "Ashford House",
      "Tara Street",
      "Dublin 2"
    ],
    "city": "Dublin",
    "country": "IE",
    "postCode": "D2",
    "state": "Oregon"
  }'

Responses

Successful operation.

Bodyapplication/json

guestTypestring(lowercase)required

The level of identity obtained. The "traveller" value is only applicable to certain industries.

Enum"visitor""customer""traveller"

Example: "visitor"

hrefstring

The URL of the guest.

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

refstring

Guest's reference.

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

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 updated in Sitecore CDP.

Example: "2024-01-01T16:17:16.000Z"

firstSeenstring(date-time)

The first seen date for the guest.

Example: "2024-01-01T16:17:16.000Z"

lastSeenstring(date-time)

The last time the guest interacted with your brand. If the guest is currently online and is interacting with your brand, this returns the date and timestamp of when the current session started.

Example: "2024-01-01T16:17:16.000Z"

titlestring(title case)

The title of the guest.

Example: "Mr"

firstNamestring(title case)

The guest's first name.

Example: "John"

lastNamestring(title case recommended)

The guest's last name.

Example: "Doe"

genderstring(lowercase)

The guest's gender.

Example values: "male", "female", "unknown"

Example: "male"

dateOfBirthstring(date-time)

The guest's date of birth. Validation: Date must be in the past.

Example: "1991-01-01T16:17:16.000Z"

nationalitystring(title case)

The guest's nationality.

Example values: "Irish", "British", "Spanish", "French"

Example: "Irish"

passportNumberstring(uppercase)

The passport number of the guest.

Example: "PZ4A9565"

passportExpirystring(date-time)

The expiry date of the guest's passport.

Example: "2025-01-01T00:00:00.000Z"

emailsArray of strings

All the email addresses of the guest.

Example: ["john.doe@gmail.com"]

emailstring

The email address of the guest.

Example: "john.doe@gmail.com"

identifiersArray of objects(Identifier)

A list of identifiers for the guest.

phoneNumbersArray of strings

The phone numbers of the guest.

Example: ["+353161123345","+353161123346"]

streetArray of strings(title case strings)

The street address of the guest.

Example: ["Ashford House","Tara Street","Dublin 2"]

citystring(title case)

The guest's city.

Example values: "Dublin", "London", "Madrid", "Paris"

Example: "Dublin"

countrystring(2-letter ISO 3166-1 Alpha-2 country code)

The guest's country.

Example values: "IE", "GB", "ES", "FR"

Example: "IE"

postCodestring(uppercase)

The guest's zipcode.

Example: "D2"

statestring(title case)

The state (address) of the guest.

Example: "Oregon"

Response

application/json

{
  "href": "https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03",
  "ref": "f7aabbca-1c1b-4fc2-be72-3e16294a4f03",
  "createdAt": "2024-01-01T16:17:16.000Z",
  "modifiedAt": "2024-01-01T16:17:16.000Z",
  "firstSeen": "2024-01-01T16:17:16.000Z",
  "lastSeen": "2024-01-01T16:17:16.000Z",
  "guestType": "visitor",
  "title": "Mr",
  "firstName": "John",
  "lastName": "Doe",
  "gender": "male",
  "dateOfBirth": "1991-01-01T16:17:16.000Z",
  "nationality": "Irish",
  "passportNumber": "PZ4A9565",
  "passportExpiry": "2025-01-01T00:00:00.000Z",
  "emails": [
    "john.doe@gmail.com"
  ],
  "email": "john.doe@gmail.com",
  "identifiers": [
    { … }
  ],
  "phoneNumbers": [
    "+353161123345",
    "+353161123346"
  ],
  "street": [
    "Ashford House",
    "Tara Street",
    "Dublin 2"
  ],
  "city": "Dublin",
  "country": "IE",
  "postCode": "D2",
  "state": "Oregon"
}

Partially update a guest

Request

Partially updates a guest, replacing only those fields in the resource that you provide in the request.

For example, you can use this request to update the guest's array of phone numbers when they enter a new one.

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

phoneNumbersArray of strings

The phone numbers of the guest.

Example: ["+353161123345","+353161123346"]

curl -i -X PATCH \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/guests/{guestRef}' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumbers": [
      "+353161123345",
      "+353161123346"
    ]
  }'

Responses

Successful operation.

Bodyapplication/json

guestTypestring(lowercase)required

The level of identity obtained. The "traveller" value is only applicable to certain industries.

Enum"visitor""customer""traveller"

Example: "visitor"

hrefstring

The URL of the guest.

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

refstring

Guest's reference.

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

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 updated in Sitecore CDP.

Example: "2024-01-01T16:17:16.000Z"

firstSeenstring(date-time)

The first seen date for the guest.

Example: "2024-01-01T16:17:16.000Z"

lastSeenstring(date-time)

The last time the guest interacted with your brand. If the guest is currently online and is interacting with your brand, this returns the date and timestamp of when the current session started.

Example: "2024-01-01T16:17:16.000Z"

titlestring(title case)

The title of the guest.

Example: "Mr"

firstNamestring(title case)

The guest's first name.

Example: "John"

lastNamestring(title case recommended)

The guest's last name.

Example: "Doe"

genderstring(lowercase)

The guest's gender.

Example values: "male", "female", "unknown"

Example: "male"

dateOfBirthstring(date-time)

The guest's date of birth. Validation: Date must be in the past.

Example: "1991-01-01T16:17:16.000Z"

nationalitystring(title case)

The guest's nationality.

Example values: "Irish", "British", "Spanish", "French"

Example: "Irish"

passportNumberstring(uppercase)

The passport number of the guest.

Example: "PZ4A9565"

passportExpirystring(date-time)

The expiry date of the guest's passport.

Example: "2025-01-01T00:00:00.000Z"

emailsArray of strings

All the email addresses of the guest.

Example: ["john.doe@gmail.com"]

emailstring

The email address of the guest.

Example: "john.doe@gmail.com"

identifiersArray of objects(Identifier)

A list of identifiers for the guest.

phoneNumbersArray of strings

The phone numbers of the guest.

Example: ["+353161123345","+353161123346"]

streetArray of strings(title case strings)

The street address of the guest.

Example: ["Ashford House","Tara Street","Dublin 2"]

citystring(title case)

The guest's city.

Example values: "Dublin", "London", "Madrid", "Paris"

Example: "Dublin"

countrystring(2-letter ISO 3166-1 Alpha-2 country code)

The guest's country.

Example values: "IE", "GB", "ES", "FR"

Example: "IE"

postCodestring(uppercase)

The guest's zipcode.

Example: "D2"

statestring(title case)

The state (address) of the guest.

Example: "Oregon"

Response

application/json

{
  "href": "https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03",
  "ref": "f7aabbca-1c1b-4fc2-be72-3e16294a4f03",
  "createdAt": "2024-01-01T16:17:16.000Z",
  "modifiedAt": "2024-01-01T16:17:16.000Z",
  "firstSeen": "2024-01-01T16:17:16.000Z",
  "lastSeen": "2024-01-01T16:17:16.000Z",
  "guestType": "visitor",
  "title": "Mr",
  "firstName": "John",
  "lastName": "Doe",
  "gender": "male",
  "dateOfBirth": "1991-01-01T16:17:16.000Z",
  "nationality": "Irish",
  "passportNumber": "PZ4A9565",
  "passportExpiry": "2025-01-01T00:00:00.000Z",
  "emails": [
    "john.doe@gmail.com"
  ],
  "email": "john.doe@gmail.com",
  "identifiers": [
    { … }
  ],
  "phoneNumbers": [
    "+353161123345",
    "+353161123346"
  ],
  "street": [
    "Ashford House",
    "Tara Street",
    "Dublin 2"
  ],
  "city": "Dublin",
  "country": "IE",
  "postCode": "D2",
  "state": "Oregon"
}

Delete a guest

Request

Deletes a guest record and all entities associated with the guest including orders, sessions, and events. This is an irreversible operation. After you delete a guest record, you cannot retrieve the guest record or any related entities.

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

curl -i -X DELETE \
  -u <username>:<password> \
  'https://api-engage-ap.sitecorecloud.io/v2.1/guests/{guestRef}'

Responses

Successful operation.

Bodyapplication/json

Response

application/json

null

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

Sitecore CDP Guest REST API (v2.1)

Authentication

Guest

Create a guest

Request

Find the guest in Sitecore CDP

Responses

Was this helpful?

Retrieve guests

Request

Query parameters

Examples

Guest reference

Responses

Was this helpful?

Retrieve a guest

Request

Responses

Was this helpful?

Update a guest

Request

Responses

Was this helpful?

Partially update a guest

Request

Responses

Was this helpful?

Delete a guest

Request

Responses

Was this helpful?

Guest data extension