API Overview and Sample Payloads

This article includes an overview of Iterable's API, how to use it, and descriptions of its various endpoints.

# Table of contents

# 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 or Api_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 or userId. However, Iterable only enforces email uniqueness—not userId.
• UserID-based projects identify users by userId, and Iterable enforces the uniqueness of this field.
• Hybrid projects projects identify users by email and/or userId, and Iterable enforces the uniqueness of both. However, you don't have to give both fields to every user.

# 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 a userId or an email (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 and userId at the top level of an API request, precedence rules apply.

  Some requests require you to place userId or email inside another object, rather than at the top level of your API request. For example, when calling POST /api/commerce/updateCart, you need to place userId or email inside a user object.

  Additionally, some requests use slightly different field names. For example, POST /api/email/target requires recipientEmail and recipientUserId, rather than email and userId. 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 of user1234567, Iterable creates one.
• Then, whether the user is new or already exists, Iterable sets their favoriteColor to red.

If this request is sent to an email-based project:

• If there's already a user identified by a userId of user1234567, Iterable updates their favoriteColor to red.
• Otherwise, the request fails. (To create a new user by userId in an email-based project, your request must set preferUserId to true. Since email is required in email-based projects, setting preferUserId to true 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

POST /api/lists/subscribe

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

DELETE /api/lists/{listId}

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

POST /api/lists/unsubscribe

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

GET /api/lists/getUsers

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

GET /api/lists

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

POST /api/lists

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 type 12345:

  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 type 12345:

  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 type 12345:

  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 type 12345:

  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, use action=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 a usersByUserId array containing the userId 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, and user1234567 to message type 12345:

  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

GET /api/events/{email}

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

POST /api/events/track

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.

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

POST /api/events/trackBulk

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

POST /api/events/inAppConsume

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.

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

POST /api/users/updateEmail

Updates a user's email.

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

POST /api/users/bulkUpdate

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 set preferUserId to true .
• 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.

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

GET /api/users/getFields

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

DELETE /api/users/{email}

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

GET /api/users/{email}

Returns a user profile (identified by email).

Learn about identifying users in API requests.

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).

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

POST /api/users/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

POST /api/users/disableDevice

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

POST /api/users/forget

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, not userId.
• In userID-based projects, you must forget and unforget users by userId, not email.
• In hybrid projects, you can forget and unforget users by email or userId (and you can use one identifier to forget, and the other to unforget).

# Unforget a user

POST /api/users/unforget

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, not userId.
• In userID-based projects, you must forget and unforget users by userId, not email.
• In hybrid projects, you can forget and unforget users by email or userId (and you can use one identifier to forget, and the other to unforget).

# Push APIs

# Send a push notification to a user

POST /api/push/target

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

GET /api/inApp/getMessages

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

POST /api/inApp/cancel

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

GET /api/inApp/target

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 /api/experiments/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

POST /api/sms/target

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

POST /api/sms/cancel

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

POST /api/verify/sms/begin

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

POST /api/verify/sms/check

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

GET /api/messageTypes

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

GET /api/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

# 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

GET /api/templates

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.

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

GET /api/templates/email/get

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

GET /api/templates/sms/get

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

GET /api/templates/push/get

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>"
 }

# 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

POST /api/campaigns/create

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

GET /api/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

GET /api/campaigns/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

POST /api/commerce/updateCart

Updates shoppingCartItems field on the user profile.

Learn about identifying users in API requests.

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.

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.

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
  }
}

# Email APIs

# Send an email to a user

POST /api/email/target

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.

Sample request body:

{
  "campaignId": 13594,
  "recipientEmail": "user@example.com",
  "dataFields": {
    "customParam": "paramValue"
  },
  "sendAt": "2015-08-31 22:00:00 +00:00"
}

# View in browser

GET /api/email/viewInBrowser

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)

GET /api/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)

GET /api/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
}

# Export user events

GET /api/export/userEvents

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

# 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

GET /api/catalogs

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 and pageSize 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 and nextPageUrl values (as applicable). Use these to load more data.

• If you specify a page and pageSize 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 and pageSize 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 and nextPageUrl values (as applicable). Use these to load more data.

• If you specify a page and pageSize 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 the price field (set to 45000).

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 and string

• previousOwner is an object containing a firstName field and a lastName field. All three fields come back in the definedMappings 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 a firstName field and a lastName field. The above request body specifies that previousOwner is an object while its children, firstName and lastName, are strings.

• It is not possible to define types for nested object fields.

• Allowed types include: boolean, date, geo_location, long, double, object and string

• 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.

# 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.

# 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 of user@example.com, Iterables creates one.
• Then, whether the user is new or already exists, Iterable sets their favoriteColor to red.

# 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 to true, which tells the API to create a new user if the provided userId 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 of user1234567, 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 to red.

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 a userId.

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 to existingUser@example.com. It not, the user is created.
• Whether the user is new or already exists, Iterable assigns a userId of newUserId to the user.

# 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.

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.

# 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

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 to user1234567, Iterable creates one.
• Whether the user is new or already exists, Iterable sets their favoriteColor to red.

# Email in userID-based projects

You can assign an email to each user in a userID-based project.

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 to user1234567, Iterable creates one.

• Whether the user is new or already exists, Iterable sets their email to user@example.com.

  NOTE

  In userID-based projects, Iterable does not enforce email uniqueness. This allows you to give the same email 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.

# 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 of user@example.com, Iterable creates one.
• Whether the user is new or already exists, Iterable sets their favoriteColor to red.

Another example request:

POST /api/users/update,

{
  "userId": "user1234567",
  "dataFields": {
     "favoriteColor": "red"
  }
}

For this request:

• If there's no user with a userId of user1234567, Iterable creates one.
• Whether the user is new or already exists, Iterable sets their favoriteColor to red.

# 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 and userId 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 with email address user@example.com. Then, it sets their favoriteColor to red.

• 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 a userId of user1234567. Then, it sets their favoriteColor to red.

  As a convenience for this request, Iterable also sets the user's email to user@example.com. However, since email is not a user identifier in userID-based projects, the API does not verify its uniqueness.

• In a hybrid project, userId and email 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 a userId of user1234567, and set their favoriteColor to red."

  As a convenience for this request, Iterable also attempts to set the user's email to user@example.com (even though that value is specified outside of dataFields.) However, since hybrid projects enforce uniqueness on email, Iterable first checks whether or not the project already has a user with an email of user@example.com.

  If user@example.com is not yet in use, the request succeeds. Iterable creates or updates a user with a userId of user1234567, setting email to user@example.com and favoriteColor to red.

  If user@example.com is already in use, the entire request fails with an HTTP status code 409. You can't reuse an email address that already belongs to another user.

# Further reading

• API Keys
• API documentation