---
title: "Connect Sitecore Personalize to an external destination"
slug: "connect-sitecore-personalize-to-an-external-destination"
abstract: "You can set up a connection from Sitecore Personalize to an external destination such as Sitecore Send or an Email Service Provider (ESP)."
---
# Connect Sitecore Personalize to an external destination

This walkthrough describes how to set up a connection from Sitecore Personalize to an external destination. In Sitecore Personalize, to begin creating a triggered [experiment](https://doc.sitecore.com/personalize/en/users/sitecore-personalize/introduction-to-experiments-in-sitecore-personalize/introduction-to-triggered-experiments-in-sitecore-personalize/create-a-triggered-experiment.html "Create a triggered experiment") or [experience](https://doc.sitecore.com/personalize/en/users/sitecore-personalize/introduction-to-experiences/introduction-to-triggered-experiences-in-sitecore-personalize/create-a-triggered-experience.html "Create a triggered experience"), you must first select a connection for sending the personalized data. You can set up a connection to an external destination, such as an Email Service Provider (ESP) or a REST API endpoint. This connection provides a way to send the output of a triggered experiment or experience to the chosen destination. For example, you might use a connection to an ESP when configuring an abandoned cart email message. Similarly, you can create a connection to the Guest REST API for updating a guest's data extension after an order is created.

Team members with a *User*, *Developer*, or *Admin* role in Sitecore Cloud Portal can connect to an external destination.

This walkthrough describes how to:

- Create a new connection
- Authenticate the connection
- Configure the request
- Review and save the connection

## Create a new connection

The first step to connect Sitecore Personalize to an external destination is to create a new connection to that destination.

To create a new connection:

1. On the navigation menu, click **Developer center** > **Connections**.
2. On the **Connections** page, click **Add connection** > **Destination**.
3. On the **Name & Describe** page, complete the following fields:

    ![The Name & Describe page when creating a new connection in Sitecore Personalize.](https://doc.sitecore.com/api/markdown-image/personalize/en/users/sitecore-personalize/images/ConnectionName.png)

    - **Name** - enter a unique, intuitive name for the destination.
    - **Description** - enter a concise description of the destination.
    - **Icon** - from the drop-down list, select the icon that the user will see when they create a triggered experiment or experience.
4. Click **Next** to proceed to the **Authenticate** page.

## Authenticate the connection

After you name the connection, you must choose how you want to authenticate the connection to the external destination. We recommend that you use OAuth 2, when possible.

To authenticate the connection to the destination:

1. On the **Authenticate** page, click one of the following authentication methods and complete the required fields:

    ![The Authenticate page lets you select the authentication method to connect to an external destination.](https://doc.sitecore.com/api/markdown-image/personalize/en/users/sitecore-personalize/images/ConnectionAuthenticate.png)

    - **OAuth 2**:
        - **Access Token URL** - enter the URL to the access token of the destination. The access token is generated by the destination system. The access token must use an HTTPS URL. This ensures you are using a secure connection.
        - **Authentication option** - select the **Header** option to pass the authentication credentials in the header or select the **Body** option to pass the authentication credentials in the body of the request.
        - **Client ID** - enter the client ID of the destination.
        - **Client Secret** - enter the client secret of the destination.
        - **Headers** - optionally, click **Show headers** and enter the key in the first field and the value in the second field. To enter additional headers, click **Add Headers**. If you selected **Header** for the **Authentication option**, you must enter the authentication parameters and values here.
        - **URL encoded form** - optionally, click **Show URL encoded form** and enter the key in the first field and the value in the second field. To enter additional items, click **Add form item**. This option enables you to convert keys and values into a valid URL format that you can send to Sitecore Personalize.
        - **Configure with Mutual TLS** - click to enable Mutual Transport Layer Security (mTLS). This lets Sitecore Personalize and the destination that you're connecting to authenticate each other using the TLS protocol.

            To view the Sitecore Personalize mTLS JSON Web Key Set (JWKS) endpoint, click the ![pers_JWTS.png](https://doc.sitecore.com/api/markdown-image/personalize/en/users/sitecore-personalize/images/pers_JWTS.png) icon. The JWKS is a set of keys containing the public keys used to verify any JSON Web Tokens (JWT).

    - **Basic**:
        - **Username** - enter the username for authenticating credentials to the destination.
        - **Password** - enter the password for authenticating credentials to the destination.
    - **None** - this is only used for public APIs and is not recommended for connecting to an external destination like an ESP.
2. Click **Next** to proceed to the **Configure Request** page.

## Configure the request

When you configure the request, you can set the headers and parameters that represent the metadata associated with the REST API request and response. Headers and parameters contain information that can help you troubleshoot issues.

To configure the request:

1. On the **Configure Request** page, in the **Request URL** drop-down list, select one of the following HTTP methods to use in the request:

    ![The Configure Request page lets you set the request method, URL, headers, and body to use for the external destination.](https://doc.sitecore.com/api/markdown-image/personalize/en/users/sitecore-personalize/images/ConnectionRequest.png)

    - **POST** - use this method to send data to create a child resource under the resource collection.
    - **PUT** - use this method to send data for updating an existing resource. Alternatively, if the resource does not exist yet, it creates a new one.
    - **PATCH** - use this method to make partial updates on an existing resource. It allows you to modify a single value or a set of values within a resource without the need to resend the entire resource.
    - **DELETE** - use this method to remove an existing resource.
2. In the **Request URL** field, enter the URL to send the destination request. 

    You can include variables in the URL by using the FreeMarker variable notation `${}`. For example, `https://example.com/api/emails/${email}?limit=${num}`.

    > [!important]
    > When setting the request URL, headers, or request body in your connection, you cannot use variables from the [guest data object](https://doc.sitecore.com/personalize/en/users/sitecore-personalize/connecting-sitecore-personalize-to-an-external-system/use-guest-data-in-the-api-request-for-a-triggered-experiment.html "Use guest data in the API request for a triggered experiment"), such as `${guest.email}`. Unlike in experiences or experiments, FreeMarker does not recognize these objects and their properties at runtime, which might result in an exception.

3. Click **Show Default Headers** to display the default headers and parameters for the destination:
    - **Accept** - this field displays **application/json** to specify that JSON is the accepted format for the response.
    - **Accept-Encoding** - this field displays **gzip** to specify that gzip is the accepted compression type.
    - **Content-Type** - this field displays **application/json** to specify that JSON is the format of the content sent in the request.
4. To add additional headers, click **Add Header**. An additional row displays to enter the following:
    - **Key** - enter the header name.
    - **Value** - enter the parameter.

    You can include variables in header names and parameters by using the FreeMarker variable notation `${}`.

5. To configure the connection timeout, fill in the following fields:
    - **Connection Timeout (ms)** - in the drop-down list, select the number of milliseconds of inactivity after which the connection will close. The default is 1000.
    - **Read Timeout (ms)** - in the drop-down list, select the number of milliseconds between connectivity being established and not receiving a response from the server after which the connection will close. The default is 1000."
6. In the **Request** field, enter a sample JSON request to test your connection. Ensure that the JSON is valid. Don't send real guest contact details in the sample request.

    You can include variables in the sample request by using the FreeMarker variable notation wrapped in double quotes `"${}"`. For example, `"name": "${name}"` or `"email": "${email}"`.

7. Click **Test Request**. If you included variables in the request URL, header, or body, such as `${email}`, enter test values for them. Then click **Run Test**.

    The results of the test display in the **Response** field with the relevant status code.

8. Click **Next** to proceed to the **Review & Save** page.

## Review and save the connection

You must continue to this page otherwise the connection that you have set up in the previous pages will not be saved and you will have to start over creating a connection.

To save the connection:

1. On the **Review & Save** page, you can see a consolidated view of your connection. Check that the external destination has been set up correctly.

    ![The Review & Save page provides a summary of your external destination.](https://doc.sitecore.com/api/markdown-image/personalize/en/users/sitecore-personalize/images/ConnectionSave.png)

2. To return to a previous page to edit the setup details, click the relevant tab at the top of the page, or click **Back**.
3. When you are ready to finalize the connection setup, click **Save**.

    > [!warning]
    > After you save, you cannot edit the connection. Review it before saving.

    You can now use this connection when you're creating a triggered [experiment](https://doc.sitecore.com/personalize/en/users/sitecore-personalize/introduction-to-experiments-in-sitecore-personalize/introduction-to-triggered-experiments-in-sitecore-personalize/create-a-triggered-experiment.html "Create a triggered experiment") or [experience](https://doc.sitecore.com/personalize/en/users/sitecore-personalize/introduction-to-experiences/introduction-to-triggered-experiences-in-sitecore-personalize/create-a-triggered-experience.html "Create a triggered experience").