Batch API Guest

Guest extension data model

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.	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.	`"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":"default", "loyaltytier":"level2", "rewardBalance":"50125", "memberSince":"2020-10-08T00:00", "loyaltyNumber":"123456789" }`	Required	Required	Required
`extensions.name`	You must set the value to `"ext"`.	string enum	`"ext"`	Required	Required	Required
`extensions.key`	You must set the value to `"default"`.	string	`"default"`	Required	Required	Required
`extensions.attribute`	One or many name/value pair attributes for custom data. The name must follow attribute naming guidelines.	Supported types for the "value": string: , boolean: `true` or `false`, integer: `9`, number: `99.9`	`"loyaltytier":"level2"`	Required	Required	Required

{
   "ref":"9d94ee11-7043-4b71-980c-a777d00a7b46",
   "schema":"guest",
   "mode":"upsert",
   "value":{
      "guestType":"customer",
      "firstSeen":"2026-03-07T16:`15:11`.000Z",
      "lastSeen":"2026-08-23T16:`17:16`.000Z",
      "identifiers":[
         {
            "provider":"IDENTITY_SYSTEM",
            "id":"B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41",
            "expiryDate":"2025-08-23T16:`17:16`.000Z"
         }
      ],
      "extensions":[
         {
            "name":"ext",
            "key":"default",
            "loyaltyTier":"level2",
            "rewardBalance": 5012.25,
            "memberSince":"2020-10-08T00:00",
            "vipMember": true,
            "loyaltyNumber": 123456789
         }
      ]
   }
}

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.	`"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":"default", "loyaltytier":"level2", "rewardBalance":"50125", "memberSince":"2020-10-08T00:00", "loyaltyNumber":"123456789" }`	Required	Required	Required
`extensions.name`	The name of the data extension.	string (uppercase recommended)	`"DE12346"`	Not supported	Required	Required
`extensions.key`	Key that uniquely identifies the data extension.	string (title case recommended)	`"flyWithMe"`	Not supported	Required	Required
`extensions.attribute`	Data extensions data.	string (title case)	`"tier":"gold"` `"milesBalance":"50125"`	Not supported	Required/Optional depending on extension	Optional

Caution

Certain data extensions require all fields to be present in order to not be deleted by the import. Consult your Sitecore CDP representative if you have questions.

{
   "ref":"9d94ee11-7043-4b71-980c-a777d00a7b46",
   "schema":"guest",
   "mode":"upsert",
   "value":{
      "firstSeen":"2026-03-07T16:`15:11`.000Z",
      "lastSeen":"2026-08-23T16:`17:16`.000Z",
      "guestType":"customer",
      "title":"Mr",
      "firstName":"John",
      "lastName":"Does",
      "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":"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":"2020-10-08T00:00",
            "loyaltyNumber":"123456789"
         }
      ]
   }
}

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