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	`"2025-03-07T16:15:11.000Z"`	Not supported	Optional	Optional
`lastSeen`	The last time the guest interacted with your brand.	ISO 8601 Date/Time UTC	`"2025-08-23T16:17:16.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:mmZ	`"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:16.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.

{
   "ref":"9d94ee11-7043-4b71-980c-a777d00a7b46",
   "schema":"guest",
   "mode":"upsert",
   "value":{
      "guestType":"customer",
      "firstSeen":"2025-03-07T16:15:11.000Z",
      "lastSeen":"2025-08-23T16:17:16.000Z",
      "identifiers":[
         {
            "provider":"SITECORE_IDENTITY_SYSTEM",
            "id":"B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41",
            "expiryDate":"2025-08-23T16:17:16.000Z"
         }
      ],
      "extensions":[
         {
            "name":"ext",
            "key":"default",
            "loyaltytier":"level2",
            "rewardBalance":"50125",
            "memberSince":"2020-10-08T00:00",
            "loyaltyNumber":"123456789"
         }
      ]
   }
}

Attribute	Description	Type	Example(s)	Insert	Upsert	Migration
`firstSeen`	The first seen date for the guest.	ISO 8601 Date/Time UTC	`"2025-03-07T16:15:11.000Z"`	Not supported	Optional	Optional
`lastSeen`	The last time the guest interacted with your brand.	ISO 8601 Date/Time UTC	`"2025-08-23T16:17:16.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:mmZ	`"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:16.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.

{  
   "ref":"9d94ee11-7043-4b71-980c-a777d00a7b46",
   "schema":"guest",
   "mode":"upsert",
   "value":{  
      "firstSeen":"2025-03-07T16:15:11.000Z",
      "lastSeen":"2025-08-23T16:17:16.000Z",
      "guestType":"customer",
      "title":"Mr",
      "firstName":"John",
      "lastName":"Doe",
      "gender":"male",
      "dateOfBirth":"1985-12-24T00:00Z",
      "email":"[email protected]",
      "nationality":"Irish",
      "passportNumber":"PZ4A9565",
      "passportExpiry":"2026-12-24T00:00Z",
      "street":[  
         "Apartment 15",
         "West Drive Avenue"
      ],
      "city":"Dublin",
      "country":"IE",
      "postCode":"D2",
      "state":"Dublin",
      "identifiers":[  
         {  
            "provider":"SITECORE_IDENTITY_SYSTEM",
            "id":"B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41",
            "expiryDate":"2025-08-23T16:17:16.000Z"
         }
      ],
      "extensions":[  
         {  
            "name":"loyalty",
            "key":"flyWithMe",
            "tier":"gold",
            "milesBalance":"50125",
            "memberSince":"2016-10-08T00:00",
            "loyaltyNumber":"123456789"
         }
      ]
   }
}

If you have suggestions for improving this article, let us know!