# Bloomreach

This Integration requires Fides Cloud or Fides Enterprise. For more information, [talk to our solutions team. (opens in a new tab)](/content/speak-with-us?utm_source=docs-site/index.html)

[Bloomreach (opens in a new tab)](https://www.bloomreach.com/) is a digital experience platform that helps companies deliver personalized customer experiences through email marketing, data management, and e-commerce optimization.

## Prerequisites

In order to [integrate](/content/docs/integrations/index.html) with Bloomreach, you'll need to collect the following information:

Your Bloomreach API should be of Private access type,

| Name | Description |
| :-- | :-- |
| **Domain** | Your Bloomreach API URL (default: `api.exponea.com`). You can find this in your Bloomreach account under Project Settings > Access Management > API |
| **API Key**\* | Your Bloomreach API key. You can find this in your Bloomreach account under Project Settings > Access Management > API |
| **API Secret**\* | Your Bloomreach API secret. You can find this in your Bloomreach account under Project Settings > Access Management > API |
| **Project Token**\* | Your Bloomreach project token. You can find this in your Bloomreach account under Project Settings > Access Management > API |
| **Bloomreach Customer ID Name** | The name of the hard_id/soft_id for customers in Bloomreach (default: `registered`) |
| **Bloomreach Identity Key**\* | The name of the identity (email or external_id) used in the privacy request that maps to the Bloomreach customer ID |

Your Bloomreach API credentials will need to have the following scopes: `Events > Consent(get/set)`, `GDPR > Anonymize customer, Export customer`, `Customer Properties > Others > Phone(get/set)`, `Customer Properties > Others > Email(get/set)`

## Integrating with Bloomreach

To integrate an existing system with Bloomreach:

1. Navigate to **Data map** → **View Systems** and choose the system that you want to connect.
2. Click on the **Integrations** tab.
3. Pick the vendor or system type that you want to integrate with from the **Connection type** drop-down menu.
4. Complete the required fields for the integration and click **Save**.

You may confirm your connection is working using the **Test connection** button, if desired.

To learn more, please see our guide for [Managing Integrations](/content/docs/integrations/guides/manage-integrations/index.html).

When propagating consent preferences, if the user does not already exist in Bloomreach, Fides will automatically create the user in Bloomreach before applying their consent preferences.

### Bidirectional Consent

Before configuring bidirectional consent, confirm that the Bloomreach system shares a `data_use` with each of the configured privacy notices. See [Ensure data use overlap](/content/docs/consent/guides/bidirectional-consent#ensure-data-use-overlap-between-systems-and-privacy-notices/index.html) for details.

Bloomreach also supports [bidirectional consent](/content/docs/consent/guides/bidirectional-consent/index.html). To configure this, click on the **Bidirectional consent** accordion under the Bloomreach configuration form. This section allows you to map Privacy Notices in Fides to **Consent Categories** in Bloomreach. In the example below, setting **Marketing** for the **Marketing information** consent category will automatically subscribe and unsubscribe the user from that category if they opt-in or out of the **Marketing** privacy notice in Fides.

Consent changes should only be made through events. Changes made through the Bloomreach admin dashboard won't trigger a consent event and will cause Fides to be out of sync.

### Consent webhooks

Bloomreach supports webhooks that can be configured to automatically forward consent preference changes to Fides. When users update their consent preferences directly in Bloomreach, these changes can be automatically synchronized with Fides.

To set up consent webhooks we will need to setup an Authentication integration and a Bloomreach scenario.

#### Authentication setup

Fides supports two authentication methods for consent webhooks. **OAuth2 client credentials (recommended)**, which handle token refresh automatically, and static Bearer tokens that require manual token rotation every 90 days.

##### Option A: OAuth2 client credentials (recommended)

With OAuth2 client credentials, Bloomreach automatically obtains and refreshes short-lived access tokens from Fides. No manual token rotation is required.

1. Generate OAuth2 client credentials by calling the Fides API:

```
POST /api/v1/plus/connection/{connection_key}/consent-webhook/oauth2-client
```

The response contains `client_id` and `client_secret`. Save these values — the `client_secret` is only shown once.

2. On your Bloomreach admin dashboard navigate to **Data & Assets > Integrations** and click `+ Add new integration`.

3. Search for `OAuth 2.0` and click on `+ Add integration`.

4. Configure the OAuth 2.0 integration:
   - **Token endpoint URL**: `https://{your-fides-url}/api/v1/oauth/token`
   - **Client ID**: Use the `client_id` from step 1
   - **Client Secret**: Use the `client_secret` from step 1
   - **Client Authentication Method**: Select `Auth Header` or `Body parameters`
5. If your Fides URL differs from the token endpoint domain, enable **"Allow webhooks from domains other than the token's endpoint"** and add your Fides base URL to the allowed domains list.

6. Click **Save Integration**.

To generate new credentials (e.g., if the secret is lost), call the same endpoint again. The previous credentials will be invalidated.

##### Option B: Static Bearer token (deprecated)

**Deprecated.** Static Bearer tokens expire after 90 days and must be manually refreshed. Consider using OAuth2 client credentials (Option A) instead.

1. On your Bloomreach admin dashboard navigate to Data & Assets > Integrations and click `+ Add new integration`
2. Search for `HTTP Authentication schemas` and click on `+ Add integration`

3. Select custom headers. Endpoint: `your_fides_url`, Key: `Authorization`, Value: `Bearer {your_consent_webhook_token}`.

4. Click on `Save Integration`.

#### Scenario setup

Once you have configured authentication (either OAuth2 or static token), create a Bloomreach scenario to forward consent events:

5. Navigate to `Campaigns > Scenario` and click on `+ New Scenario`. On the pop up window click `Create New Scenario`

6. From the selection tab on the right grab the `On event` item located on the triggers section and drop it on the canvas.

7. Click on the added `On event` item and select `consent` as the event trigger.

8. Click on `Done`.
9. From the selection tab on the right grab the `Webhook` item located on the actions section and drop it on the canvas.

10. Click on the newly added webhook item and navigate to `Settings`.
11. Activate the Authentication option and select your recently created authentication from step 4.
12. On the `Other` section click on the `Consent Category` dropdown and select `General Consent`.

13. Navigate back to the `Editor` tab of the webhook.

- You'll notice that the base url from the webhook is now the url that was setup on the authentication integration. In this example the `fides_url` is an ngrok endpoint.
- The endpoint method should be set to `POST`.
- The dropdown to the right of the `Endpoint` header should be set to `Do not process response`.
- On the empty textbox to the right of our base url set the endpoint to `/api/v1/plus/connection/{{integration_identifier}}/consent-webhook`
- The payload must contain the following parameters. (Note that the customer_id can be either a soft_id or a hard_id in this example we set it to the hard_id `registered`)

```
{
 "customer_id": "{{ customer_ids.registered }}",
 "email": "{{ customer.email }}",
 "category": "{{ event.category }}",
 "action": "{{ event.action }}"
}
```

The webhook endpoint expects a specific payload format. Make sure your Bloomreach webhook configuration sends the customer ID, email, category, and action fields as required.

16. You may now click on `Test Webhook` to verify that the payload is being received by Fides.
17. Click on `Done`.

18. Click on `Save` and then `Start` your scenario.

By configuring this scenario. Any consent event that happens inside of Bloomreach will be automatically forwarded and stored within Fides.

## Technical detail

Fides utilizes _API endpoints_ to access the _API service_ for a SaaS application. An _API service_ is the programmatic interface through which Fides can query and update data within an application to access, rectify, or delete personal information. Each SaaS tool will have a unique set of endpoints to enable privacy functions.

### Bloomreach Endpoints

In the table below, you can find which endpoints are used for each type of privacy function. Clicking on the endpoint will take you to the documentation for that endpoint.

| Privacy function | Endpoint | Description |
| --- | --- | --- |
| **Access Requests** | [Export Customer (opens in a new tab)](https://documentation.bloomreach.com/engagement/reference/export-a-customer-2) | Returns information about a customer and their data |
| **Update or Delete Requests** | [Anonymize Customer (opens in a new tab)](https://documentation.bloomreach.com/engagement/reference/anonymize-a-customer-2) | Used to anonymize/delete a customer's data |
| **Consent Access Requests** | [Get Consent Categories (opens in a new tab)](https://documentation.bloomreach.com/engagement/reference/get-consent-categories-2) | Used to retrieve all available consent categories |
| **Consent Access Requests** | [Get Customer Attributes (opens in a new tab)](https://documentation.bloomreach.com/engagement/reference/customer-attributes-2) | Used to access a customer's current consent preferences |
| **Consent Update Requests** | [Track Consent Events (opens in a new tab)](https://documentation.bloomreach.com/engagement/reference/batch-commands-2) | Used to update a customer's consent preferences |