Search documentation...

K

Iterable

Run better email, push, and SMS campaigns on Iterable with up-to-date customer data from your data warehouse

Overview

Providing relevant and timely customer interactions relies on fresh and accurate data in your Iterable account. By automatically syncing customer data from your data warehouse into Iterable, you don't need to worry about data consistency or staleness. Instead, you can focus on building world-class customer experiences.

Supported syncing

Object TypeDescriptionSupported Sync Modes
UsersSync data from any source to your Iterable usersUpsert, Update
Custom EventsSync custom events with data from any sourceInsert, Update
Purchase EventsSync purchase events with data from any sourceInsert, Update
User Shopping Cart EventsUpdate user's shopping cart and creates event for itInsert
CatalogsSync data from any source to your Iterable catalogsInsert
SegmentsCreate new or use existing list to sync users to itInsert
Update email addressUpdate user email addressUpdate
User API actionsDelete, forget, or unforget users.Insert
To ensure syncs send each event, use a hash function for the event model's primary key . The hash should combine all columns, including member ID, timestamp, etc. See the event sync documentation for more information.

Getting started

Setup

Navigate to Integrations > API Keys and create a new API key with Server-Side permissions.

Use the API key generated to create a new Iterable destination in the Destinations tab of Hightouch.

Now that you have a new Iterable destination, you can start piping data.

Syncing data

Users

Sync Iterable users and properties with data from any source.

Record matching

You can match columns in your model with users in Iterable on the following fields:

  • Email
  • UserId

Field mapping

Hightouch lets you send data to user data fields. You can map data to existing fields or to new fields.

When creating new fields, Iterable automatically generates a schema for that field based on the first data sent. You cannot change the schema once it's set. See Iterable's article here.

Nested objects and object arrays

Iterable supports user and event attributes containing JSON objects or arrays of objects. These objects and object arrays are commonly used to support "entities" related to each user—for example, devices, medications, pets, etc.—especially when marketing communication needs to include metadata about these related entities.

Hightouch is a great tool to sync to these types of attributes because you can leverage your data warehouse to manage these associations. To do so, you must build the full JSON object into a single column within your Hightouch data model.

Modeling nested attributes into JSON can be done in a few ways:

  • Natively in the warehouse, for example with ARRAY_CONSTRUCT(value1, value2, ...) or ARRAY_AGG(column) SQL functions
  • With something like dbt
  • Or by building these objects within the Hightouch SQL Editor

Nested object array example

Let's say you want an array of a customer's pets to be an attribute named pets in Iterable. You would need a data model with a column named pets and would then build the full JSON pets object array to populate that column. This array might look something like this:

[
  {
    "id": 0,
    "type": "dog",
    "breed": "Mutt",
    "name": "Rae"
  },
  {
    "id": 1,
    "type": "cat",
    "breed": "Tabby",
    "name": "Garfield"
  }
]

This full object array would need to be the value of a column in your Hightouch data model:

Value of an example "Pets" field shown in the Hightouch UI

Then you would map this column to the pets custom attribute in Iterable in your Hightouch sync configuration:

Mapping the "Pets" field in the Hightouch UI

After running your sync, you'd have relevant pet data on each user in Iterable.

Delete behavior

You have these options for how to treat records that leave your source data:

BehaviorDescription
Do nothingKeep the users in Iterable unchange
ClearField mapping will be synced with null values
DeleteDelete the user from Iterable

Custom events

When syncing custom events, the integration inserts new events into Iterable. Those events are kept up-to-date within Iterable using the event ID.

Field mapping

Add context to your custom events by mapping data fields to them. Your must provide at least an email or user ID in your mappings. The integration uses these fields for identifying the user associated with this event. If you provide both, email takes precedence.

These fields can be modified on an existing event:

  • Event name
  • Campaign ID
  • Template ID
  • Timestamp
  • Custom fields (Mappings)

Any custom destination fields are provided to Iterable in the dataFields property of the request.

Purchase events

Sync purchase events to track them in Iterable. The integration inserts new events into Iterable when they first appear in your query results. It then keeps those events up-to-date using the event ID.

Field mapping

You are required to provide the shopping cart items as Items and the Total order dollar amount in the mappings. You must also provide at least an email or a user ID in your mappings. The integration uses the email or user ID for identifying the user associated with the event. If you provide both email and user ID, email takes precedence. See Iterable's API documentation for more information.

You can modify these fields on an existing event:

  • Campaign ID
  • Template ID
  • User Data Fields (Mappings)
  • Event Data Fields (Mappings)

Update shopping cart items events

Send update shopping cart items events in Iterable. The integration inserts new events into Iterable when they first appear in your query results.

Field mapping

You are required to provde the shopping cart items as Items.You must also provide at least an email or a user ID in your mappings. The integration uses the email or user ID for identifying the user associated with the event. If you provide both email and user ID, email takes precedence. See Iterable's API documentation for more information.

You can include these fields in the event:

  • User Data Fields (Mappings)

Catalogs

Iterable catalogs can be synced to using Upsert mode.

Record matching

You can match columns in your model with users in Iterable on the following fields

  • Unique Product ID

Field mapping

Once a catalog is selected, Hightouch automatically pulls existing field types from your Iterable catalog for you to map data into.

Segment

Sync audiences into your Iterable static lists.

Record matching

You can either use email or user ID to map records from your query results to your users in Iterable.

Field mapping

Hightouch lets you pass data to the user data fields. You can map data to existing fields or to new fields.

Static list

Your can create a new list or select an existing one. If you choose to create a new list, Hightouch creates it on initial sync run.

Update email address

Hightouch lets you update your users email addresses.

Record matching

You can either use email or user ID to map records from your query results to your users in Iterable. If you match by email, the update call is only made the first time the record appears in your query results. Matching by user ID makes an update email call the first time the record shows up in your query results and every time changes in your record are detected.

Field mapping

You must provide the new email in the mapping.

User API actions

Hightouch lets you perform the following actions on your users:

This destination only triggers delete, forget, or unforget when records first appear in your model.

Record matching

You can either use email or user ID to match records from your query results to your users in Iterable. You should select the one that corresponds to the project type you selected when first setting up your project type.

Tips and troubleshooting

Common errors

To date, our customers haven't experienced any errors while using this destination. If you run into any issues, . We're here to help.

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.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

On this page

OverviewSupported syncingGetting startedSetupSyncing dataUsersNested objects and object arraysCustom eventsPurchase eventsUpdate shopping cart items eventsCatalogsSegmentUpdate email addressUser API actionsTips and troubleshootingCommon errorsLive debuggerSync alerts

Was this page helpful?