Introduction to Sitecore CDP REST APIs and my Postman Collection

In this post, I will introduce the Sitecore CDP REST APIs and the postman collection I created for working with the APIs. I’m a huge fan of postman it’s an essential developer tool when it comes to working with a REST API.

Sitecore CDP does not currently provide a standard document like OpenAPI (swagger) for describing the APIs, which can be used to generate a postman collection. Therefore I’ve started a collection based on the Sitecore documentation and examples they’ve provided. The Sitecore docs are an excellent resource for developers, to help you understand the various APIs and attributes. I highly recommend checking these out as they are constantly evolving since the acquisition of Boxever.

My postman collection is available on GitHub as a json file. You can import it into Postman and use it when working with your own Sitecore CDP sandbox. I hope you find it useful, please share any feedback.

Authentication

To use the collection against your sandbox you need to authenticate, Sitecore CDP supports basic authentication. An API token is a unique key that Sitecore provides your organization to authenticate your services.

1. You need to obtain your client key and API token from Sitecore CDP, in the navigation pane, click System Settings -> API Access. For basic authentication:

  • Username = Sandbox API Access Client Key
  • Password = Sandbox API Token

2. You will need to update the variables in the postman collection:

  • apiKeyId = Sandbox API Access Client Key
  • apiKeySecret = Sandbox API Token

Collections Variables

Here is a list of current variables within the collection:

VariableDescriptionExamples
apiKeyIdYour Sandbox API Client Key
apiKeySecretYour Sandbox API Token
apiEndpointAll URLs referenced in the Sitecore CDP v2.1 API
data model begin with the following base URL: https://{apiEndpoint}/v2
api.boxever.com
pointOfSaleA POS is a specific storefront your organization sells products. Sitecore CDP supports multiple storefronts certain requests need to target the correct storefront.betaSpinAir
currencyCodeThe type of currency used for requests. String value (3 letter ISO 4217).“EUR”, “USD”, “GBP”
languageThe language captured on each page the guest visited.“EN”, “FR”, “DE”
channelThe channel captured on each page the guest visited.“WEB”, “MOBILE_WEB”, “MOBILE_APP”
guestRefThe unique ID of the guest generated by Sitecore CDP.guid
guestEmailThe email address for the guest.
identifiersProviderThe provider of the identifiers.ProfileSystem
identifiersIdThe ID of the identifiers.guid
dataExtensionNameThe data extension name.extEmailPreferences
dataExtensionRefThe reference of the data extension.guid
orderRefThe reference of the order.guid
orderItemRefThe reference of the order item.guid
orderContactRefThe reference of the contact on the order.guid
orderConsumerRefThe reference of the consumer on the order.guid
batchFlowsJobRefThe reference of the Batch flow.guid
decisionModelDefinitionRefThe reference of the Decision Model Definition.guid
decisionModelDefinitionRevisionThe reference of the Decision Model Definition Revisions.guid
decisionModelVariantRefThe reference of the Decision Model Variant.guid
decisionModelVariantRevisionThe reference of the Decision Model Variant Revision.guid
connectionRefThe reference of the Connection.guid

CDP REST API documentation

The collection was created based on the available Sitecore CDP REST API documentation. The documentation describes 2 API versions.

  • Version 2.1 Data Model – is the most recent and if your organization has only started using CDP since April 2021 (after Boxever was acquired by Sitecore) you will want to use this version of the documentation.
  • Version 2.0 Data Model – if your organization was already using CDP before April 2021 use this version.

Note: As the documentation evolves you might find yourself switching between versions to get more detailed information or examples.

Guests

A guest is any person that interacts with your brand, regardless of whether they are identified. The guest is the main entity in Sitecore CDP and each guest has a unique identifier (GUID). Sitecore CDP provides the following REST API methods for managing the guest data model:

  • Locate Guests – a get request to search for guests and returns 0 or more guest guestRefs. You can use any of the following parameters (camelCase) to search for guests:firstName
    • lastName
    • phoneNumber
    • email
    • email.untouched
    • identifiers.provider
    • identifiers.id
  • Note: You can also pass pagination parameters with the locate guests request:
    • offset – zero-based starting index in the entire collection of the first item to return (default is 0).
    • limit – maximum number of collection items to return for a single request (minimum value: is 1, maximum value: 100, default is 10).
  • Retrieve Guest – a get request to retrieve a single guest using the unique guestRef parameter.
  • Create Guest – a post request to create a new guest user.
  • Update Guest – a post request to update guest model attributes using the guestRef parameter to reference the guest record.

Guest Data Extensions

The Guest Data Extensions model allows you to extend the Guest model and store custom data against each guest.  It is an array that enables you to specify whatever name/value pairs (attributes) you wish.

  • Locate guest data extension a get request to return guest(s) using identifying information stored in a data extension. After you perform the locate guest data extension function, you can use the guestRef included in the response. You can also specify the pagination params.
  • Retrieve guest data extension – a get request return a full guest record using identifying information stored in a data extension. Using the following parameters: guestRef, dataExtensionName, dataExtensionRef
  • Create guest data extension – a post request to create guest data extension.
  • Update guest data extension – a post request to update guest data extension.
  • Delete guest data extension – a delete request to remove a data extension. Using the following parameters: guestRef, dataExtensionName, dataExtensionRef.

Orders

The following methods are available for the Order Data Model

  • Create Order – a post request to create an order.
  • Retrieve Order – a get request to retrieve an order as well as additional attributes contained in the declared order entity using the orderRef param.
  • Locate Order– a get request to locate orders function to return the referenceId of the order(s). The response returns the referenceIds of the order(s) which you can then use when you retrieve an order.

NOTE: Not currently documented in v2.1 data model, refer to 2.0.

Order Items

The order item object model represents something that has been purchased as part of the order.

  • Create order item – a post request to create order item function to create an order item.
  • Retrieve order item – a get request to retrieve the attributes of an order item.
  • Update order item – a post request to update order item function to update the attributes of an order item.
  • Locate order item – a get request to locate an order item using orderRef parameter. The response returns the referenceId of the Order Item(s) which you can use when you retrieve an order item.
  • Delete order item – a delete request to delete an order item.

NOTE: Not currently documented in v2.1 data model, refer to 2.0.

Order Contacts

The order contact model represents the primary contact for an order. The same guest can be both the order contact and order consumer.

  • Locate order contacts – a get request to locate order contacts using orderRef parameter. The response returns the orderContactRef which you can then use when you retrieve an order contact.
  • Retrieve order contact – a get request to retrieve the primary contact on an order using the orderContactRef.
  • Create order contact – a post request to create order item function to create a primary contact on an order.
  • Update order contact – a post request to update order item function to update the primary contact.
  • Delete order contact – a delete request to delete an order contact.

NOTE: Not currently documented in v2.1 data model, refer to 2.0.

Order Consumers

The order consumer model represents the guest who is consuming an order item. If the order item is a flight, the order consumer is the traveler or passenger of the flight segment.

  • Locate order consumer – a get request to locate order contacts using orderRef parameter. The response returns the orderConsumerRef which you can then use when you retrieve an order contact.
  • Retrieve order consumer – a get request to retrieve the consumer on an order using the orderConsumerRef.
  • Create order consumer – a post request to create order item function to create a consumer on an order.
  • Update order consumer – a post request to update order item function to update the consumer.

NOTE: Not currently documented in v2.1 data model, refer to 2.0.

Audience Sync

Batch imports are used to ingest guest and order data into the CDP on a regular scheduled basis (e.g. daily). Batch imports are generally used for importing large amounts of data.

Decisions

A Decision data model object is the parent for decision Model variants. The following methods allow you to manipulate the decision Model.

Decision Variants

A Decision variant data model is a child of a decision model.

  • Retrieve decision model variant – a get request to return a decision model variant reference. Using the decisionModelVariantRef attribute returned when retrieving the decision model variant reference.
  • Create a decision model variant – a post request to create a decision model variant. Using the decisionModelDefinitionRef.
  • Update decision model variant – a put request to to update a decision model variant. You must provide the decisionModelVariantRef.
  • Retrieve a decision model variant revision – a get request to return a decision model variant revision. You must provide the decisionModelVariantRef attribute returned when retrieving the decision model variant reference and the revision number.
  • Retrieve decision model variant revisions – a get request to return decision model variant revisions. To do this, you must have the decisionModelVariantRef attribute returned when retrieving the decision model variant reference.

CDP connections

The connections data model – allows you to manage connections to external systems.

Flow Execution

The flow execution data model – send a flow execution request for an interactive experiment using either the browserId, email, or identifiers attribute. A flow is a mechanism that runs an experiment or experience on the Sitecore CDP back end.

  • Create Flow Execution – to create a flow execution function to execute an interactive experiment or web experiment over any web-based or mobile application.
  • Run Experiment – When you create an experiment, Sitecore CDP automatically creates an ID when you name the experiment. You can programmatically run experiments using the friendlyID attribute.

Hope this is helpful!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s