Hightouch Personalization API

Personalize any customer experience using our fully-managed, low-latency API

Overview

Hightouch Personalization API is a fully managed service that combines the analytical power of the data warehouse with the real-time performance of a low-latency API. You can think of this feature as a cache for your data warehouse.

With the Personalization API, you can serve any data model—customers, products, transactions, recommendations, etc.—to any internal app, web experience, or email marketing platform. Define your dataset with SQL and Hightouch handles the rest.

Example use cases include:

• Powering personalized marketing campaigns by enriching marketing touchpoints with dynamic product recommendations
• Delivering in-app or web personalization like customized search results, cohort-based pricing and messaging, article recommendations, or nearest store locations
• Optimizing product experimentation by delivering up-to-date customer information like audience inclusion/exclusion to decisioning and experimentation systems

Architecture

Under the hood, the Personalization API is backed by a distributed, low-latency database that stores a cache of your model. This cache updates as frequently as you see fit with Hightouch's scheduling options. Hightouch then serves this cache over HTTP so that it can be queried by your SaaS tools and other services.

Our benchmarks show p99 response times under 30 milliseconds in the same region. The Personalization API can support peak throughput of 1 million requests per second. To obtain the most recent benchmarks for your region, please contact us.

Implementation steps

Using this feature is a three-step process:

1. Enabling the Personalization API in the regions closest to your own infrastructure
2. Creating syncs to define which models should be materialized in the Hightouch-managed cache
3. Using your HTTP endpoints to access data

Getting started

After the Personalization API is enabled for your workspace, navigate to the newly created destination and configure the region from which the API should be served.

Currently, the following AWS regions are available for self-serve deployment:

• us-east-1
• us-west-2
• eu-west-1

For other regions, please contact us to complete setup.

Sync configuration

There are two core concepts in the Personalization API: collections and records.

• Collections are conceptually similar to database tables. Each should represent a particular type of data, such as customers or invoices. Collection names must be alphanumeric and will become part of your Personalization API endpoint.
• Records are conceptually similar to rows in a database. Each should represent a single item, like a customer profile. Collections consist of one or more records.

You can create multiple syncs to the same collection provided that each sync updates different record fields.

For example, you might have one model representing basic customer demographic data—age, gender, location, etc.—and another model representing account usage data—last_login_at, num_messages_sent, etc. By creating two syncs to the same customers collection, you can create more complex records that contain all attributes necessary for personalization.

Next, specify which column from your model should serve as the primary index for record lookups. This field must uniquely identify each record in the collection and is often the same as your model's primary key.

The Personalization API supports lookups on multiple indices. For example, you might want to retrieve customer profiles using user_id, anonymous_id, or email_address. To enable multiple indices, please contact us.

Use the field mapper to specify which columns from your model should be included in the API response payload. You can rename these fields and use the advanced mapper to apply transformations using the Liquid template language.

Delete behavior

You have the following options for how Hightouch should handle rows leaving your query results:

You probably want to delete the entire record if your collection is managed using only one sync. However, if multiple syncs are writing to the same collection, it's best to clear only the fields updated by this sync.

Access data

To start using the API, you must first create an API key for your workspace.

Create an API key

1. From the API keys tab on the Settings page, select Add API key.
2. Enter a descriptive Name for your key.
3. Copy your API key and store it in a safe location. The key will only be displayed once.
4. Click Create API key.

Make API requests

Once you have an API key, you can make requests to the Personalization API to retrieve data. The API is accessible at https://personalization.{region}.hightouch.com, for example, https://personalization.us-west-2.hightouch.com.

Authentication

You can specify your API key via a bearer token in an HTTP Authorization header.

Authorization: Bearer XXXXX

Usage

The API has a single endpoint:

Refer to your sync configuration for your collection_name.

A request looks like this:

curl -X GET \
     -H "Authorization: Bearer 55555555-4444-3333-2222-111111111111" \
     "https://personalization.us-west-2.hightouch.com/v1/collections/customers/records/id/12345"

When the query is successful, the HTTP response is a 200 OK and returns the record specified by the index value, in this case the customer with user_id (the index key) equal to 12345 (the index value). The data in the response payload is entirely flexible and defined by your sync configuration.

For example:

{
    "user_id": 12345,
    "full_name": "Jane Doe",
    "lifetime_value": 1492.18,
    "churn_risk": 0.04,
    "90_day_summary": {
        "num_songs_listened": 813,
        "top_genres": [
            "house",
            "techno",
            "ambient"
        ],
        "top_artists": [
            "deadmau5",
            "Marsh",
            "Enamour"
        ],
    },
    "recommendations": {
        "concerts": [
            {
                "artist": "Aphex Twin",
                "location": "San Francisco, CA",
                "event_date": "2023-01-31"
            },
            {
                "artist": "Sultan + Shepard",
                "location": "San Francisco, CA",
                "event_date": "2023-02-25"
            }
        ],
        "upcoming_album_release": {
            "title": "Universal Language",
            "artist": "Simon Doty",
            "label": "Anjunadeep",
            "release_date": "2023-04-28"
        }
    },
    "_audiences": {
        "top_concert_ticket_purchasers": true,
        "attended_concert_last_month": false,
        "electronic_music_listeners": true
    }
}

Tips and troubleshooting

Unique primary key requirement

The model you select for your sync configuration must have a unique identifier as its primary key.

Recommended usage

The Personalization API should not be called directly from a webpage, mobile app, or any untrusted client. We recommend proxying API calls through a service that you own, such as your application backend. This allows you to enforce reasonable rate limits and ensure that clients cannot retrieve data belonging to other users. Keep in mind that authentication is performed using a Hightouch API key, which grants access to all records in your Personalization API collection.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.