This article includes an overview of Iterable's API, how to use it, and descriptions of its various endpoints.
Table of contents
- Getting started
- Optional and required fields
- TLS 1.2
- Authenticating with Iterable's API
- Identifying users
- List APIs
-
Subscription APIs
- Subscribe a user to a single channel, message type or list (by email)
- Subscribe a user to a single channel, message type or list (by user ID)
- Unsubscribe a user from a single channel, message type or list (by email)
- Unsubscribe a user from a single channel, message type or list (by user ID)
- Subscribe or unsubscribe multiple users to the same channel, message type, or list
- Events APIs
- User APIs
- Push APIs
- In-app message APIs
- Experiment APIs
- SMS APIs
- Verify APIs
- Message type APIs
- Channel APIs
- Template APIs
- Campaign APIs
- Commerce APIs
- Email APIs
- Export APIs
- Journey APIs
-
Catalog APIs
- Create a catalog
- Get catalog names
- Delete a catalog
- Bulk create catalog items
- Get the catalog items for a catalog
- Get a specific catalog item
- Create or replace a catalog item
- Create or update a catalog item
- Delete a catalog item
- Bulk delete catalog items
- Get field mappings (data types) for a catalog
- Set a catalog's field mappings (data types)
- Appendix: Project types
- Further reading
Getting started
Before getting started with Iterable's API, note the following:
- To learn how to create API keys and use them to authenticate with Iterable's API, read API Keys.
- To learn more about Iterable's API and experiment with its endpoints, visit our API documentation.
- The base URI for Iterable's API is
https://api.iterable.com
. - Iterable may occasionally add fields to API response bodies. Make sure that any dependencies you have on these APIs do not break if and when new fields are added.
- Iterable will not rename or remove existing, documented fields from an API response body without prior communication.
Optional and required fields
To learn which fields are optional and which are required for a given request body, see our API documentation.
TLS 1.2
Clients making calls to Iterable's API must support TLS 1.2. Starting October 22, 2021, API calls from clients that do not support TLS 1.2 will fail. For more information, read this release note from September 22, 2021.
Authenticating with Iterable's API
To authenticate a request to Iterable's API:
-
For API keys that are not JWT-enabled, add to the the request an
Api-Key
orApi_Key
header whose value is a valid API key for your Iterable project. For more information, read Using API keys.IMPORTANT
Be sure never to use server-side API keys in client-side (web, mobile, or otherwise) code.
To learn how to use JWT-enabled API keys, read Calling Iterable's API with JWT-enabled API keys.
Identifying users
Many of Iterable's API endpoints require you to specify a particular user for
your request to modify or return. To do this, you generally need to provide a
userId
or an email
in the body of your API request (at the top level, or
sometimes in another object included in the request).
To decide whether to include an email
or a userId
, consider the type of
your Iterable project:
- Email-based projects identify users by
email
oruserId
. However, Iterable only enforcesemail
uniqueness—notuserId
. - UserID-based projects identify users by
userId
, and Iterable enforces the uniqueness of this field. - Hybrid projects projects identify users by
email
and/oruserId
, and Iterable enforces the uniqueness of both. However, you don't have to give both fields to every user.
TIP
For more information about project types in Iterable, read Appendix: Project types.
Sample API request that identifies a user
To identify a user in an API request:
-
At the top level of your request (outside of
dataFields
), provide auserId
or anemail
(but not both), as required by your project type. This value tells Iterable which user to update, create, or return.If you do include both
email
anduserId
at the top level of an API request, precedence rules apply.Some requests require you to place
userId
oremail
inside another object, rather than at the top level of your API request. For example, when callingPOST /api/commerce/updateCart
, you need to placeuserId
oremail
inside auser
object.Additionally, some requests use slightly different field names. For example,
POST /api/email/target
requiresrecipientEmail
andrecipientUserId
, rather thanemail
anduserId
. For endpoint-specific details, consult the API docs. Inside the
dataFields
object in the request, place the updates you'd like to make for that user.
For example, here's a request to POST /api/users/update
.
{ "userId": "user1234567", "dataFields": { "favoriteColor": "red" } }
If this request is sent to a userID-based or hybrid project:
- If your project doesn't yet have a user with a
userId
ofuser1234567
, Iterable creates one. - Then, whether the user is new or already exists, Iterable sets their
favoriteColor
tored
.
If this request is sent to an email-based project:
- If there's already a user identified by a
userId
ofuser1234567
, Iterable updates theirfavoriteColor
tored
. - Otherwise, the request fails. (To create a new user by
userId
in an email-based project, your request must setpreferUserId
totrue
. Sinceemail
is required in email-based projects, settingpreferUserId
totrue
also causes Iterable to assign an@placeholder.email
email address to the new user. To learn more, read Handling Anonymous Users.)
List APIs
Add subscribers to list
Adds a subscriber to an existing static list.
Learn about identifying users in API requests.
Sample request body:
{ "listId": 123, "subscribers": [ { "email": "user@example.com", "dataFields": { "firstName": "Sherry", "hasCat": true }, "userId": "1" } ] }
Delete static list
Deletes a list. All users who are part of the deleted list have the list removed from their profile.
Sample request:
https://api.iterable.com:443/api/lists/21398
Remove users from list
Removes one or more subscribers from an existing static list.
Learn about identifying users in API requests.
Sample request body:
{ "listId": 1, "subscribers": [ { "email": "user@example.com" }, { "email": "user2@example.com" } ], "campaignId": 123, "channelUnsubscribe": false }
Get users in list
Returns a string of all the users who are on a list. Works for both static and dynamic lists
Sample:
GET https://api.iterable.com:443/api/lists/getUsers?listId=21401
Get lists from project
Returns the project's static lists and their descriptions (if set).
Sample:
GET https://api.iterable.com:443/api/lists
Sample response body:
{ "lists": [ { "id": 12345, "name": "September subscribers", "description": "Users who subscribed in September 2022.", "createdAt": 1234567891011, "listType": "Standard" } ] }
Create static list
Creates a new, empty, standard list, with the specified name. Returns the list ID.
Sample request body:
{ "name": "September subscribers", "description": "Users who subscribed in September 2022." }
Subscription APIs
Subscribe a user to a single channel, message type or list (by email)
PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
Learn about identifying users in API requests.
-
For
subscriptionGroup
, provide one of the following values:messageChannel
messageType
emailList
For
subscriptionGroupId
, provide the ID of the message channel, message type or email list to which you are subscribing the user.For
userEmail
, provide the email address of the user for which you'd like to create a subscription.This is an asynchronous API. It returns 202 on success.
-
For example, the following call subscribes user
user@example.com
to message type12345:
PATCH https://api.iterable.com/api/subscriptions/messageType/12345/user/docs%40iterable.com
Subscribe a user to a single channel, message type or list (by user ID)
PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userId}
Learn about identifying users in API requests.
-
For
subscriptionGroup
, provide one of the following values:messageChannel
messageType
emailList
For
subscriptionGroupId
, provide the ID of the message channel, message type or email list to which you are subscribing the user.For
userId
, provide the user ID of the user for which you'd like to create a subscription.This is an asynchronous API. It returns 202 on success.
-
For example, the following call subscribes user
101abc123
to message type12345:
PATCH https://api.iterable.com/api/subscriptions/messageType/12345/user/101abc123
Unsubscribe a user from a single channel, message type or list (by email)
DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
Learn about identifying users in API requests.
-
For
subscriptionGroup
, provide one of the following values:messageChannel
messageType
emailList
For
subscriptionGroupId
, provide the ID of the message channel, message type or email list from which you are unsubscribing the user.For
userEmail
, provide the email address of the user from which you are unsubscribing the user.This is an asynchronous API. It returns 202 on success.
-
For example, the following call unsubscribes user
user@example.com
from message type12345
:DELETE https://api.iterable.com/api/subscriptions/messageType/12345/user/docs%40iterable.com
Unsubscribe a user from a single channel, message type or list (by user ID)
DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userId}
Learn about identifying users in API requests.
-
For
subscriptionGroup
, provide one of the following values:messageChannel
messageType
emailList
For
subscriptionGroupId
, provide the ID of the message channel, message type or email list from which you are unsubscribing the user.For
userId
, provide the user ID of the user from which you are unsubscribing the user.This is an asynchronous API. It returns 202 on success.
-
For example, the following call unsubscribes user
101abc123
to message type12345
:DELETE https://api.iterable.com/api/subscriptions/messageType/12345/user/101abc123
Subscribe or unsubscribe multiple users to the same channel, message type, or list
PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}?action=subscribe
To subscribe multiple users to the same channel, message type or list, use
action=subscribe
(as shown in the above URL). To unsubscribe, useaction=unsubscribe
.-
For
subscriptionGroup,
provide one of the following values:messageChannel
messageType
emailList
For
subscriptionGroupId,
provide the ID of the message channel, message type or email list to which you are subscribing the users.For the request body, provide a
users
array containing the email addresses of the users to subscribe or unsubscribe, and/or ausersByUserId
array containing theuserId
values to subscribe. Learn about identifying users in API requests.This is an asynchronous API. It returns 202 on success.
-
For example, the following request subscribes
user@example.com
,user2@example.com
, anduser1234567
to message type12345
:PUT https://api.iterable.com/api/subscriptions/messageType/12345?action=subscribe
Request body:
{ "users": [ "user@example.com", "user2@example.com" ], "usersByUserId": [ "user1234567" ] }
Events APIs
Get events associated with a user
Returns a user's events, including system events and custom events. The default
value for limit
is 30.
Learn about identifying users in API requests.
Sample:
GET https://api.iterable.com:443/api/events/docs%40iterable.com
Sample JSON response:
{ "events": [ { "contentId": 330397, "recurringCampaignId": 12345, "email": "user@example.com", "createdAt": "2016-10-04 00:54:00 +00:00", "campaignId": 67890, "templateId": 11111, "messageId": "1234example9876", "eventType": "emailSend" }, { "contentId": 329261, "recurringCampaignId": 12345, "email": "user@example.com", "createdAt": "2016-09-30 19:50:00 +00:00", "campaignId": 67890, "templateId": 22222, "messageId": "9876example1234", "eventType": "emailSend" } ] }
Track event
Saves custom events in Iterable (user logins, signups, app opens, etc.).
You can use these events in segmentation, to trigger journeys, and to track custom conversions. Additionally, in a template, you can use the the fields of a campaign-triggering event as a source of dynamic data.
Learn about identifying users in API requests.
An optional string id
parameter may be passed as one of the top-level
parameters. If an event exists with that id
, the event is updated. If no id
is specified, a new id
is automatically generated and returned.
NOTE
An id
value must:
- Contain only alphanumeric characters and hyphens.
- Be no longer than 512 bytes in length.
- Be unique across all custom events in the project.
Sample request body:
{ "email": "user@example.com", "eventName": "startedMembership", "id": "12345", "dataFields": { "source": "facebook", "membershipType": "monthly" }, "userId": "1", "campaignId": 123, "templateId": 123 }
Bulk track events
Tracks multiple custom events.
Events are created asynchronously and processed separately from the non-bulk event tracking endpoint. Thus, if you need to make sure events are tracked in order, send all of them to the same endpoint (either bulk or non-bulk).
Learn about identifying users in API requests.
Limitations:
Rate limit: 10 requests/second, per project.
An Iterable project can contain up to 8,000 unique custom event field names. If the same field name is used on various custom events that have different
eventName
values, it counts multiple times against this limit.Types of data fields must match the types sent in previous requests, across all data fields in the project (for the same event name).
Bulk events are processed separately from regular event track endpoint.
There's a 4MB limit for the request's JSON body (about 1000 events).
Fields per event are the same as for single event in regular track event endpoint.
Sample request body:
{ "events": [ { "email": "user@example.com", "eventName": "startedMembership", "id": "12345", "dataFields": { "source": "facebook", "membershipType": "monthly" }, "userId": "1", "campaignId": 123, "templateId": 123 }, { "email": "user@example.com", "eventName": "quizCompleted", "id": "45678", "dataFields": { "score": 9 } } ] }
Track push open
POST /api/events/trackPushOpen
Tracks a mobile push notification open.
Include a campaignId
to attribute the open to the Iterable campaign that
sent the push notification.
Learn about identifying users in API requests.
Sample request body:
{ "email": "user@example.com", "userId": "2", "campaignId": 12345, "templateId": 67890, "messageId": "01234567890", "dataFields": { "openedMostRecentPush": true } }
Track in-app message click
POST /api/events/trackInAppClick
Creates an inAppClick
event for the specified user, message and URL. When not
using one of Iterable's mobile SDKs, call this endpoint when a user taps on a
button or link in an in-app message.
Learn about identifying users in API requests.
Sample request body:
{ "email": "user@example.com", "userId": "user123", "messageId": "Ddd8cae9adf61A48afab877a58c22Lfa7ab1", "clickedUrl": "https://www.iterable.com" }
Consume or delete an in-app message
Consumes or deletes an in-app message from the server.
Use this API if your app does not use one of Iterable's mobile SDKs, since they call it automatically.
Learn about identifying users in API requests.
If an incoming in-app message is not configured to use the mobile inbox, use this API to "consume" it from the server queue after the user sees it. Otherwise, call this API when the user explicitly deletes an inbox-enabled message (by clicking a delete button in its content, swiping it in the inbox, etc.).
If you pass a deleteAction
value to this endpoint, Iterable generates an
inAppDelete
event (otherwise, it does not).
Sample request body:
{ "email": "user@example.com", "userId": "user123", "messageId": "Ddd8cae9adf61A48afab877a58c22Lfa7ab1", "deleteAction": "inbox-swipe", "messageContext": { "location": "inbox", "saveToInbox": true, "silentInbox": false }, "deviceInfo": { "deviceId": "E628DC81-52AB-4464-B337-C2624E3B293D", "platform": "iOS", "appPackageName": "com.example.testapp" } }
Track in-app message open
POST /api/events/trackInAppOpen
Creates an inAppOpen
event for the specified user and message. When not using
one of Iterable's mobile SDKs, call this endpoint when a mobile app displays an
in-app message to a user.
This endpoint also marks the specified in-app message as having been read.
Learn about identifying users in API requests.
Sample request body:
{ "email": "user@example.com", "userId": "user123", "messageId": "Ddd8cae9adf61A48afab877a58c22Lfa7ab1" }
Track in-app message close
POST /api/events/trackInAppClose
Creates an inAppClose
event for a specific user and in-app message. When not
using Iterable's mobile SDKs, call this endpoint to indicate that the user
tapped a close button or link to close a particular in-app message.
- Learn about identifying users in API requests.
Sample request body:
{ "email": "user@example.com", "userId": "user123", "messageId": "Ddd8cae9adf61A48afab877a58c22Lfa7ab1", "clickedUrl": "https://www.iterable.com", "messageContext": { "saveToInbox": true, "silentInbox": true, "location": "in-app" }, "closeAction": "link", "deviceInfo": { "deviceId": "", "platform": "iOS", "appPackageName": "com.example.testapp" } }
Track in-app message delivery
POST /api/events/trackInAppDelivery
Creates an inAppDelivery
event for a specific user, device and message. When
not using Iterable's mobile SDKs, call this endpoint to indicate that a
particular message has been delivered to a particular device for a particular
user. Take care not to call this endpoint multiple times for the same
message/device/user combination.
Learn about identifying users in API requests.
Sample request body:
{ "email": "user@example.com", "userId": "user123", "messageId": "Ddd8cae9adf61A48afab877a58c22Lfa7ab1", "messageContext": { "saveToInbox": true, "silentInbox": true }, "deviceInfo": { "deviceId": "E628DC81-52AB-4464-B337-C2624E3B293D", "platform": "iOS", "appPackageName": "com.example.testapp" } }
User APIs
Bulk update subscriptions
POST /api/users/bulkUpdateSubscriptions
Updates one or more users' subscription preferences. Include campaignId
and/or
templateId
to attribute unsubscribes to campaigns and templates.
Learn about identifying users in API requests.
NOTE
This endpoint overwrites existing subscription preferences if fields are set and not null.
Sample request body:
{ "updateSubscriptionsRequests": [ { "email": "user@example.com", "userId": "0192837821", "unsubscribedChannelIds": [ 12345, 23456 ], "unsubscribedMessageTypeIds": [ 65432 ], "campaignId": 34567, "templateId": 456789 }, { "email": "user2@example.com", "userId": "2131238573", "unsubscribedChannelIds": [ 12345 ], "campaignId": 34567, "templateId": 456789 } ] }
Update a user's email
Updates a user's email.
IMPORTANT
Use this endpoint with email-based projects. To update
an email in a userID-based or hybrid project, use POST /api/users/update
.
In the request body, specify currentEmail
or currentUserId
, but not both. If
you provide both, currentEmail
takes precedence.
Sample request body:
{ "currentEmail": "oldEmail@example.com", "newEmail": "newEmail@example.com" }
Another sample request body:
{ "currentUserId": "user1234567", "newEmail": "newEmail@example.com" }
Returns an error if the new email already exists in Iterable, or if the new email has been forgotten via a GDPR request.
Learn more about identifying users in API requests.
Bulk update
Bulk updates user data. This endpoint adds and overwrites user profile fields as needed. It does not modify top-level fields omitted from the request body.
Learn about identifying users in API requests.
If you'd like to merge (rather than overwrite) a user profile's top-level
objects with the values provided for them in the request body, set
mergeNestedObjects
to true.
When updating an existing field, you cannot change its data type (the new value must have the same data type as the old value).
When adding a new field, remember that each project has a soft limit of 1,000 unique user profile fields (across all its users, with a field's uniqueness determined by its name and position on the user profile).
Iterable handles requests to this endpoint separately from requests to
single-user endpoints (update
, updateEmail
, updateSubscriptions
, etc.). For a
given user, in a short period of time, only use single-user calls or bulk update
calls. Otherwise, results may be inconsistent.
When updating the emailListIds
field, this endpoint does not generate subscribe
or unsubscribe events. The same is true for updates to unsubscribedChannelIds
and unsubscribedMessageTypeIds
(but these can only be updated by this endpoint
in projects where the opt-in message types feature is not enabled).
To create a user profile for a user without a known email address:
- For email-based projects, specify a
userId
and setpreferUserId
totrue
. - For userID-based and hybrid projects, specify a
userId
. - To learn more, read Handling Anonymous Users.
Sample request body:
{ "users": [ { "email": "user@example.com", "userId": "0192837821", "dataFields": { "favoriteColor": "orange" } }, { "email": "user2@example.com", "userId": "9281928374", "dataFields": { "favoriteColor": "blue" } }, { "userId": "2394029394", "preferUserId": true, "dataFields": { "favoriteColor": "red" } } ] }
Register device token
POST /api/users/registerDeviceToken
Registers a mobile device token to enable push notifications.
applicationName
is usually be the package name of your mobile app, as found
in Settings > Apps and websites.
Learn about identifying users in API requests.
TIP
Learn more about sending push notifications with Iterable.
Sample request body:
{ "email": "user@example.com", "device": { "token": "sampletoken123", "platform": "APNS", "applicationName": "com.example.pizzatracker", "dataFields": { "phoneType": "iPhone 6 plus" } }, "userId": "2" }
Update user subscriptions
POST /api/users/updateSubscriptions
Updates a user's subscription settings with new settings.
This endpoint overwrites existing subscription preferences if those fields are set
and not null
.
Learn about identifying users in API requests.
Sample request body:
{ "email": "user@example.com", "userId": "0192837821", "emailListIds": [ 5, 6, 7 ], "unsubscribedChannelIds": [ 100 ], "unsubscribedMessageTypeIds": [ 100 ], "campaignId": 123, "templateId": 123 }
Get user profile fields
Gets all user profile fields in a project.
Sample:
GET https://api.iterable.com:443/api/users/getFields
Sample JSON response:
{ "fields": { "phoneNumber": "string", "email": "string", "lastName": "string", "firstName": "string", "signupDate": "date", "profileUpdatedAt": "date", "signupSource": "string" } }
Delete a user
WARNING
This endpoint completely deletes the specified user profile, including subscription settings and event history. If the user is ever re-added, their profile will be empty and subscribed to everything by default. Deleting a user removes their historic campaign metrics, too.
Sample:
DELETE https://api.iterable.com:443/api/users/docs%40iterable.com
Before deleting users, consider your project type.
In email-based projects and hybrid projects, you can delete users by email
or
userId
. In userID-based projects, you can delete users only by userId
.
Get a user
Returns a user profile (identified by email
).
Learn about identifying users in API requests.
TIP
For email addresses that contain non-alphanumeric characters, use
GET /api/users/getByEmail
instead of this endpoint.
Sample:
GET https://api.iterable.com:443/api/users/docs%40iterable.com
Delete a user by user ID
DELETE /api/users/byUserId/{userId}
Deletes a user (identified by userId
).
WARNING
This endpoint completely deletes the specified user profile, including subscription settings and event history. If the user is ever re-added, their profile will be empty and subscribed to everything by default. Deleting a user removes their historic campaign metrics, too.
Sample:
GET https://api.iterable.com:443/api/users/byUserId/{userId}
Before deleting users, consider your project type.
In email-based projects and hybrid projects, you can delete users by email
or
userId
. In userID-based projects, you can delete users only by userId
.
Get a user by userId
GET /api/users/byUserId/{userId}
Returns a user profile (identified by userId
).
Learn about identifying users in API requests.
Sample:
GET https://api.iterable.com:443/api/users/byUserId?userId=[USER_ID]
User update
Updates a user profile with the specified data. Learn about identifying users in API requests.
If you set mergeNestedObjects
to true
(defaults to false
), the API merges
data in top-level objects rather than overwriting it with the values found
on the request.
For example, consider this user profile:
{ "email": "user@example.com", "mySettings": { "mobile": true } }
And this API request to POST /api/users/update
:
{ "email": "user@example.com", "mergeNestedObjects": true, "dataFields": { "mySettings": { "email": true } } }
Because mergeNestedObjects
was true
, the resulting user profile is:
{ "email": "user@example.com", "mySettings": { "mobile": true, "email": true } }
If mergeNestedObjects
had been false
, the resulting user profile would
instead have been:
{ "email": "user@example.com", "mySettings": { "email": true } }
Get sent messages
GET /api/users/getSentMessages
Returns a list of sent messages to a user within a certain time period.
Includes the messageId
, campaignId
, templateId
and createdAt
data. Does
not include the body of the message. campaignId
, excludeBlastCampaigns
,
startDateTime
and endDateTime
are all optional.
Sample:
GET https://api.iterable.com:443/api/users/getSentMessages?email=docs%40iterable.com&limit=2&campaignId=123&excludeBlastCampaigns=false&startDateTime=2016-10-01%2021%3A00%3A27%20%2B00%3A00&endDateTime=2016-10-29%2000%3A54%3A00%20%2B00%3A00
Sample JSON response:
{ "messages": [ { "messageId": "9876example4321", "campaignId": 123, "templateId": 456, "createdAt": "2016-10-04 00:54:00 +00:00" }, { "messageId": "1234example5678", "campaignId": 321, "templateId": 654, "createdAt": "2016-09-30 19:50:00 +00:00" } ] }
Disable device
Disables device. Prevents it from receiving push notifications. Must include the device token.
Learn about identifying users in API requests.
If the token exists on multiple user profiles, including email
disables
the token for that one email address only. If email
is not included, the toke
is disabled from all user profiles. The same is true for including or not
including userId
.
Sample request body:
{ "token": "sampleToken123", "email": "user@example.com", "userId": "2" }
Forget a user
IMPORTANT
- It can take up to ten minutes for Iterable to forget a user.
- Use this endpoint only for handling right to be forgotten requests.
This endpoint:
- Deletes the user's data from the Iterable project.
- Prevents Iterable from collecting more information about or sending messages to that user.
For a given user, call this endpoint for each project necessary.
Before forgetting or unforgetting a user, consider your project type:
- In email-based projects, you must forget and unforget users by
email
, notuserId
. - In userID-based projects, you must forget and unforget users by
userId
, notemail
. - In hybrid projects, you can forget and unforget users by
email
oruserId
(and you can use one identifier to forget, and the other to unforget).
TIP
For more information, read Responding to GDPR Requests.
Unforget a user
Restores a given Iterable project's ability to store information about and send messages to a user who had previously been forgotten. However, it does not recover any data stored about the user before they were forgotten.
For a given user, call this endpoint for each project necessary.
Before forgetting or unforgetting a user, consider your project type:
- In email-based projects, you must forget and unforget users by
email
, notuserId
. - In userID-based projects, you must forget and unforget users by
userId
, notemail
. - In hybrid projects, you can forget and unforget users by
email
oruserId
(and you can use one identifier to forget, and the other to unforget).
TIP
For more information, read Responding to GDPR Requests.
Push APIs
Send a push notification to a user
Sends a triggered push notification to a specific user.
Request data fields override existing user profile data fields. Campaign must be
set up in Iterable beforehand. If sendAt
field is not included, the message is
sent immediately.
Learn about identifying users in API requests.
Sample request body:
{ "campaignId": 13770, "recipientEmail": "user@example.com", "dataFields": { "newUser": "FALSE" }, "sendAt": "2016-08-25 23:25:00 +00:00" }
In-app message APIs
Get in-app messages for user
Gets the in-app messages available for a specific user. This endpoint returns
new messages and messages that have already been saved to a user's mobile inbox.
Each message has a read
field that indicates whether or not it has already
been seen.
If you'd like this API to return selective in-app messages for a specific
app/platform combination (as well as non-selective in-app messages), include
packageName
and platform
as query parameters in your request.
If you don't include both of these parameters, the API returns only non-selective in-app messages (i.e., in-app messages sent with the selective in-app messaging feature disabled).
Sample request:
GET https://api.iterable.com:443/api/inApp/getMessages?email=docs%40iterable.com&userId=1234&count=123
Sample JSON response:
{ "inAppMessages": [ { "messageId": "string", "campaignId": 0, "createdAt": "2022-11-10T16:58:14.933Z", "expiresAt": "2022-11-10T16:58:14.933Z", "content": { "html": "string", "inAppDisplaySettings": { "top": {}, "right": {}, "bottom": {}, "left": {}, "bgColor": { "alpha": 0, "hex": "string" }, "shouldAnimate": true }, "webInAppDisplaySettings": { "position": {} } }, "customPayload": {}, "trigger": { "type": {} }, "saveToInbox": true, "inboxMetadata": { "title": "string", "subtitle": "string", "icon": "string" }, "priorityLevel": 0, "read": true, "jsonOnly": true, "typeOfContent": {}, "messageType": {} } ] }
priorityLevel
indicates an in-app messages's display priority:
- Proof: 100.0
- Critical: 100.5
- High: 200.5
- Medium: 300.5
- Low: 400.5
By default, Iterable's mobile SDKs display greater priority messages first (proof, then critical, then high, then medium, then low), sorting the messages in each individual priority level by send time (first sent, first displayed).
Get web in-app messages for user
GET /api/inApp/web/getMessages
This endpoint is functionally the same as GET /api/inApp/getMessages
,
but with platform
always set to Web
(cannot be changed).
This endpoint is used by Iterable's web SDK to fetch in-browser messages (in-app messages that target a website).
Cancel in-app message to user
Cancels the sending of a scheduled in-app message to a specific user.
Learn about identifying users in API requests.
Sample JSON body:
{ "email": "user@example.com", "campaignId": 13770 }
Send in-app message to user
Sends an existing in-app message campaign to a specific user. Use sendAt
to
schedule a future send and dataFields
to override user profile fields.
Learn about identifying users in API requests.
Sample JSON body:
{ "campaignId": 13770, "recipientEmail": "user@example.com", "dataFields": { "newUser": "FALSE" }, "sendAt": "2016-08-25 23:25:00 +00:00" }
Experiment APIs
Get experiment metrics
Get metrics for experiments(s). Note that we currently only export email experiment metrics.
Sample:
GET https://api.iterable.com:443/api/experiments/metrics?experimentId=12345&campaignId=23456&startDateTime=2017-06-01&endDateTime=2017-07-01
SMS APIs
Send an SMS to a user
Sends an SMS to a specific user. Request data fields override existing user
profile data fields. Campaign must be set up in Iterable beforehand. If sendAt
field is not included, the message is sent immediately.
Learn about identifying users in API requests.
Sample request body:
{ "campaignId": 13770, "recipientEmail": "user@example.com", "dataFields": { "newUser": "FALSE" }, "sendAt": "2016-08-25 23:25:00 +00:00" }
Cancel SMS to a user
Cancels an SMS to a specific user. Must include either an email
address AND
campaignId
, or just a scheduledMessageId
.
Learn about identifying users in API requests.
Sample request body:
{ "email": "user@example.com", "campaignId": 15354, "scheduledMessageId": "210badf49fe54f2591d64ad0d055f4fb", "userId": "1" }
Verify APIs
Begin an SMS verification
Sends an SMS verification code to phoneNumber
, using the specified
verificationProfileId
.
Sample request body:
{ "verificationProfileId": 12345, "phoneNumber": "+15551112222" }
To find a verificationProfileId
, look on the Settings > Sending Platforms
page in Iterable. Open the Twilio or Telnyx account you use to send SMS
verification messages, open the Verification Profiles menu, and grab a
verification profile ID from the right-most column.
Call this endpoint only for projects that use Iterable SMS to send SMS messages. If you use your own Twilio or Telnyx account, call their verification endpoints directly.
To use this endpoint, first ask your Iterable customer success manager to add SMS phone verification to your project. To learn more, read SMS Phone Verification
Check an SMS verification
Checks whether the code
included in the request body matches the most recent,
non-expired, not-yet-verified SMS verification code sent to phoneNumber
by the
specified verificationProfileId
.
Sample request body:
{ "verificationProfileId": 12345, "phoneNumber": "+15551112222", "code": "13579" }
To find a verificationProfileId
, look on the Settings > Sending Platforms
page in Iterable. Open the Twilio or Telnyx account you use to send SMS
verification messages, open the Verification Profiles menu, and grab a
verification profile ID from the right-most column.
For code
, provide the code entered by your users in your mobile app or website
after you sent them a verification SMS.
If code
is correct, this endpoint returns a 200
response with a JSON body
that has a params
object with status
set to verified
. For example:
{ "msg": "", "code": "Success", "params": { "status": "verified" } }
If code
is incorrect, this endpoint returns a 200
response with a JSON body
that has a params
object with status
set to rejected
. For example:
{ "msg": "incorrect verification code", "code": "Success", "params": { "status": "rejected" } }
Call this endpoint only for projects that use Iterable SMS to send SMS messages. If you use your own Twilio or Telnyx account, call their verification endpoints directly.
To use this endpoint, first ask your Iterable customer success manager to add SMS phone verification to your project. To learn more, read SMS Phone Verification
Message type APIs
Get message types
Lists all message types for that project.
Sample JSON response:
{ "messageTypes": [ { "id": 3868, "name": "Push Marketing Message", "channelId": 3422 }, { "id": 3867, "name": "Transactional Message", "channelId": 3421 }, { "id": 3866, "name": "Marketing Message", "channelId": 3420 } ] }
Channel APIs
Get channels
Lists all channels for that project.
Sample JSON response:
{ "channels": [ { "id": 3422, "name": "Push Marketing Channel", "channelType": "Marketing", "messageMedium": "Push" }, { "id": 3421, "name": "Transactional Channel", "channelType": "Transactional", "messageMedium": "Email" }, { "id": 3420, "name": "Marketing Channel", "channelType": "Marketing", "messageMedium": "Email" } ] }
Template APIs
IMPORTANT
Iterable's various template APIs allow you to read and update all templates. These APIs are not restricted to base templates—they can also be used to read and update templates associated with blast campaigns, triggered campaigns, and journey campaigns (changing their content for future sends). For descriptions of these APIs, read the API documentation.
Update SMS template
POST /api/templates/sms/update
Updates a specific SMS template. Most fields are optional. Include the fields you wish to update.
Sample request body:
{ "templateId": 123, "name": "My SMS Title", "message": "I like animals.", "locale": "fr", "messageTypeId": 531 }
Get templates in a project
Gets info for the templates in a project. Includes the templateId
, creation
and modification times, the name of the template, the creator of the template
and the message type used.
NOTE
If you leave templateType
blank, the endpoint returns base templates only.
Sample:
GET https://api.iterable.com:443/api/templates?templateType=Base&messageMedium=Email
Sample JSON response:
{ "templates": [ { "templateId": 86596, "createdAt": 1473368899828, "updatedAt": 1473370111852, "name": "Regular editor", "creatorUserId": "user@example.com", "messageTypeId": 3867 }, { "templateId": 68178, "createdAt": 1466810056349, "updatedAt": 1470431713441, "name": "Photography Welcome Message", "creatorUserId": "user@example.com", "messageTypeId": 3866 } ] }
Update push template
POST /api/templates/push/update
Updates a specific push template. Most fields are optional. Include the fields you wish to update.
Sample request body:
{ "templateId": 0, "createdAt": "2022-09-29T17:23:42.683Z", "updatedAt": "2022-09-29T17:23:42.683Z", "name": "string", "title": "string", "message": "string", "payload": {}, "badge": "string", "wake": true, "relevanceScore": 0, "interruptionLevel": "passive", "locale": "string", "messageTypeId": 0, "sound": "string", "buttons": [ { "identifier": "string", "title": "string", "buttonType": "default", "action": { "type": "string", "data": "string" }, "openApp": true, "requiresUnlock": true, "inputPlaceholder": "string", "inputTitle": "string", "actionIcon": { "iconType": {}, "imageName": "string" } } ], "deeplink": { "ios": "string", "android": "string" }, "richMedia": { "ios": "string", "android": "string" }, "dataFeedIds": [ 0 ], "cacheDataFeed": true, "mergeDataFeedContext": true, "clientTemplateId": "string", "campaignId": {}, "isSilentPush": true }
To indicate that a template should send as a silent push notification, rather
than a standard push notification, set isSilentPush
to true
.
Silent push notifications don't visibly appear to your user. Instead, they pass
JSON data to your app (the payload
), which can use this data as needed — to
kick off a download, to tell the app to display an app store review prompt, etc.
On iOS, you can also use a silent push to set the badge
field, which updates
the badge on your app's icon.
Get an email template
Returns HTML and metadata for a specific email template.
Sample JSON response:
{ "templateId": 86596, "name": "My name of template", "fromName": "Customer Success", "fromEmail": "user@example.com", "replyToEmail": "replyTo@example.com", "subject": "My Subject of message", "preheaderText": "preheader message here", "ccEmails": [], "bccEmails": [], "html": "<html>\n\n<head>\n<title></title>\n</head>\n\n<body>\n <p>\n {{userPropertyParameter}}\n </p>\n</body>\n\n</html>", "plainText": "Optional plain text message", "cacheDataFeed": false, "mergeDataFeedContext": true, "messageTypeId": 3867, "creatorUserId": "user@example.com" }
Upsert an SMS template
POST /api/templates/sms/upsert
Creates a new template if one does not exist or updates all templates with the specified client template id.
Sample request body:
{ "clientTemplateId": 112233, "name": "SMS Test", "message": "Hello There!", "locale": "en", "messageTypeId": "1234" }
Get an SMS template
Returns content and metadata for a specific SMS template.
Sample JSON response:
{ "templateId": 100692, "name": "SMS testing", "message": "Here is example message", "messageTypeId": 4769 }
Get a push template
Returns content and metadata for a specific push notification template.
Sample JSON response:
{ "templateId": 0, "createdAt": "2022-09-29T17:23:42.748Z", "updatedAt": "2022-09-29T17:23:42.748Z", "name": "string", "title": "string", "message": "string", "payload": {}, "badge": "string", "wake": true, "relevanceScore": 0, "interruptionLevel": "passive", "locale": "string", "messageTypeId": 0, "sound": "string", "buttons": [ { "identifier": "string", "title": "string", "buttonType": "default", "action": { "type": "string", "data": "string" }, "openApp": true, "requiresUnlock": true, "inputPlaceholder": "string", "inputTitle": "string", "actionIcon": { "iconType": {}, "imageName": "string" } } ], "deeplink": { "ios": "string", "android": "string" }, "richMedia": { "ios": "string", "android": "string" }, "dataFeedIds": [ 0 ], "cacheDataFeed": true, "mergeDataFeedContext": true, "clientTemplateId": "string", "campaignId": {}, "isSilentPush": true }
Get an email template from a client template id
GET /api/templates/getByClientTemplateId
Gets an array of template ids that match a client template id. If the client has
set a clientTemplateId
on any email template(s), then this call return those
templates.
Update email template
POST /api/templates/email/update
Updates a specific email template. Only fields specified are updated.
Sample request body:
{ "templateId": 53081, "name": "Lots of Cats", "fromName": "Felicia the Cat", "fromEmail": "replyto@example.com", "replyToEmail": "replyto@example.com", "subject": "Rank These Cats", "preheaderText": "10 out of 10!", "html": "<html><body><p>So many cats!</p></body></html>" }
NOTE
This call does not work on templates made with the Drag-and-Drop Editor.
Upsert an email template
POST /api/templates/email/upsert
Creates a new email template if one does not exist, or updates all templates with the specified client template id.
Sample request body:
{ "clientTemplateId": 112233, "name": "Lots of Cats", "fromName": "Felicia the Cat", "fromEmail": "user@example.com", "replyToEmail": "replyTo@example.com", "subject": "Rank These Cats", "preheaderText": "10 out of 10!", "html": "<html><body><p>So many cats!</p></body></html>" }
Create a push template
POST /api/templates/push/upsert
Creates a new template if one does not exist, or updates all templates with the specified name.
Sample request body:
{ "clientTemplateId": "string", "name": "string", "title": "string", "message": "string", "payload": { "underlying": {}, "fields": [ { "_1": "string", "_2": {} } ], "value": {} }, "badge": "string", "wake": true, "relevanceScore": 0, "interruptionLevel": "passive", "locale": "string", "messageTypeId": 0, "sound": "string", "buttons": [ { "identifier": "string", "title": "string", "buttonType": "default", "action": { "type": "string", "data": "string" }, "openApp": true, "requiresUnlock": true, "inputPlaceholder": "string", "inputTitle": "string", "actionIcon": { "iconType": {}, "imageName": "string" } } ], "deeplink": { "ios": "string", "android": "string" }, "richMedia": { "ios": "string", "android": "string" }, "dataFeedIds": [ 0 ], "cacheDataFeed": true, "mergeDataFeedContext": true, "creatorUserId": "string", "isSilentPush": true, "messageMedium": {} }
Campaign APIs
Create campaign
Creates and schedules a blast campaign up to two weeks in advance. The campaign
has a new template with a new template id. If the sendAt
field is not
included, message is sent immediately.
Sample request body:
{ "name": "Sample API Blast Campaign", "listIds": [ 5925, 6094 ], "templateId": 28533, "suppressionListIds": [ 6095 ], "sendAt": "2015-09-15 00:00:00" }
Get campaigns
Gets info such as id
, createdAt
, name
, templateId
, etc. from campaigns.
Sample JSON response:
{ "campaigns": [ { "id": 59530, "createdAt": 1475452500507, "updatedAt": 1475452500591, "startAt": 1475535300000, "endedAt": 1475542440016, "name": "Recurring | 2016-10-02 | Pre-Make a campaign ahead of time", "templateId": 93661, "createdByUserId": "user@example.com", "campaignState": "Finished", "listIds": [ 16182 ], "suppressionListIds": [], "sendSize": 3 }, { "id": 59355, "createdAt": 1475265000217, "updatedAt": 1475265000276, "startAt": 1475265000274, "endedAt": 1475265000320, "name": "Recurring | 2016-09-30 | Recurring - Jeremy's List", "templateId": 93419, "createdByUserId": "user@example.com", "campaignState": "Finished", "listIds": [ 14007 ], "suppressionListIds": [], "sendSize": 3 } ] }
Get child campaigns
GET /api/campaigns/recurring/{id}/childCampaigns
Get details for campaigns generated by a recurring campaign.
Sample:
GET https://api.iterable.com:443/api/campaigns/recurring/12345/childCampaigns
Campaign metrics
Gets analytic info such as id
, bounces
, clicks
, conversions
, purchases
,
etc. from a campaign. A start and end date can be added to select the desired
range of analytics.
Sample CSV response:
id,bounces,clicks,conversions,opens,purchases,pushBounces,pushOpens,pushSent,pushUninstalls,revenue,sent,smsBounces,smsReceived,smsSent,spams,totalClicks,totalOpens,totalPushOpens,unsubs 59355,0,0,,0,0,,,,,0.0,3,,,,0,0,0,,0
Commerce APIs
Update cart
Updates shoppingCartItems
field on the user profile.
Learn about identifying users in API requests.
NOTE
We recommend casting the required price
field as a double instead of a long.
To do that, include a number with a decimal in the first call that you use to
cast that field. Use a non-zero decimal value to cast the field as a double
(example: 5.55
). Otherwise, the field is cast as a long.
Sample request body:
{ "user": { "email": "user@example.com", "dataFields": { "currentCartTotal": 34 }, "userId": "1", "mergeNestedObjects": true }, "items": [ { "id": "2", "sku": "4", "name": "Iterable T-shirt", "description": "100% cotton shirt. Show how much you love your favorite marketing automation platform!", "categories": [ "clothing", "swag" ], "price": 20.5, "quantity": 1, "imageUrl": "https://static.iterable.com/iterable/15-10-03-iterableshirt.png", "url": "iterable.com" }, { "id": "3", "sku": "5", "name": "Macadamia Nuts", "description": "Full of healthy fats! Made in Hawaii.", "categories": [ "food" ], "price": 5.5, "quantity": 2, "imageUrl": "https://nuts.com/images/auto/510x340/assets/4d57de389a2f6d59.jpg", "url": "iterable.com" } ] }
Track purchase
POST /api/commerce/trackPurchase
Tracks when a user makes a purchase and clears shoppingCartItems
on their
profile. Including a campaignId
attributes the purchase to a specific Iterable
campaign.
Learn about identifying users in API requests.
NOTE
We recommend casting the required price
and total
fields as doubles instead
of longs. To do that, include a number with a decimal in the first call that you
use to cast that field. Use a non-zero decimal value to cast the field as a
double (example: 5.55
). Otherwise, the field is be cast as a long.
An optional string id
parameter may be passed as one of the top-level
parameters. If a purchase event exists with that id
, the event is updated. If
no id
is specified, a new id
is automatically generated and returned.
NOTE
An id
value:
- Must contain only alphanumeric characters and hyphens.
- Must be no longer than 512 bytes in length.
- Must be unique across all purchase events in the project.
Sample request body:
{ "user": { "email": "user@example.com", "dataFields": { "totalPurchases": 5 }, "userId": "1" }, "items": [ { "id": "1", "sku": "1", "name": "Iterable Stickers", "description": "Put these stickers anywhere and everywhere!", "categories": [ "stickers", "novelty" ], "price": 5.5, "quantity": 2, "imageUrl": "https://static.iterable.com/iterable-demo-v1/15-03-04-Iterable_stickers.jpg", "url": "iterable.com" } ], "campaignId": 14348, "templateId": 29592, "total": 11, "dataFields": { "shippingAddress1": "360 3rd Street", "shippingAddress2": "Suite 675", "city": "San Francisco", "state": "CA", "zip": 94107 } }
NOTE
The POST /api/commerce/trackPurchase
endpoint requires an array of items
, but any events that are created by
invoking this endpoint contain an array named shoppingCartItems
(not
items
).
When segmenting your users into lists, you can access data in this array by
referencing the shoppingCartItems
field (not items
).
Similarly, journeys that are triggered by trackPurchase
can access data in
this array by referencing shoppingCartItems
(not items
).
Email APIs
Send an email to a user
Sends a triggered email campaign to specified email address. If sendAt
field
is not included, the message is sent immediately. The JSON passed in the
dataFields
section is indexed on the emailSend
event as transactionalData
.
Learn about identifying users in API requests.
NOTE
This is an asynchronous call; a 200 response means that the request has been received, not that the email has been sent.
Sample request body:
{ "campaignId": 13594, "recipientEmail": "user@example.com", "dataFields": { "customParam": "paramValue" }, "sendAt": "2015-08-31 22:00:00 +00:00" }
View in browser
View a copy of a previously sent email. Must include both a user's email address and the message id of the sent email.
Sample:
GET https://api.iterable.com:443/api/email/viewInBrowser?email=docs%40iterable.com&messageId=340c333dea5e43cea6de24170d8a81c8
Export APIs
Export data (CSV)
Exports different types of data (purchases, user created, email sends, email opens, etc.) in CSV format. When the call is made, a string is returned as a .csv file. This file is then available for download.
Export data (JSON)
Exports different types of data (purchases, user created, email sends, email opens, etc) in JSON format.
Sample response:
{ "contentId": 243307, "recurringCampaignId": 41777, "email": "user@example.com", "createdAt": "2016-07-08 19:50:00 +00:00", "campaignId": 43521, "templateId": 71213 } { "contentId": 242909, "email": "user@example.com", "createdAt": "2016-07-08 16:58:19 +00:00", "campaignId": 43444, "templateId": 71115 } { "contentId": 243307, "recurringCampaignId": 41777, "email": "user2@example.com", "createdAt": "2016-07-08 19:50:00 +00:00", "campaignId": 43521, "templateId": 71213 } { "contentId": 243307, "recurringCampaignId": 41777, "email": "user3@example.com", "createdAt": "2016-07-08 19:50:00 +00:00", "campaignId": 43521, "templateId": 71213 }
NOTE
The range field pulls information based off of the profile update field.
Export user events
Exports events in a user's history in JSON format. System events are always included, while custom events are optional.
Use the includeCustomEvents
parameter with a boolean value to specify whether
to include custom events in query parameters, enabling you to export only system
events if desired. The GET /api/events/{email}
endpoint does not have this filter.
Sample JSON response:
{ "name": "Jane Docs", "email": "user@example.com", "lastName": "Docs", "firstName": "Jane", "profileUpdatedAt": "2025-06-22 00:58:55 +00:00", "itblInternal": { "documentCreatedAt": "2025-06-22 00:58:55 +00:00", "documentUpdatedAt": "2025-06-22 00:58:55 +00:00" }, "createdAt": "2020-06-22 00:58:55 +00:00", "signupSource": "Import", "messageTypeIds": [], "emailListIds": [ 1111111 ], "channelIds": [], "_type": "emailSubscribe" } { "_id": "50bc32394fa14ef8dh24a17b5b6da768", "eventName": "viewedItem", "email": "user@example.com", "viewedItem": { "email": "user@example.com" }, "createdAt": "2025-06-28 02:12:02 +00:00", "eventUpdatedAt": "2025-06-28 02:12:02 +00:00", "itblInternal": { "documentCreatedAt": "2025-06-28 02:12:02 +00:00", "documentUpdatedAt": "2025-06-28 02:12:02 +00:00" }, "_type": "customEvent" }
Journey APIs
Trigger a journey
POST /api/workflows/triggerWorkflow
Triggers a journey for a single user and/or all users on a list. Works for both standard and dynamic lists.
Learn about identifying users in API requests.
Sample request body (JSON):
{ "email": "user@example.com", "workflowId": 2765, "listId": 6094, "dataFields": { "signupSource": "google", "optIn": true } }
Catalog APIs
NOTE
Contact your Iterable customer success manager to discuss adding Catalog to your plan.
Create a catalog
POST /api/catalogs/{catalogName}
Creates a new catalog in the project associated with the API key. Each catalog in an Iterable project must have a unique name that is no longer than 255 characters and contains only letters, numbers and dashes (no spaces, underscores or other special characters).
Example:
POST https://api.iterable.com/api/catalogs/Trucks
Sample JSON response body:
{ "msg": "", "code": "Success", "params": { "id": 740, "name": "Trucks", "url": "/api/catalogs/Trucks" } }
On success, this API returns HTTP status code 201.
Get catalog names
Lists the names of all catalogs in the project associated with an API key.
Example:
GET https://api.iterable.com/api/catalogs
Paging:
-
Use
page
andpageSize
in the query string to specify a page number and page size. For example:GET https://api.iterable.com/api/catalogs?page=3&pageSize=10
When you pass these parameters, the API returns
previousPageUrl
andnextPageUrl
values (as applicable). Use these to load more data.If you specify a
page
andpageSize
combination outside the range of available data, the API returns an empty list of catalog names.
Sample JSON response body:
{ "msg": "", "code": "Success", "params": { "catalogNames": [ { "name": "Trucks" } ], "totalCatalogsCount": 1 } }
On success, this API returns HTTP status code 200.
Delete a catalog
DELETE /api/catalogs/{catalogName}
Deletes a catalog and all its items.
Example:
DELETE https://api.iterable.com/api/catalogs/Trucks
Sample JSON response body:
{ "msg": "Successfully deleted catalog Trucks", "code": "Success", "params": null }
On success, this API returns HTTP status code 200.
Bulk create catalog items
POST /api/catalogs/{catalogName}/items
Creates up to 1,000 catalog items at a time (each one having a max size of 30kb). This is an asynchronous API; 202 response code indicates that the request has been received and will be processed.
The request body should specify a JSON object with a top-level document
key
and an associated object. In the document
object, each key corresponds to the
ID of a catalog item, and the key's associated object contains the catalog
item's fields.
Catalog items must have unique IDs (within a catalog). They may contain letters, numbers and dashes (no spaces, underscores or other special characters), and must be no longer than 255 characters.
If the catalog already contains an item having the same ID as one provided in the request body, the existing item is completely overwritten by the item specified in the request body Do not use the period character in catalog item field names.
Example:
POST https://api.iterable.com/api/catalogs/Trucks/items
Request headers:
Content-Type: application/json
Sample request body:
{ "documents": { "PickupTruckA": { "options": [ "manual transmission", "sunroof", "premium stereo" ], "manufactureDate": "2019-01-15", "current_location": { "lat": 37.773972, "lon": -122.431297 }, "fullLength": 230.25, "used": true, "price": 35000, "previousOwner": { "firstName": "John", "lastName": "Smith" } }, "PickupTruckB": { "options": [ "automatic transmission", "keyless entry" ], "manufactureDate": "2018-06-12", "current_location": { "lat": 39.742043, "lon": -104.991531 }, "fullLength": 215.75, "used": true, "price": 29500, "previousOwner": { "firstName": "Jane", "lastName": "Jones" } } } }
Sample JSON response body:
{ "msg": "Request to bulk-upload documents into Trucks processed successfully", "code": "Success", "params": null }
On success, this API returns HTTP status code 202.
Get the catalog items for a catalog
GET /api/catalogs/{catalogName}/items
Lists all catalog items in a catalog.
Example:
GET https://api.iterable.com/api/catalogs/Trucks/items
Paging:
-
Use
page
andpageSize
in the query string to specify a page number and page size. For example:GET https://api.iterable.com/api/catalogs/Trucks/items?page=3&pageSize=10
When passing these parameters, the API returns
previousPageUrl
andnextPageUrl
values (as applicable). Use these to load more data.If you specify a
page
andpageSize
combination outside the range of available data, the API returns an empty list of catalog names.
Sample JSON response body:
{ "msg": "", "code": "Success", "params": { "catalogItemsWithProperties": [ { "catalogName": "Trucks", "itemId": "PickupTruckB", "size": 242, "lastModified": 1555662886000, "value": { "used": true, "current_location": { "lat": 39.742043, "lon": -104.991531 }, "price": 29500, "manufactureDate": "2018-06-12", "options": [ "automatic transmission", "keyless entry" ], "fullLength": 215.75, "previousOwner": { "firstName": "Jane", "lastName": "Jones" } } }, { "catalogName": "Trucks", "itemId": "PickupTruckA", "size": 251, "lastModified": 1555662886000, "value": { "used": false, "current_location": { "lat": 37.773972, "lon": -122.431297 }, "price": 35000, "manufactureDate": "2019-01-15", "options": [ "manual transmission", "sunroof", "premium stereo" ], "fullLength": 230.25, "previousOwner": { "firstName": "John", "lastName": "Smith" } } } ], "totalItemsCount": 2 } }
On success, this API returns HTTP status code 200.
Get a specific catalog item
GET /api/catalogs/{catalogName}/items/{itemId}
Gets the details of a specific catalog item.
Example:
GET https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckA
Sample JSON response body:
{ "msg": "", "code": "Success", "params": { "catalogName": "Trucks", "itemId": "PickupTruckA", "size": 251, "lastModified": 1555662886000, "value": { "used": false, "current_location": { "lat": 37.773972, "lon": -122.431297 }, "price": 35000, "manufactureDate": "2019-01-15", "options": [ "manual transmission", "sunroof", "premium stereo" ], "fullLength": 230.25, "previousOwner": { "firstName": "John", "lastName": "Smith" } } } }
On success, this API returns HTTP status code 200.
Create or replace a catalog item
PUT /api/catalogs/{catalogName}/items/{itemId}
Writes over (or creates) a catalog item with the values found in the request body. Any already-existing fields not included in the request body are deleted. This is an asynchronous call; 202 response code indicates that the request has been received and will be processed.
If the item specified in the URL does not exist, it is created.
A catalog item ID may contain letters, numbers, and dashes (no spaces, underscores or other special characters), must be unique, and can contain no more than 255 characters.
Example:
PUT https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckA
Request headers:
Content-Type: application/json
Sample request body:
{ "value": { "used": false } }
Sample JSON response body:
{ "msg": "", "code": "Success", "params": { "catalogName": "Trucks", "itemId": "PickupTruckA", "url": "/api/catalogs/Trucks/items/PickupTruckA" } }
On success, this API returns HTTP status code 202.
Create or update a catalog item
PATCH /api/catalogs/{catalogName}/items/{itemId}
Updates (or creates) a catalog item with the values found in the request body. Any already-existing fields not included in the request body remain as is. This is an asynchronous call; 202 response code indicates that the request has been received and will be processed.
Example:
PATCH https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckB
Request headers:
Content-Type: application/json
Sample request body:
{ "update": { "price": 45000 } }
This request updates the `price field on the catalog item in question, but it leaves all other fields on that catalog item as is.
Do not use the period character in catalog item field names.
This request overwrites every one of the fields on
PickupTruckA
, leaving nothing except theprice
field (set to45000
).
Sample JSON response body:
{ "msg": "", "code": "Success", "params": { "catalogName": "Trucks", "itemId": "PickupTruckB", "url": "/api/catalogs/Trucks/items/PickupTruckB" } }
On success, this API returns HTTP status code 202.
Delete a catalog item
DELETE /api/catalogs/{catalogName}/items/{itemId}
Deletes a single catalog item. This is an asynchronous call; 202 response code indicates that the request has been received and will be processed.
Example:
DELETE https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckA
Sample JSON response body:
{ "msg": "Received request to deleted item ID PickupTruckA from catalog Trucks", "code": "Success", "params": null }
On success, this API returns HTTP status code 202.
Bulk delete catalog items
DELETE /api/catalogs/{catalogName}/items
Deletes multiple catalog items. This is an asynchronous call; 202 response code indicates that the request has been received and will be processed.
Example:
DELETE https://api.iterable.com/api/catalogs/Trucks/items
Request headers:
Content-Type: application/json
Sample request body:
{ "itemIds": [ "PickupTruckA", "PickupTruckB" ] }
Sample JSON response body:
{ "msg": "Successfully received request to delete 2 items from catalog Trucks", "code": "Success", "params": null }
On success, this API returns HTTP status code 202.
Get field mappings (data types) for a catalog
GET /api/catalogs/{catalogName}/fieldMappings
Lists the data types assigned to the various fields found in the catalog items in a particular catalog.
Example:
GET https://api.iterable.com/api/catalogs/Trucks/fieldMappings
Sample JSON response body (no field types defined):
{ "msg": "", "code": "Success", "params": { "definedMappings": {}, "undefinedFields": [ "used", "current_location", "price", "manufactureDate", "options", "fullLength", "previousOwner" ] } }
Sample JSON response body (many field types defined):
{ "msg": "", "code": "Success", "params": { "definedMappings": { "used": "boolean", "current_location": "geo_location", "price": "long", "manufactureDate": "date", "options": "string", "previousOwner.lastName": "string", "previousOwner": "object", "previousOwner.firstName": "string", "fullLength": "double" }, "undefinedFields": [] } }
Types include:
boolean
,date
,geo_location
,long
,double
,object
andstring
previousOwner
is an object containing afirstName
field and alastName
field. All three fields come back in thedefinedMappings
field if their data types have been assigned.
On success, this API returns HTTP status code 200.
Set a catalog's field mappings (data types)
PUT /api/catalogs/{catalogName}/fieldMappings
Sets the data types for the various fields found in the catalog items in a particular catalog.
Example:
PUT https://api.iterable.com/api/catalogs/Trucks/fieldMappings
Request headers:
Content-Type: application/json
Sample request body:
{ "mappingsUpdates": [ { "fieldName": "used", "fieldType": "boolean" }, { "fieldName": "manufactureDate", "fieldType": "date" }, { "fieldName": "current_location", "fieldType": "geo_location" }, { "fieldName": "price", "fieldType": "long" }, { "fieldName": "options", "fieldType": "string" }, { "fieldName": "fullLength", "fieldType": "double" }, { "fieldName": "previousOwner", "fieldType": "object", "children": [ { "fieldName": "firstName", "fieldType": "string" }, { "fieldName": "lastName", "fieldType": "string" } ] } ] }
previousOwner
is an object containing afirstName
field and alastName
field. The above request body specifies thatpreviousOwner
is an object while its children,firstName
andlastName
, are strings.It is not possible to define types for nested object fields.
Allowed types include:
boolean
,date
,geo_location
,long
,double
,object
andstring
For a catalog collection to search previously uploaded data containing the newly typed fields (using the API or the web interface), you must re-upload or re-create that data.
Sample JSON response body:
{ "msg": "", "code": "Success", "params": null }
On success, this API returns HTTP status code 200.
Appendix: Project types
When creating a new Iterable project, you select a project type: email-based, userID-based, or hybrid. Each project types identifies its users in a different way, which affects how you identify users in API calls.
TIP
After reading the following information about Iterable's different project types, learn more by reading Project Types and Unique Identifiers.
Email-based projects
Email-based projects identify users by email
. As you create users and give
them email
addresses, Iterable enforces email
uniqueness.
In these projects, you can also identify users by userId
, but Iterable does
not enforce userId
uniqueness. Because of this, if you're not careful, you
can give the same userId
to multiple users. This can lead to unpredictable
results when making API calls.
To identify a user in an API call to an email-based project, add an email
or a
userId
(but not both) to the top level of your API request (outside of
dataFields
). If you provide both, email
takes precedence.
TIP
When calling the GDPR forget and unforget endpoints in an email-based project,
you must use email
, not userId
.
Creating new users in email-based projects
To use Iterable's API (in an email-based project) to create a new user and assign them a unique email address, make a request to one of the various endpoints that can create new users:
- Update user data (individually or in bulk)
- Target users with email and in-app campaigns
- Update subscription information
- Update the shopping cart and track purchases
- Register device and browser tokens
For example, you can call POST /api/users/update
with a request body such as:
{ "email": "user@example.com", "dataFields": { "favoriteColor": "red" } }
For this request:
- If your project doesn't yet have a user with an
email
address ofuser@example.com
, Iterables creates one. - Then, whether the user is new or already exists, Iterable sets their
favoriteColor
tored
.
Creating new users when email is unknown
To create a new user for someone with an unknown email address (in an email-based
project), provide a userId
instead of an email
.
For example, you can call POST /api/users/update
.
In the request, body:
- Don't include an
email
. - Include a unique
userId
(one that doesn't yet exist in the Iterable project). - Set
preferUserId
totrue
, which tells the API to create a new user if the provideduserId
doesn't yet exist in the project.
For example:
{ "userId": "user1234567", "preferUserId": true, "dataFields": { "favoriteColor": "red" } }
For this request:
- If your project doesn't have a user with a
userId
ofuser1234567
, Iterable creates one. - Since this is an email-based project, Iterable assigns the user a unique
email
with a@placeholder.email
domain. This is just a unique identifier, not a way to contact the user. - Then, whether the user is new or already exists, Iterable sets the user's
favoriteColor
tored
.
In subsequent API calls, you can identify this user by their userId
, or by the
placeholder email
given to them by Iterable.
Assigning a userId to an existing user
In an email-based project, you can also assign a userId
to an existing user
who is already identified by email
.
For example, you can call POST /api/users/update
.
In the request body:
- For
email
, specify the existing user's email address. - In
dataFields
, provide auserId
.
For example:
{ "email": "existingUser@example.com", "dataFields": { "userId": "newUserId" } }
For this request:
- Iterable checks to see whether your project already has a user with
email
set toexistingUser@example.com
. It not, the user is created. - Whether the user is new or already exists, Iterable assigns a
userId
ofnewUserId
to the user.
WARNING
In email-based projects, when assigning a userId
to an existing user, Iterable
does not verify that the specified userId
hasn't already been used in your
project. If you reuse a userId
on multiple users in the same project, it can
lead to unpredictable results: Iterable can't guarantee which user will be
affected by an API call that references a userId
assigned to multiple users.
UserID-based projects
UserID-based projects identify users by userId
. As you create users and give
them each a userId
, Iterable enforces userId
uniqueness. userId
values can
be a maximum of 52 characters, and they're case-sensitive.
TIP
UserID-based is often the most sensible type of project to choose, because these projects:
- Are simple to use. You always identify users by
userId
. - Allow you to match Iterable
userId
values with user identifiers you use in other systems. - Allow multiple users to share the same email address, which can sometimes be useful.
In userID-based projects, email
is not a user identifier. You can assign
email
addresses to your users (just like you can assign any other field, like
favoriteColor
), but you can't use email
to look up or modify users (in
Iterable's web UI or when making API calls). Since, in userID-based projects,
email
is a field just like any other, multiple users can have the same email
address.
TIP
When calling the GDPR forget and unforget endpoints in a userID-based project,
you must use userId
, not email
.
Creating new users in userID-based projects
In userID-based projects, when you make an API request that includes a userId
not yet used by your project, some endpoints create new users:
- Update user data (individually or in bulk)
- Target users with email and in-app campaigns
- Update subscription information
- Update the shopping cart and track purchases
- Register device and browser tokens
- Track events (individually or in bulk)
- Trigger workflows
NOTE
In API calls to userID-based projects, the API ignores the preferUserId
parameter that's sometimes used in API calls to email-based projects. There's no
need to include this parameter.
For example, you can call POST /api/users/update
,
with a request body such as:
{ "userId": "user1234567", "dataFields": { "favoriteColor": "red" } }
For this request:
- If there's no user with
userId
set touser1234567
, Iterable creates one. - Whether the user is new or already exists, Iterable sets their
favoriteColor
tored
.
Email in userID-based projects
You can assign an email
to each user in a userID-based project.
NOTE
Since email
is not a required field in userID-based projects, Iterable does
not automatically assign @placeholder.email
addresses like it does in
email-based projects.
To do this, call POST /api/users/update
,
with a request body such as:
{ "userId": "user1234567", "dataFields": { "email": "user@example.com" } }
For this request:
If there's no user with
userId
set touser1234567
, Iterable creates one.-
Whether the user is new or already exists, Iterable sets their
email
touser@example.com
.NOTE
In userID-based projects, Iterable does not enforce
email
uniqueness. This allows you to give the sameemail
to many users in the same project, which can sometimes be useful.
Hybrid projects
Hybrid projects identify users by email
, by userId
, or by both of these
values. In these projects, Iterable enforces uniqueness on both of these fields,
but it does not automatically assign them.
To identify a user in an API call to a hybrid project, add a userId
or an
email
(but not both) to the top level of your API request (outside of
dataFields
). If you provide both, userId
takes precedence.
Since email
is not a required field in hybrid projects, Iterable does not
assign @placeholder.email
addresses like it does in email-based projects.
TIP
When calling the GDPR forget and unforget endpoints in a hybrid project, you can
use either userId
or email
.
Creating new users in hybrid projects
In hybrid projects, when you make an API request that references a non-existent
userId
or email
, some endpoints create new user profiles:
- Update user data (individually or in bulk)
- Target users with email and in-app campaigns
- Update subscription information
- Update the shopping cart and track purchases
- Register device and browser tokens
- Track events (individually or in bulk)
- Trigger workflows
For example, you can call POST /api/users/update
with a request body such as:
{ "email": "user@example.com", "dataFields": { "favoriteColor": "red" } }
For this request:
- If there's no user with an
email
ofuser@example.com
, Iterable creates one. - Whether the user is new or already exists, Iterable sets their
favoriteColor
tored
.
Another example request:
{ "userId": "user1234567", "dataFields": { "favoriteColor": "red" } }
For this request:
- If there's no user with a
userId
ofuser1234567
, Iterable creates one. - Whether the user is new or already exists, Iterable sets their
favoriteColor
tored
.
NOTE
In userID-based projects, Iterable's API ignores the preferUserId
parameter
used in email-based projects for some endpoints.
email
and userId
precedence (by project type)
Generally, API requests should identify specific users by email
or userId
,
but not both, at the top level (outside of dataFields
). If a request does
include both fields, precedence rules apply.
For example, consider this request to POST /api/users/update
:
{ "email": "user@example.com", "userId": "user1234567", "dataFields": { "favoriteColor": "red" } }
In an email-based project,
email
anduserId
are both valid user identifiers. However,email
takes precedence, since it's guaranteed to be unique. So, for this request, in an email-based project, Iterable looks up or creates a user withemail
addressuser@example.com
. Then, it sets theirfavoriteColor
tored
.-
In a userID-based project,
userId
is the only valid user identifier, and it's guaranteed to be unique. So, for this request, in a userID-based project, Iterable looks up or creates a user with auserId
ofuser1234567
. Then, it sets theirfavoriteColor
tored
.As a convenience for this request, Iterable also sets the user's
email
touser@example.com
. However, sinceemail
is not a user identifier in userID-based projects, the API does not verify its uniqueness. -
In a hybrid project,
userId
andemail
are both valid user identifiers that are guaranteed to be unique. However,userId
takes precedence. So, Iterable interprets this request to mean, "Find or create a user with auserId
ofuser1234567
, and set theirfavoriteColor
tored
."As a convenience for this request, Iterable also attempts to set the user's
email
touser@example.com
(even though that value is specified outside ofdataFields
.) However, since hybrid projects enforce uniqueness onemail
, Iterable first checks whether or not the project already has a user with anemail
ofuser@example.com
.If
user@example.com
is not yet in use, the request succeeds. Iterable creates or updates a user with auserId
ofuser1234567
, settingemail
touser@example.com
andfavoriteColor
tored
.If
user@example.com
is already in use, the entire request fails with an HTTP status code409
. You can't reuse an email address that already belongs to another user.
Comments
0 comments
Please sign in to leave a comment.