Sitecore CDP guest data model for Batch API

Abstract

Provides attribute definitions and JSON examples for using the Sitecore CDP guest data model for Batch API (Data model 2.1).

This topic defines the Sitecore CDP standard data model for the following entities:

When you create a batch file, ensure that you include all required attributes in addition to any guest attributes from the following table:

Attribute

Description

Type

Example(s)

Insert

Upsert

Merge

firstSeen

The first seen date for the guest.

ISO 8601 Date/Time UTC

"2015-01-01T16:17:16.000Z"

Not supported

Optional

Optional

lastSeen

The last time the guest interacted with your brand.

ISO 8601 Date/Time UTC

"2015-01-01T16: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

"2019-01-01T00:00:00.000Z"

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

subscriptions

A list of subscriptions associated with the guest.

JSON array of JSON objects

[ { "name":"default", "channel":"EMAIL", "pointOfSale":"default", "status":"SUBSCRIBED", "effectiveDate":"2012-08-23T16:17:16.000Z" } ]

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":"2016-08-23T16:17:16.000Z" } ]

Not supported

Optional

Optional

extensions

A list of extensions associated with the guest.

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, 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.

The following is a JSON example of using upsert mode with the guest data model:

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