Batch API Guest

Guest identifiers 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
`provider`	The provider of the identifier.	string (title case)	`"CRM_SYSTEM"`, `"SITECORE_IDENTITY_SYSTEM"`	Not supported	Required	Required
`id`	The unique ID of the identifier.	string (uppercase)	`"B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41"`	Not supported	Required	Required
`expiryDate`	The date and time after which the identifier is no longer valid.	ISO 8601 date/time UTC	`"2025-08-23T16:`17 `.000Z"`	Not supported	Optional	Optional

Here's an example that includes Personally Identifiable Information (PII) and uses upsert mode:

{
   "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",
      "title":"Mr",
      "firstName":"John",
      "lastName":"Does",
      "gender":"male",
      "dateOfBirth":"1985-12-24T00:00Z",
      "email":"[email protected]",
      "nationality":"Irish",
      "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"
         }
      ]
   }
}

Here's an example that includes the identifiers attribute and uses upsert mode.

{
   "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":"SITECORE_IDENTITY_SYSTEM",
            "id":"B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41",
            "expiryDate":"2025-08-23T16:`17:16`.000Z"
         }
      ]
   }
}

Note

When consumers are passed to Sitecore CDP using the Batch API, and the only identifying information is first_name and last_name, Sitecore CDP creates a new guest profile of type: traveller. An exception occurs when the consumer on the order has the same first and last name as the contact on the order. If the contact is successfully identified, then a new guest profile is not created. This only pertains to the Batch API.

{
   "ref":"9d94ee11-7043-4b71-980c-a777d00a7b46",
   "schema":"guest",
   "mode":"upsert",
   "value":{
      "firstSeen":"2010-03-07T16:`15:11`.000Z",
      "lastSeen":"2012-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",
      "subscriptions":[
         {
            "name":"default",
            "channel":"EMAIL",
            "pointOfSale":"default",
            "status":"SUBSCRIBED",
            "effectiveDate":"2012-08-23T16:`17:16`.000Z"
         }
      ],
      "identifiers":[
         {
            "provider":"SITECORE_IDENTITY_SYSTEM",
            "id":"B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41",
            "expiryDate":"2016-08-23T16:`17:16`.000Z"
         }
      ],
      "extensions":[
         {
            "name":"loyalty",
            "key":"flyWithMe",
            "tier":"gold",
            "milesBalance":"50125",
            "memberSince":"2006-10-08T00:00",
            "loyaltyNumber":"123456789"
         }
      ]
   }
}

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