How Conversion works with Hightouch
Conversion connects to Hightouch through an HTTP Request destination that calls the Conversion API. Contact syncs create and update contacts from your Hightouch models, and event syncs record events on contacts for audiences and event-based workflows. Both run on the schedule you set in Hightouch, and syncing audience memberships or live events takes setup help from the Conversion team.
What you can do
Your models, your schedule
Contact and event syncs read from your Hightouch models and run on the schedule you set in Hightouch, with retries for rows that fail.
Control over overwrites
Fields you send replace existing values by default, and fields you leave out stay as they are. Set preserveExistingFields to true to fill only empty fields.
Backfill or go forward
The first event sync can send your existing event rows or skip them and send only new ones. Historical events can trigger workflows too.
Events for audiences and workflows
Events such as trial_started or plan_upgraded land on contacts, where they build audiences and start event-triggered workflows.
What syncs
| Data | Direction | Details |
|---|---|---|
| Contacts | Into Conversion | Upserted through /api/v2/contacts one row at a time and matched by email, with attributes mapped under fields. |
| Events | Into Conversion | New model rows post to /api/v2/events with a unique eventId and the original timestamp, and duplicate IDs are ignored. |
| Audience memberships | Into Conversion | Requires the Conversion team. Contact them for setup details. |
How to connect Hightouch
- 1 Create a Conversion API key under Settings > API Keys.
- 2 In Hightouch, add an HTTP Request destination named Conversion with the base URL https://pub-api.conversion.ai and your key in an X-API-Key header marked Secret.
- 3 Create a contact sync on Rows added and Rows changed that POSTs single rows to /api/v2/contacts, mapping email and a fields object whose keys match Conversion field keys.
- 4 For events, create a sync on Rows added only that POSTs to /api/v2/events, mapping email, event, eventId, timestamp, and optional data.
- 5 Choose a schedule for each sync and enable retries for failed rows.
