> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retention Science

> AI-driven email marketing automation

## Overview

You want to send relevant, timely emails to your customers, and doing so heavily relies on the accuracy and freshness of the data in Retention Science. By automatically syncing customer data from your data warehouse into Retention Science, you no longer need to worry about data consistency because data is no longer flowing in from multiple sources in different formats, and your team can focus on drafting engaging emails and delivering delightful experiences.

## Supported syncing

| Type | Description | Supported Sync Modes | API Reference |
| - | - | - | - |
| **Users** | Sync data from any source to Users in Retention Science | Upsert, Update | [Users docs](https://developer.retentionscience.com/?data/v3.0.0#tag/Users) |
| **Lists** | Add or remove users from a list in Retention Science | Add, Remove | [Lists docs](https://developer.retentionscience.com/?data/v3.0.0#tag/Lists) |

For more information about sync modes, refer to the [sync modes](https://docs.hightouch.com/syncs/types-and-modes.md#sync-modes) docs.

## Connect to Retention Science

Go to the [**Destinations** overview page](https://app.hightouch.com/destinations?from=docs) and click the **Add destination**
button. Select **Retention Science** and click **Continue**. You can then authenticate Hightouch to **Retention Science** by entering a Retention Science API key.

To get your API Key, go to your ReSci dashboard. Click on the dropdown menu in the upper right hand corner and then select **API settings**. Click **API Password** to reveal your key.

## Sync configuration

Once you've set up your Retention Science destination and have a [model](https://docs.hightouch.com/getting-started/concepts.md#models) to pull
data from, you can set up your sync configuration to begin syncing data. Go to the [**Syncs** overview
page](https://app.hightouch.com/syncs?from=docs) and click the **Add sync** button to begin. Then, select the relevant model and
the Retention Science destination you want to sync to.

### Users

Sync data from any source to Users in Retention Science.

#### Record matching

You can match rows in your model with user in Retention Science on any of the following fields:

* **Email**
* **Record ID**: this is also called `id` or `record_id`

#### Field mapping

You can sync columns from your source to the following columns in Retention Science user:

* **Full Name**: User's full name (first and last)
* **Address Line 1**
* **Address Line 2**
* **City**
* **State**
* **Zip code**
* **Country**
* **Phone number**
* **Year of birth**
* **Gender**
* **Registartion Source**: The source of the user's registration typically used for user segmentation
* **Birthday**: User's full birthday in `YYYY-MM-DD` format
* **Send Transactional Welcome**: When `true`, ReSci sends an email to new users when there is an available template in the Welcome stage. When `false`, ReSci doesn't send welcome emails to new users. No emails are sent to existing users who are updated. The default for this setting is `true`.
* **Merge Before Upsert**: By default, a request containing a `record_id` and `email` that match two distinct users will result in an API error, with an error message stating that we cannot uniquely identify which user to update. If you set the `merge_before_upsert` field to `true`, ReSci merges these two users into one. The default for this setting is `false`.
* **Date unsubscribed**: The User's unsubscribe date. Setting this field unsubscribes a user from email. This field accepts `YYYY-MM-DD hh:mm:ss` (24-hour clock) in UTC. Note that passing a null value doesn't re-subscribe a previously unsubscribed user. If a user is unsubscribed, ReSci ignores null values.
* **Account Created On**: User's signup date in format `YYYY-MM-DD`. If this field and existing user **Account Created On** value differ, ReSci chooses the oldest date between the two.
* **Timestamps**: The timestamp is the date and time of when the data changed for a specific plugin fields. ReSci uses the newest timestamp when updating the fields. If the timestamp for the plugin data in the database is newer than the data in the call, then the data in the call will be ignored.
* **UTM**: User's UTM tags
* **Accepts Marketing**: Indicates whether the user has opted in to accepting marketing emails. For new users, the default is `true`. Existing users' marketing preferences will not be modified unless you explicitly change this field.
* **Accepts Marketing Timestamp**: The timestamp of a users subscription status change. If earlier than a user's last subscription update, the requested subscription status update will be ignored. The `date_unsubscribed` field takes precedence over this date, so if both are present this date will be ignored. If no date is passed in the current time will be used.
* **Birthday Month**: Birthday month of the user being upserted in numerical format, for example, January = 1. Note that this field is ignored if birthday is present.
* **Birthday Day of Month**: Day of the month for the users birthday. Note that this field is ignored if the **Birthday** field is present.
* **Interests**: An array of interest object representing user's interest opt-in selections.
* **Frequency Option ID**: An integer representing the ID of a user's frequency choice for subscription preferences.

> [!TIP]
>
> The **Send Transactional Welcome** field defaults to `true`.
> If a sync creates a new user record and you've enabled transactional welcome emails in Cortex, then the sync results in ReSci sending the user a welcome email.
> Set **Send Transactional Welcome** to `false` if you don't want to send a welcome email.

See Retention Science's [docs](https://developer.retentionscience.com/?data/v3.0.0#tag/Users/paths/~1users/patch) for more details.

#### Delete behavior

**Delete** is only available for upsert mode.

| Behavior | Description |
| - | - |
| **Do nothing** | Keep the customer record in Retention Science with all its synced fields |
| **Clear** | Unset all the mapped fields from Retention Science |
| **Delete** | Delete the synced record from your Retention Science user |

### Lists

Add or remove users from a list in Retention Science.

#### Record matching

You can match rows in your model with list in Retention Science on any of the following fields:

* **Email**
* **Record ID**: this is also called `id` or `record_id`

## Tips and troubleshooting

To see the exact API requests and responses from each sync run, use the [live debugger](https://docs.hightouch.com/syncs/debugger.md). To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up [sync alerts](https://docs.hightouch.com/syncs/alerting.md). If you run into an issue this page doesn't cover, [contact support](#pylon-chat).