---
title: "Guest extension data model"
slug: "guest-extension-data-model"
abstract: "Describes the standard data model for guest extensions (Sitecore CDP Batch API)."
---
# Guest extension data model
When you create a batch file, ensure that you include all [required attributes](https://doc.sitecore.com/cdp/en/developers/api/batch-api/batch-api-guest/batch-file-formatting-requirements.html#UUID-4499e082-be7d-9ebb-4936-c178936c1e06_para-idm1903351877649584) in addition to any attributes from the following table:
::::tabs
:::tab{title="2.1"}
| 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:11`.000Z"` | Not supported | Optional | Optional |
| `lastSeen` | The last time the guest interacted with your brand. | ISO 8601 Date/Time UTC | `"2026-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. | `"1985-12-24T00:00Z"` | Not supported | Optional | Optional |
| `email` | The email address of the guest. | string (recommend lowercase) | `"john.does@gmail.com"` | 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":"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](https://doc.sitecore.com/cdp/en/developers/api/batch-api/batch-api-guest/send-additional-guest-data.html). | Supported types for the "value": string: , boolean: `true` or `false`, integer: `9`, number: `99.9` | `"loyaltytier":"level2"` | Required | Required | Required |
```json
{
"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
}
]
}
}
```
:::
:::tab{title="2.0"}
| 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:11`.000Z"` | Not supported | Optional | Optional |
| `lastSeen` | The last time the guest interacted with your brand. | ISO 8601 Date/Time UTC | `"2026-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. | `"1985-12-24T00:00Z"` | Not supported | Optional | Optional |
| `email` | The email address of the guest. | string (recommend lowercase) | `"john.does@gmail.com"` | 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":"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.
```json
{
"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":"john.does@sitecore.com",
"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"
}
]
}
}
```
:::::::