Guest data model
This topic defines the Sitecore CDP standard data model for the following entities:
You can only upload identified guests which are guests that have the "customer" guest type.
Note
insert mode is not supported. Use upsert or migration instead.
When you create a batch file, ensure that you include all required attributes in addition to any attributes from the following table:
| Attribute | Description | Type | Example(s) | Insert | Upsert | Migration |
|---|---|---|---|---|---|---|
firstSeen | The first seen date for the guest. | ISO 8601 Date/Time UTC | "2026-03-07T16:15.000Z" | Not supported | Optional | Optional |
lastSeen | The last time the guest interacted with your brand. | ISO 8601 Date/Time UTC | "2026-08-23T16:17.000Z" | Not supported | Optional | Optional |
guestType | A required Sitecore CDP attribute that represents the level of identity obtained. This must be set to "customer". | string (lowercase) | "customer" | Not supported | Optional | Optional |
title | The title of the guest. | string (title case) | "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" | Not supported | Optional | Optional |
firstName | The first name of the guest. | string (title case) | "John" | Not supported | Optional | Optional |
lastName | The last name of the guest. | string (recommend title case) | "Does" | Not supported | Optional | Optional |
gender | The gender of the guest. | string (lowercase) | "male", "female", "unknown" | Not supported | Optional | Optional |
dateOfBirth | The date of birth of the guest. | ISO 8601 Date/Time UTC Validation: Date must be in the past. Date must not include milliseconds. | "1985-12-24T00:00Z" | Not supported | Optional | Optional |
email | The email address of the guest. | string (recommend lowercase) | "[email protected]" | Not supported | Optional | Optional |
phoneNumbers | The phone numbers of the guest. | JSON array of strings | [ "+353161123345", "+353861123311" ] | Not supported | Optional | Optional |
language | The preferred language of the guest. | string (2 letter ISO 639 language code) | "EN", "FR", "DE" | Not supported | Optional | Optional |
nationality | The nationality of the guest. | string (title case) | "Irish", "British", "Spanish", "French""Irish", "British", "Spanish", "French" | Not supported | Optional | Optional |
passportNumber | The passport number of the guest. | string (uppercase) | "PZ4A9565" | Not supported | Optional | Optional |
passportExpiry | The expiry date of the guest's passport. | string yyyy-MM-ddTHH | "2026-12-24T00:00Z" | Not supported | Optional | Not supported |
street | The street address of the guest. | JSON array of strings (title case) | ["Ashford House", "Tara Street", "Dublin 2"] | Not supported | Optional | Optional |
city | The guest's city. | string (title case) | "Dublin", "London", "Madrid", "Paris" | Not supported | Optional | Optional |
country | The guest's country. | string (2 letter ISO 3166-1 Alpha-2 country code) | "IE", "GB", "ES", "FR" | Not supported | Optional | Optional (Uppercase) |
postCode | The guest's postcode. | string (uppercase) | "D2" | Not supported | Optional | Optional |
state | The guest's state. | string (title case) | "Oregon" | Not supported | Optional | Optional |
identifiers | A list of identifiers for the guest. | JSON array of JSON objects | [ { "provider":"CR_SYSTEM", "id":"B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41", "expiryDate":"2025-08-23T16:17.000Z" } ] | Not supported | Optional | Optional |
extensions | A list of extensions associated with the guest. You must set the value for name to ext. | JSON array of JSON objects | { "name":"ext", "key":"default", "loyaltytier":"level2", "rewardBalance":"50125", "memberSince":"2020-10-08T00:00", "loyaltyNumber":"123456789" } | Not supported | Optional | Optional |
When using upsert mode, all the fields in the guest data model are optional. However, you can only upload guests who are identified, which are guests that have the "customer" guest type.
| Attribute | Description | Type | Example(s) | Insert | Upsert | Migration |
|---|---|---|---|---|---|---|
firstSeen | The first seen date for the guest. | ISO 8601 Date/Time UTC | "2026-03-07T16:15.000Z" | Not supported | Optional | Optional |
lastSeen | The last time the guest interacted with your brand. | ISO 8601 Date/Time UTC | "2026-08-23T16:17.000Z" | Not supported | Optional | Optional |
guestType | A required Sitecore CDP attribute that represents the level of identity obtained. | string (lowercase) | "customer" | Not supported | Optional | Optional |
title | The title of the guest. | string (title case) | "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" | Not supported | Optional | Optional |
firstName | The first name of the guest. | string (title case) | "John" | Not supported | Optional | Optional |
lastName | The last name of the guest. | string (recommend title case) | "Does" | Not supported | Optional | Optional |
gender | The gender of the guest. | string (lowercase) | "male", "female", "unknown" | Not supported | Optional | Optional |
dateOfBirth | The date of birth of the guest. | ISO 8601 Date/Time UTC Validation: Date must be in the past. Date must not include milliseconds. | "1985-12-24T00:00Z" | Not supported | Optional | Optional |
email | The email address of the guest. | string (recommend lowercase) | "[email protected]" | Not supported | Optional | Optional |
phoneNumbers | The phone numbers of the guest. | JSON array of strings | [ "+353161123345", "+353861123311" ] | Not supported | Optional | Optional |
language | The preferred language of the guest. | string (2 letter ISO 639 language code) | "EN", "FR", "DE" | Not supported | Optional | Optional |
nationality | The nationality of the guest. | string (title case) | "Irish", "British", "Spanish", "French""Irish", "British", "Spanish", "French" | Not supported | Optional | Optional |
passportNumber | The passport number of the guest. | string (uppercase) | "PZ4A9565" | Not supported | Optional | Optional |
passportExpiry | The expiry date of the guest's passport. | string yyyy-MM-ddTHH | "2026-12-24T00:00Z" | Not supported | Optional | Not supported |
street | The street address of the guest. | JSON array of strings (title case) | ["Ashford House", "Tara Street", "Dublin 2"] | Not supported | Optional | Optional |
city | The guest's city. | string (title case) | "Dublin", "London", "Madrid", "Paris" | Not supported | Optional | Optional |
country | The guest's country. | string (2 letter ISO 3166-1 Alpha-2 country code) | "IE", "GB", "ES", "FR" | Not supported | Optional | Optional (Uppercase) |
postCode | The guest's postcode. | string (uppercase) | "D2" | Not supported | Optional | Optional |
state | The guest's state. | string (title case) | "Oregon" | Not supported | Optional | Optional |
identifiers | A list of identifiers for the guest. | JSON array of JSON objects | [ { "provider":"CR_SYSTEM", "id":"B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41", "expiryDate":"2025-08-23T16:17.000Z" } ] | Not supported | Optional | Optional |
extensions | A list of extensions associated with the guest. | JSON array of JSON objects | [ { "name":"loyalty", "key":"flyWithMe", "tier":"gold", "milesBalance":"50125", "memberSince":"2016-10-08T00:00", "loyaltyNumber":"123456789" } ] | Not supported | Optional | Optional |
When using upsert mode, all the fields in the guest data model are optional. However, there must be sufficient information within the object to identify the guest within the platform for it to be updated. Alternatively, if the required fields are present and no matching guests exist in the platform, a new guest is created.
If you have suggestions for improving this article, let us know!