> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-engage/19.latest/developers/headless/headless-example.md).

# Headless Example

This article shows how to personalize content using the Umbraco Engage Headless API and Umbraco’s Content Delivery API.

This article shows how to use the Umbraco Engage Headless API with Umbraco Content Delivery API.

## Setting up a Personalization Segment

1. Go to the **Engage** > **Personalization** section.
2. Navigate to the **Segments** tab.
3. Click **Add new segment**.
   * Give the segment a name. For example: *Morning People*.
   * And a description such as *For people who like to visit us in the morning*.
   * Set the segment type to **Core** as this is not temporary and is tied to an end date for a campaign.
   * Select the **Time of day** parameter and configure it to **Include** times from **00:00** to **12:00** as it is a 24-hour clock.

For more information, see the [Personalization](https://docs.umbraco.com/umbraco-engage/19.latest/developers/personalization.md) documentation.

<figure><img src="https://2694658632-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdeWIZl0opa4iOLq36gzS%2Fuploads%2Fgit-blob-071f9b9bbcf6622ed65706d8d7d78733238cf613%2FPersonalization-add-new-segment-v16.png?alt=media" alt="Edit segment view."><figcaption><p>Add new segment</p></figcaption></figure>

### Creating a Document Type for Personalization

1. Navigate to **Settings**.
2. Click **Create a New Document Type**.
3. Enable **Allow Segmentation** under **Settings**.
4. Save the Document Type.
5. Add a new property, such as a **Header**, using a **Textstring** property editor.
   * Ensure **Shared across segments** is turned off for this property, so it can vary per segment.
6. Create a piece of content using this new Document Type to query and request it using the Umbraco Content Delivery API
   * For this example, create this piece of content at the root.

### Creating Personalized Content

1. Open the created content and go to **Personalization**.
2. Click **Create personalized variant**.
3. Set the following in the **Create personalized variant** panel:
   * Choose the segment **Morning People** we added earlier.
   * Give it a name and a meaningful description such as **Home Page for Morning People**.

<figure><img src="https://2694658632-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdeWIZl0opa4iOLq36gzS%2Fuploads%2Fgit-blob-904419e84ab18d77be50873daf1df158babe5fd6%2Fimage%20(4)%20(4).png?alt=media" alt="Add new variant."><figcaption><p>Add new variant.</p></figcaption></figure>

4. After adding the variant we will return to the content node in split-view mode.
5. We can then add a different piece of content we want to return in our Header property specific to morning people such as *Hello you early risers.*
6. Save and publish the node with the variant content.

<figure><img src="https://2694658632-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdeWIZl0opa4iOLq36gzS%2Fuploads%2Fgit-blob-650b8632771bbbe00dfd05b2b30b505f30fd7326%2Fimage%20(5)%20(4).png?alt=media" alt="split-view."><figcaption><p>split-view.</p></figcaption></figure>

### Using the Content Delivery API

Let us use the Swagger development tool to make requests to the Umbraco Content Delivery API and Umbraco Engage Headless API.

1. Navigate to the swagger endpoint of your site **/umbraco/swagger**.
2. Select **Umbraco Delivery API** from the dropdown.
3. Expand `/umbraco/delivery/api/v1/content/item/{path}`:
   * Click **Try it out**.
   * For the path parameter, enter `/` for the example piece of content we created at the root of our site - alternatively, specify the correct URL path to the content.
   * Set the **API-Key** parameter if your Umbraco application requires [Public Access](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#additional-configuration) this can be toggled with the configuration value `Umbraco:CMS:DeliveryAPI:PublicAccess`
4. You should view the JSON result of the content node, including the default header value.
5. Navigate to **Umbraco Engage API** from the definitions dropdown.
6. Expand `/umbraco/engage/api/v1/analytics/pageview/trackpageview/client`:
   * Click **Try it out**.
   * Modify the JSON body, setting the URL to the page visited earlier. With the content delivery API above, leave the other property **referrerUrl** empty.
   * Repeat the earlier steps to fetch the content by its path. The JSON of the content node and the header property now contains our personalized content **Hello you early risers**
     * Remember it will only show different content if we view the page before midday.

<figure><img src="https://2694658632-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdeWIZl0opa4iOLq36gzS%2Fuploads%2Fgit-blob-96836651d2dd317a860690aa3d3a4bed05aecab3%2Fimage%20(6)%20(4).png?alt=media" alt="Response body."><figcaption><p>Response body.</p></figcaption></figure>

{% hint style="info" %}
Umbraco Engage is licensed to individual domains. It requires the Host Header to match one of the registered licensed domains for personalization and A/B Testing to work.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umbraco.com/umbraco-engage/19.latest/developers/headless/headless-example.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
