# Guest API Use the Guest REST API to create, retrieve, update, and delete guest data in Sitecore CDP. This REST API lets you interact with: - The guest object. The guest object is the core entity of Sitecore CDP. It stores the personal data of a customer, and all relevant transactional and behavioral data is linked in a guest profile. - The guest data extension object. A guest data extension is an object that lets you specify any key-value pairs you want. Guest data extensions are optional and enable your organization to capture more robust information about your guests. After capturing guest information, Sitecore CDP users can: - View the captured data in the [guest profile](https://doc.sitecore.com/cdp/en/users/sitecore-cdp/view-a-guest-profile-in-sitecore-cdp.html). - Use the captured data to [build segments of guests](https://doc.sitecore.com/cdp/en/users/sitecore-cdp/introduction-to-batch-segmentation.html). - [Export audience data](https://doc.sitecore.com/cdp/en/users/sitecore-cdp/audience-export.html) to activate audiences outside Sitecore CDP. Note the following: - To use this REST API, you must [authenticate](https://doc.sitecore.com/cdp/en/developers/api/authentication-and-authorization.html) your API requests. - All API requests are made in your production environment. - This reference documentation describes Sitecore CDP functionality for data model 2.1. For more information, see the [official Sitecore CDP developer documentation](https://doc.sitecore.com/cdp/en/developers/api/index-en.html). ## Authentication The Guest REST API uses basic authentication. Basic authentication involves sending a user name and a password with every request. To find your user name and password, in Sitecore CDP, on the navigation pane, click **Settings** > **API access**: - The user name is the **Client key**. - The password is the **API token**. You must include the user name and password in every request you make. For example: ``` curl -X GET '{baseURL}/v2/guests' \ -u '{YOUR_USERNAME}:{YOUR_PASSWORD}' \ -H 'Accept: application/json' Version: v2.1 License: Apache 2.0 Metadata: - product: CDP ## Servers Production server AP ``` https://api-engage-ap.sitecorecloud.io ``` Production server EU ``` https://api-engage-eu.sitecorecloud.io ``` Production server JP ``` https://api-engage-jpe.sitecorecloud.io ``` Production server US ``` https://api-engage-us.sitecorecloud.io ``` ## Security ### BasicAuth Type: http Scheme: basic ### BearerToken Type: http Scheme: bearer Bearer Format: JWT ## Download OpenAPI description [Guest API](https://api-docs.sitecore.com/_bundle/cdp/guest-rest-api/index.yaml) ## Guest The guest object is the core entity of Sitecore CDP. It stores the personal data of a customer, and all relevant transactional and behavioral data is linked in a guest profile. To get started with this API, create a guest then find it in Sitecore CDP. ### Create a guest - [POST /v2.1/guests](https://api-docs.sitecore.com/cdp/guest-rest-api/guest/createguest.md): Creates a guest. The REST API does not check whether a guest already exists in Sitecore CDP when you create a guest. To avoid creating duplicates, first retrieve guests by their email address or other identifying information. In the response, the ref key contains the guest reference. ## Find the guest in Sitecore CDP You can also use the guest reference to find data about the guest in Sitecore CDP. In Sitecore CDP, click Guests, and select the Guest type: All filter. Then, in the search dropdown, select Guest reference and then enter the guest reference in the search field. Then, Sitecore CDP lists the guest profile for the guest. ### Retrieve guests - [GET /v2.1/guests](https://api-docs.sitecore.com/cdp/guest-rest-api/guest/retrieveguests.md): Retrieves a maximum of 100 of the most recent guests. We recommend that you retrieve guests by their email address or other identifying information using query parameters before you create a guest. This lets you check if a certain guest already exists in Sitecore CDP. If the guest exists, avoid creating duplicates. Instead, update the existing guest. ### Query parameters You can use the following query parameters to retrieve guests by exact match, using some of the following identifying information: - email - orderReferenceId - orderRef - identifiers.provider plus identifiers.id Alternatively, you can use the expand=true query parameter to retrieve guests with all their key-value pairs listed. #### Examples Here's an example of how to use the email query parameter to retrieve guests by their email address: {baseURL}/v2.1/guests?email=john.doe@gmail.com" Here's an example of how to use the identifiers.provider and the identifiers.id query parameters to retrieve guests by their identifiers: {baseURL}/v2.1/guests?identifiers.provider=ProfileSystem&identifiers.id=B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41" If any of this returns a guest, avoid creating another guest with the same identifying information. Instead, update the existing guest. ### Guest reference In the response, in items.href, the guest reference is the string that follows the final slash&: \"href\": \"{baseURL}/v2.1/guests/{guestRef}" Example guest reference: f7aabbca-1c1b-4fc2-be72-3e16294a4f03 Use the guest reference to interact with the full guest record, for example, to retrieve or update it. You can also use the guest reference to find data about the guest in Sitecore CDP. In Sitecore CDP, click Guests. In the Search field, enter the guest reference, then click the Guest type: All filter. Then, Sitecore CDP lists the guest profile for the guest. ### Retrieve a guest - [GET /v2.1/guests/{guestRef}](https://api-docs.sitecore.com/cdp/guest-rest-api/guest/retrieveguest.md): Retrieves the full guest record of a guest, including any guest data extensions. ### Update a guest - [PUT /v2.1/guests/{guestRef}](https://api-docs.sitecore.com/cdp/guest-rest-api/guest/putguest.md): Fully updates a guest, replacing the entire resource including all the key-value pairs with the data you send in the request. To update certain key-value pairs only, use the Partially update a guest endpoint instead. ### Partially update a guest - [PATCH /v2.1/guests/{guestRef}](https://api-docs.sitecore.com/cdp/guest-rest-api/guest/updateguests.md): Partially updates a guest, replacing only those fields in the resource that you provide in the request. For example, you can use this request to update the guest's array of phone numbers when they enter a new one. ### Delete a guest - [DELETE /v2.1/guests/{guestRef}](https://api-docs.sitecore.com/cdp/guest-rest-api/guest/deleteguest.md): Deletes a guest record and all entities associated with the guest including orders, sessions, and events. This is an irreversible operation. After you delete a guest record, you cannot retrieve the guest record or any related entities. ## Guest data extension A guest data extension is an object that lets you specify any key-value pairs you want. Guest data extensions are optional and enable your organization to capture more robust information about your guests. To get started with this API, create a data extension for the guest you previously created, then find the data in Sitecore CDP in the guest profile. ### Create a data extension - [POST /v2.1/guests/{guestRef}/extensions](https://api-docs.sitecore.com/cdp/guest-rest-api/guest-data-extension/createguestdataextension.md): Creates a data extension for a guest. You can create up to six data extensions. To avoid creating key-value pairs in a data extension that already exist within a guest profile, first retrieve a guest's collection of data extensions to check that the keys you intend to create are unique. ### Creating the request body In the request body, you must provide one object. This object represents the data extension. Note the following about the object: - Can contain primitive values only. You cannot nest objects. If you need to group key-value pairs, use prefixes for the key names. - Can contain a maximum of 100 key-value pairs. - Must contain the name key. This is the name of the data extension. - If you send extension data from one source, set the value for name to ext. - If you send extension data from multiple sources, you can create up to six data extensions by setting the value for name to one of the following: ext, ext1, ext2, ext3, ext4, ext5. - The other key-value pairs you include in the object become the extension data. For example, if you include "loyaltyTier": "level2" in the object, Loyalty Tier with the value of level2 becomes extension data. - Supported data types for the values: - string, for example "level2" - boolean, for example true - integer, for example 9 - floating-point number, for example 99.9 #### Naming keys The keys you enter in the request body must be: - Alphanumeric A-Z,a-z,0-9] as per the [JSON RFC 7159 specification. - In camel case. - Unique across all data extensions within a guest profile. For example, if ext contains the vipMember key, you must not use that key in any other data extensions for the same guest. ### Example request body Here's an example request body: { "name": "ext", "vipMember": true, "loyaltyTier": "level2", "rewardBalance": 5012.25, "loyaltyNumber": 3452 } This creates four key-value pairs in the ext data extension for the guest. ### Finding the data in Sitecore CDP You can find the created data in Sitecore CDP by clicking Guests > the guest profile you created the data for > Properties > Additional information: - The ext data displays in Data extension group. - The ext1 data displays in Data extension group 1. - The ext2 data displays in Data extension group 2. - The ext3 data displays in Data extension group 3. - The ext4 data displays in Data extension group 4. - The ext5 data displays in Data extension group 5. ### Multiple sources You can send extension data from multiple sources. For example, your organization might want to send extension data both from a loyalty system to capture loyalty data, and from a Customer Relationship Management (CRM) system to capture email preferences, alternative mailing addresses, and so on. To send data from multiple sources, we recommend that you use a different data extension name for each source system. For example, use the ext data extension for the loyalty system data, and use the ext1 data extension for the CRM data. ### Retrieve a guest's collection of data extensions - [GET /v2.1/guests/{guestRef}/extensions](https://api-docs.sitecore.com/cdp/guest-rest-api/guest-data-extension/retrieveguestdataextensions.md): Retrieves the URLs for each of the guest's data extensions. We recommend that you retrieve the URLs using the expand=true query parameter to check that the keys you intend to create when you Create a data extension are unique. This is because keys must be unique across all data extensions within a guest profile. In the response, each URL in items.href corresponds to one data extension. Use this URL to interact with the guest's data extension, for example, to retrieve or update it. ### Retrieve a data extension - [GET /v2.1/guests/{guestRef}/extensions/{dataExtensionName}](https://api-docs.sitecore.com/cdp/guest-rest-api/guest-data-extension/retrieveguestdataextension.md): Retrieves a data extension for a guest. ### Update a data extension - [PUT /v2.1/guests/{guestRef}/extensions/{dataExtensionName}](https://api-docs.sitecore.com/cdp/guest-rest-api/guest-data-extension/putguestdataextension.md): Fully updates a data extension for a guest, replacing the entire resource including all the key-value pairs with the data you send in the request. To update certain key-value pairs only, use the Partially update a data extension endpoint instead. ### Partially update a data extension - [PATCH /v2.1/guests/{guestRef}/extensions/{dataExtensionName}](https://api-docs.sitecore.com/cdp/guest-rest-api/guest-data-extension/updateguestdataextension.md): Partially updates a data extension for a guest, replacing only those key-value pairs in the resource that you provide in the request. If multiple source systems use the same data extension, use this endpoint to safely update the key-value pairs from a specific source system without accidentally overwriting the key-value pairs from other source systems. ### Delete a data extension - [DELETE /v2.1/guests/{guestRef}/extensions/{dataExtensionName}](https://api-docs.sitecore.com/cdp/guest-rest-api/guest-data-extension/deleteguestdataextension.md): Deletes the data extension for a guest, including all the key-value pairs in the data extension. To delete certain key-value pairs only, use the Delete key-value pairs from a data extension endpoint instead. ### Delete key-value pairs from a data extension - [DELETE /v2.1/guests/{guestRef}/extensions/{dataExtensionName}/fields](https://api-docs.sitecore.com/cdp/guest-rest-api/guest-data-extension/deleteguestdataextensionfields.md): Deletes the key-value pairs you provide in the name query parameter from a data extension for a guest. For example, if your data extension contains the vipMember and loyaltyMember keys, you can delete both keys and their values by making the following request: {baseURL}/v2.1/guests/{guestRef}/extensions/{dataExtensionName}/fields?name=vipMember|loyaltyMember If you don't provide the query parameter, this operation will empty the data extension: the data extension itself will not be deleted, but all the key-value pairs in it will.