Skip to main content

Sitecore CDP batch file format requirements

Abstract

Provides batch file requirements for uploading to Sitecore CDP (Data model 2.1).

The Sitecore CDP Batch API supports the upload of compressed files. Each file must contain a separate JSON record for each entity to import. Each JSON record must contain a single line, be terminated with a carriage return, and encoded according to RFC 4627.

The following table includes the required fields of each JSON record within the batch import file:

Field name

Type

Description

ref

string, containing version 3 or 5 UUID

A unique ID of the record that the organization generates for the purpose of identification outside of Sitecore CDP. Each record has a unique ref.

schema

string, one of: "guest", "order", "tracking", or "migration"

The type of record contained in the value field that is being imported. Only use "migration" as the value for "schema" when migrating guests, as detailed in Sitecore CDP guest migration data model for Batch API .

mode

string, one of: "insert", "upsert", or "guest"

Indicates how to import the record into the system:

insert - overwrites everything belonging to the existing entity resulting in a new one being created

upsert - updates the existing entity only with the fields set in the request. If the entity does not exist, a new one is created.

guest - applies specific migration rules to how the fields are updated. Only use "guest" as the value for "mode", when migrating guests, as detailed in Sitecore CDP guest migration data model for Batch API

value

JSON object

Contains the entity to be imported into the platform.

Not all fields for each object are required to be present during the import. The exception is for guest data extensions, where depending on the type of guest data extension, all fields might be required.

When using upsert mode for a guest, you only need to include enough data to identify the guest within the platform, as well as the fields to be updated.

When using guest mode for a guest, all fields required to deem the entity valid must be included as the update must result in a valid entity.

The following is an example of the required format for the batch import file:

{"ref":"CE8B4A20-9C56-49A9-8B94-D1474939612F","schema":"guest","mode":"upsert","value":{"guestType":"customer","firstName":"Jane","lastName":"Jones","identifiers":[{"provider":"CDP_ID","id":"12345"}]}} 
{"ref":"A721CE88-7E0D-45FC-9380-93EA1A5CA559","schema":"guest","mode":"upsert","value":{"guestType":"customer","firstName":"Bob","lastName":"Jones","email":"bobjones@test.com","identifiers":[{"provider":"CDP_ID","id":"56789"}] <valid guest record> }}