Sitecore API catalog/Guest API/Guest

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, and select the Guest type: All filter. Then, in the search dropdown, select Guest reference and then enter the guest reference in the search field. Then, Sitecore CDP lists the guest profile for the guest.

Security
BasicAuth
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"
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"
dateOfBirthstring, (date-time)

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

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

The email address of the guest.

Example:"john.doe@gmail.com"
emailsArray of strings

All the email addresses of the guest.

Example:
[
  "john.doe@gmail.com"
]
firstNamestring, (title case)

The guest's first name.

Example:"John"
genderstring, (lowercase)

The guest's gender.

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

Example:"male"
hrefstring

The URL of the guest.

Example:"https://api-engage-eu.sitecorecloud.io/v2.1/guests/f7aabbca-1c1b-4fc2-be72-3e16294a4f03"
identifiersArray of objects(Identifier)

A list of identifiers for the guest.

lastNamestring, (title case recommended)

The guest's last name.

Example:"Doe"
nationalitystring, (title case)

The guest's nationality.

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

Example:"Irish"
passportExpirystring, (date-time)

The expiry date of the guest's passport.

Example:"2025-01-01T00:00:00.000Z"
passportNumberstring, (uppercase)

The passport number of the guest.

Example:"PZ4A9565"
phoneNumbersArray of strings

The phone numbers of the guest.

Example:
[
  "+353161123345",
  "+353161123346"
]
postCodestring, (uppercase)

The guest's zipcode.

Example:"D2"
refstring

The Guest's reference.

Example:"f7aabbca-1c1b-4fc2-be72-3e16294a4f03"
statestring, (title case)

The state (address) of the guest.

Example:"Oregon"
streetArray of strings

The street address of the guest.

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

Responses

Resource successfully created

Bodyapplication/json
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"
createdAtstring, (date-time)

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

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

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

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

The email address of the guest.

Example:"john.doe@gmail.com"
emailsArray of strings

All the email addresses of the guest.

Example:
[
  "john.doe@gmail.com"
]
firstNamestring, (title case)

The guest's first name.

Example:"John"
firstSeenstring, (date-time)

The first seen date for the guest.

Example:"2024-01-01T16:17:16.000Z"
genderstring, (lowercase)

The guest's gender.

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

Example:"male"
guestTypestring, (lowercase)

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"
identifiersArray of objects(Identifier)

A list of identifiers for the guest.

lastNamestring, (title case recommended)

The guest's last name.

Example:"Doe"
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"
modifiedAtstring, (date-time)

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

Example:"2024-01-01T16:17:16.000Z"
nationalitystring, (title case)

The guest's nationality.

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

Example:"Irish"
passportExpirystring, (date-time)

The expiry date of the guest's passport.

Example:"2025-01-01T00:00:00.000Z"
passportNumberstring, (uppercase)

The passport number of the guest.

Example:"PZ4A9565"
phoneNumbersArray of strings

The phone numbers of the guest.

Example:
[
  "+353161123345",
  "+353161123346"
]
postCodestring, (uppercase)

The guest's zipcode.

Example:"D2"
refstring

The Guest's reference.

Example:"f7aabbca-1c1b-4fc2-be72-3e16294a4f03"
statestring, (title case)

The state (address) of the guest.

Example:"Oregon"
streetArray of strings

The street address of the guest.

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