Guest REST API v2 (legacy)
Important
A newer version of this REST API (v2.1) is available. If you're new to this 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 object is the core entity of Sitecore CDP. The personal data of a customer or prospect is recorded and stored, and all relevant transactional and behavioral data is linked in a guest profile.
The following are guest attributes:
| Attribute | Type | Description | Example(s) |
|---|---|---|---|
firstSeen | ISO 8601 Date/Time UTC | The first seen date for the guest. | "2026-01-01T16:17.000Z" |
lastSeen | ISO 8601 Date/Time UTC | 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. | "2026-01-01T16:17.000Z" |
guestType | string enum (lowercase) | The level of identity obtained. | Must be one of the following:
|
title | string (title case) | The title of the guest. | "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" |
firstName | string (title case) | The first name of the guest. | "John" |
lastName | string (recommend title case) | The last name of the guest. | "Doe" |
gender | string (lowercase) | The gender of the guest. | "male", "female", "unknown" |
dateOfBirth | ISO 8601 Date/Time UTC Validation: Date must be in the past. | The date of birth of the guest. | "1985-12-24T00:00Z" |
emails | JSON array of strings | The email addresses of the guest. | ["[email protected]", "[email protected]" ] |
phoneNumbers | JSON array of strings | The phone numbers of the guest. | [ "+353161123345", "+353861123311" ] |
language | string (2 letter ISO 639 language code) | The preferred language of the guest. | "EN", "FR", "DE" |
nationality | string (title case) | The nationality of the guest. | "Irish", "British", "Spanish", "French" |
passportNumber | string (uppercase) | The passport number of the guest. | "PZ4A9565" |
passportExpiry | string | The expiry date of the guest's passport. | "2025-01-01T00:00.000Z" |
street | JSON array of strings (title case) | The street address of the guest. | ["Ashford House", "Tara Street", "Dublin 2"] |
city | string (title case) | The guest's city. | "Dublin", "London", "Madrid", "Paris" |
country | string (2 letter ISO 3166-1 Alpha-2 country code) | The guest's country. | "IE", "GB", "ES", "FR" |
postCode | string (uppercase) | The guest's postcode. | "D2" |
state | string (title case) | The guest's state. | "Oregon" |
identifiers | JSON array of JSON objects | A list of identifiers for the guest. | [ { "provider":"SITECORE_IDENTITY_SYSTEM", "id":"B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41", "expiryDate":"2025-08-23T16:17.000Z" } ] |
The following are identifier model attributes:
| Attribute | Description | Type | Example(s) | Required/optional |
|---|---|---|---|---|
provider | The identifier provider. | string | "ProfileSystem" | Required |
id | The identifier ID. | string | "B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41" | Required |
expiryDate | The expiry date of the identifier. | ISO 8601 Date/Time UTC | "2025-01-01T16:17.000Z" | Optional |
The following are the standard response attributes:
| Attribute | Description | Type | Example(s) |
|---|---|---|---|
href | The resource fully qualified location Uniform Resource Identifier (URI). | string | "https://{apiEndpoint}/v2/{resourceName}/{resourceRef}" |
ref | The reference of the resource. | string UUID | "9d94ee11-7043-4b71-980c-a777d00a7b46" |
createdAt | Date and time when the resource was created in Sitecore CDP. | ISO 8601 Date/Time UTC | "2026-01-01T16:17.000Z" |
modifiedAt | Date and time when the resource was updated in Sitecore CDP. | ISO 8601 Date/Time UTC | "2026-01-01T16:17.000Z" |
If you have suggestions for improving this article, let us know!