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:
| Variable | Description | Examples |
| apiKeyId | Your Sandbox API Client Key | |
| apiKeySecret | Your Sandbox API Token | |
| apiEndpoint | All URLs referenced in the Sitecore CDP v2.1 API data model begin with the following base URL: https://{apiEndpoint}/v2 | api.boxever.com |
| pointOfSale | A POS is a specific storefront your organization sells products. Sitecore CDP supports multiple storefronts certain requests need to target the correct storefront. | betaSpinAir |
| currencyCode | The type of currency used for requests. String value (3 letter ISO 4217). | “EUR”, “USD”, “GBP” |
| language | The language captured on each page the guest visited. | “EN”, “FR”, “DE” |
| channel | The channel captured on each page the guest visited. | “WEB”, “MOBILE_WEB”, “MOBILE_APP” |
| guestRef | The unique ID of the guest generated by Sitecore CDP. | guid |
| guestEmail | The email address for the guest. | |
| identifiersProvider | The provider of the identifiers. | ProfileSystem |
| identifiersId | The ID of the identifiers. | guid |
| dataExtensionName | The data extension name. | extEmailPreferences |
| dataExtensionRef | The reference of the data extension. | guid |
| orderRef | The reference of the order. | guid |
| orderItemRef | The reference of the order item. | guid |
| orderContactRef | The reference of the contact on the order. | guid |
| orderConsumerRef | The reference of the consumer on the order. | guid |
| batchFlowsJobRef | The reference of the Batch flow. | guid |
| decisionModelDefinitionRef | The reference of the Decision Model Definition. | guid |
| decisionModelDefinitionRevision | The reference of the Decision Model Definition Revisions. | guid |
| decisionModelVariantRef | The reference of the Decision Model Variant. | guid |
| decisionModelVariantRevision | The reference of the Decision Model Variant Revision. | guid |
| connectionRef | The 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.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 is10).
- 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.
- Locate Batch Flows Job – to return a list of batch jobs for a flow.
- Retrieve Batch Flow Job – etrieve a batch job for a flow.
- Retrieve Batch Flows Output – to retrieve the signed URLs.
Decisions
A Decision data model object is the parent for decision Model variants. The following methods allow you to manipulate the decision Model.
- Retrieve decision data model – a get request to retrieve decision model definition.
- Retrieve decision model definition reference – a get request to retrieve decision model definition reference.
- Create decision model definitions reference – a post request to create decision model definitions reference function to create a unique decision model reference.
- Update decision model definitions reference – a put request to update decision model definitions reference model. Using the decisionModelDefinitionRef.
- Retrieve revisions of a decision model definition – a get request to return the revisions of a decision model definition. To do this, you need the decisionModelDefinitionRef.
- Retrieve variants of a decision model reference – a get request to return the variants of a decision model using the decisionModelDefinitionRef.
- Retrieve decision model definitions revision record -a get request to return the variants of a decision model. Using the decisionModelDefinitionRef and the revision number.
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.
- Retrieve Connections – a get request that retrieves a list of connections.
- Create Connections – a post request to create a new connection.
- Retrieve Connection – a get request passing the ref parameter for an existing connection, retrieves a single connection.
- Update Connection – a put request updates a connections attributes.
- Test Connection – a post request allows you to test a connection.
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.
Useful Links
- Introduction to Sitecore CDP 2.1 data model
- Overview of Sitecore CDP REST APIs
- Using Sitecore CDP REST APIs
- Sitecore CDP Base Url
- Authentication for the Sitecore CDP REST APIs
- My Sitecore CDP Postman Collection
Hope this is helpful!
Neil Killen 