Go to the Destinations overview page and click the Add destination button. Select Iterable and click Continue. You can then authenticate Hightouch to Iterable with an Iterable API key and Project Type Identifier.
Once you've set up your Iterable destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the Iterable destination you want to sync to.
You can either use email or user ID to match rows from your model to users in Iterable.
In general, it's best to select the one that corresponds to the project type you selected when first setting up your Iterable instance.
There's one exception when you shouldn't match your record matching column to your project type:
If you have an email-based Iterable project and you're using update mode, selecting user ID for record matching can increase sync speed.
You should do this if you're confident that your user IDs are unique. (In email-based projects, Iterable doesn't require uniqueness for user IDs.)
Ensure you set your project identifier appropriately.
If you select user ID for record matching in email-based projects, Hightouch uses the bulk user update endpoint with the preferUserId parameter.
The preferUserId parameter dictates whether new users should be created if the request includes a userId that doesn't yet exist in the Iterable project.
This allows Hightouch to update only existing users without first having to perform a lookup.
Iterable only respects the preferUserId parameter in API calls for email-based projects.
For more information on how Iterable's API works differently according to project-type, refer to Iterable's docs.
Upsert mode is performant regardless of the project-type and column used for record matching.
You can sync columns from your model to Iterable user's data fields. If you send data for a custom field that doesn't exist, Hightouch adds the field and automatically detects its type.
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 for more information.
Iterable supports user and event fields 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.
For example, say you want to sync an array of a customer's pets to be an attribute named pets in Iterable:
When syncing custom and purchase events, the integration inserts new events into Iterable and lets you modify existing events as long as you provide their event ID.
Providing an event name is required to send an event to the Iterable API.
You can either provide a static value or select to use a column from your model.
Hightouch syncs the static or column value as the eventName body parameter the API requires.
You can optionally select a column that contains timestamps of when events occurred.
If this field is empty, Iterable uses the time the event arrives at the server.
You can use field mapping to add context to your events.
You must include either an email or user ID in your mappings.
Which you include depends on how your project identifies users.
If you provide both email and user ID, your project type takes precedence.
The integration uses these fields for identifying the user associated with this event.
For purchase events, you also need to provide the shopping cart items as Items and the Total order dollar amount in your mappings.
You can also include event data fields, including custom ones. Hightouch sends any custom fields you include as part of the in the dataFields property of event's body.
This sync mode both updates the shoppingCartItems field on a user's profile and tracks updateCart events in Iterable.
The integration inserts new events into Iterable when they first appear in your query results.
You must include shopping cart items as Items and either an email or user ID in your mappings.
Which you include depends on how your project identifies users.
If you provide both email and user ID, your project type takes precedence.
The integration uses these fields for identifying the user associated with this event.
You can also include user data fields for the user who updated their cart.
To match rows from your model to catalog items, you need to select the model column that contains values that match the Unique Product ID field.
Refer to the record matching docs for more information.
The Unique Product ID must contain only alphanumeric characters and dashes and has a maximum length of 255 characters.
See Iterable's API documentation for more information.
Sync audiences into your Iterable static lists of users. Hightouch automatically removes users from the Iterable list when they leave the query result.
To identify which contacts to add or update in a segment, select a model column and the corresponding Iterable field.
You can match on either Email or User ID.
It's best to select the one that corresponds to the project type you selected when first setting up your Iterable instance.
If you provide both email and user ID, your project type takes precedence.
You can sync columns from your model to user's default and custom data fields.
If you send data for a custom field that doesn't exist, Hightouch adds the field and automatically detects its type.
Your can create a new list or select an existing one.
If you choose to create a new list, Hightouch creates it on the initial sync run and then keeps it updated on existing sync runs.
You can provide a name for the new list, or Hightouch defaults to the name of the model used to create the sync.
Set all existing users from a query to be subscribed to a specific list, message type or message channel.
Hightouch automatically unsubscribes users from the target when they leave the query result.
To identify which contacts to add or update in a segment, select a model column and the corresponding Iterable field.
You can match on either Email or User ID, regardless of your project type.
You can use either email or user ID to match rows from your model to users in Iterable, regardless of your Iterable project type.
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 updates the email the first time the record appears in your query results and every time changes are detected.
This destination only triggers delete, forget, or unforget when records first appear in your model.
In other words, if a row with the same primary key appears in the model's query results in multiple syncs, Hightouch only triggers the selected API action on it the first time.
You can either use email or user ID to match rows from your model to users in Iterable.
It's best to select the one that corresponds to the project type you selected when first setting up your Iterable instance.
Before March 2023, Hightouch didn't require you to set your Iterable project identifier when connecting to Iterable.
Setting it may enhance sync performance if you're using update mode with the users sync type for an email-based project.
See the record matching section for more information.
You can set the project-type from the configuration tab of your Iterable destination in Hightouch.
If you see a discrepancy between the number of records that have passed through your sync and the number of records displaying in Iterable, check your data set for duplicates. Iterable automatically dedupes records based on primary key so the number of records in Iterable might be less than the number of records in your Hightouch sync if your sync unintentionally contains duplicates.
{"msg":"Project 13691: The request does not have the same data types as the data previously submitted, or the input value is not within the correct range. Field 'date_field' already exists for type 'user' and has a data type of 'date' but possible types 'string, keyword' in the request.","code":"RequestFieldsTypesMismatched","params":{"validationErrors":{"date_field":{"incomingTypes":["string","keyword"],"expectedType":"date","category":"user","offendingValue":["2023-04-19 12:15:30","0000-00-00 00:00:00"],"_type":"UnexpectedType"}}}}
The first value in the offendingValue array is associated with the first record in the batch sent to Iterable. The second value in the array is the value causing the issue. One instance of this value ("0000-00-00 00:00:00") causes the entire batch of records being sent to Iterable to fail.
To resolve the error, check for instances of ("0000-00-00 00:00:00") in the date_field column of your model and replace these values with null or a valid date.
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.