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
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 .
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:
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 .
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.
You have the following options for how Hightouch should handle rows leaving your query results:
Behavior
Description
Do nothing
All cached data is preserved indefinitely. This option is strongly recommended against.
Clear the fields managed by this sync but do not delete the entire record
Fields managed by other syncs are preserved.
Delete the entire record
Requests for deleted records receive 404 Not Found responses.
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.
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.
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.
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.
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.