API Overview and Sample Payloads

This article describes how to get started using Iterable's API. Additionally, it describes each of Iterable's API endpoints, and links out to API reference docs.

# In this article

# Changes to fields included in API responses

Iterable may occasionally add fields to API response bodies. Make sure that any dependencies you have on Iterable's 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.

# TLS 1.2

To call Iterable's API, you must use a client that supports TLS 1.2.

As of 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 with Iterable's API, you'll need a project-specific API key. To learn more about API keys, read API Keys.

Some important things to note about Iterable API keys:

• Each Iterable API key is associated with a specific Iterable project, which means that it's also associated with a specific data center.

  • API keys created in USDC-based Iterable projects can only be used with Iterable's USDC API endpoints.

  • API keys created in EDC-based Iterable projects can only be used with EDC-based endpoints.

• To authenticate a request with a non JWT-enabled API key, set the API key as the value of an Api-Key or Api_Key header in your request. For more information, read API keys.

• To learn how to authenticate a request with a JWT-enabled API key, read JWT-Enabled API Keys.

# Base URLs

To call Iterable's API, use the base URL associated with the Iterable data center that hosts your project.

• USDC-based Iterable projects

  • Base URL: https://api.iterable.com
  • For example: https://api.iterable.com/api/events/track

• EDC-based Iterable projects

  • Base URL: https://api.eu.iterable.com
  • For example: https://api.eu.iterable.com/api/events/track

# API reference docs

For more detail about Iterable's API (including required an optional fields), and to try sending actual API calls, visit our API reference docs:

• API docs for USDC-based Iterable projects: https://api.iterable.com/api/docs
• API docs for EDC-based Iterable projects: https://api.eu.iterable.com/api/docs

# Identifying users

Many of Iterable's API endpoints require you to specify a particular user (for example, so you can modify their user profile or fetch some data about them).

To identify a user, you'll need to provide a userId or an email in the body of your API request. This field goes in the top level of your request, or sometimes in another object that the request includes.

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

# email and userId validation

When you send an API request that includes an email or userId, Iterable validates the format of these fields.

• For email, Iterable checks that the field is a valid email address format and converts the value to lowercase. Iterable does not check the deliverability of the email address. To learn more, read Email Validation in Iterable.

• For userId, Iterable rejects requests that include userId values that don't meet certain requirements.

# 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 our API Overview.

• Inside the dataFields object in the request, place the updates you'd like to make for that user.

• Do not include empty userId values to look up users in your API request. Iterable rejects blank userId when provided to locate a record. However, API requests for email-based and hybrid projects that include userId with a null value and nested in dataFields, with intention to clear the data from a user profile, are still accepted.

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

# Avoiding race conditions when creating new fields

There is a slight processing delay when Iterable ingests a new field name. This creates the possibility of race conditions that may result in data loss. This may happen when a second API request is made in quick succession after the first.

For best results, allow a buffer of 5 minutes after adding a new field before you start using it.

Example:

First, to add a new field when user fields are locked for your project, you send an API request with createNewFields set as true. The request is successful and the response indicates a new field is created.

Then, a minute later, you send another request with the same new field, but without the override. You might expect that the new field is now recognized, however, Iterable's system is still processing. Iterable rejects the field as unrecognized and data was dropped.

# Data types

Iterable's API supports a variety of data types. When you send data to Iterable, Iterable validates the data types you send against the data types that Iterable expects.

To learn about the data types that Iterable supports, read Field Data Types.

# Campaigns

# GET /api/campaigns

List campaign metadata
API reference: USDC-based projects, EDC-based projects

Retrieves metadata about the campaigns in the project associated with the API key (for example, id, createdAt, name, templateId, etc.).

Sample JSON response:

{
  "campaigns": [
    {
      "id": 59530,
      "createdAt": 1475452500507,
      "updatedAt": 1475452500591,
      "startAt": 1475535300000,
      "endedAt": 1475542440016,
      "name": "Example campaign #1",
      "templateId": 93661,
      "createdByUserId": "user@example.com",
      "campaignState": "Finished",
      "listIds": [
        16182
      ],
      "suppressionListIds": [],
      "sendSize": 3
    },
    {
      "id": 59355,
      "createdAt": 1475265000217,
      "updatedAt": 1475265000276,
      "startAt": 1475265000274,
      "endedAt": 1475265000320,
      "name": "Example campaign #2",
      "templateId": 93419,
      "createdByUserId": "user@example.com",
      "campaignState": "Finished",
      "listIds": [
        14007
      ],
      "suppressionListIds": [],
      "sendSize": 3
    }
  ]
}

# POST /api/campaigns/abort

Abort a campaign
API reference: USDC-based projects, EDC-based projects

Abort a campaign, given a campaign ID.

# POST /api/campaigns/{campaignId}/schedule

Schedule a campaign
API reference: USDC-based projects, EDC-based projects

Schedules the send of a campaign, given its campaignId (as a path parameter).

Use this endpoint to schedule a blast campaign that is in the Ready state. This request places the campaign in the Scheduled state.

Sample request body:

{
    "sendAt": "2024-09-15T00:00:00Z",
    "recipientTimeZone": {
        "defaultTimeZone": "America/Denver",
        "startTimeZone": "America/New_York"
    }
}

# POST /api/campaigns/activateTriggered

Activate a triggered campaign
API reference: USDC-based projects, EDC-based projects

Activates a triggered campaign, given its campaignId (in the request body).

Use this endpoint to change an API-triggered campaign from the Ready state to the Running state.

Sample request body:

{
  "campaignId": 12345
}

To learn more about activating and sending triggered campaigns, read Activating a Triggered Campaign.

# POST /api/campaigns/archive

Archive campaigns
API reference: USDC-based projects, EDC-based projects

Archives one or more campaigns. This endpoint behaves the same as the archive feature in the UI. Scheduled or recurring campaigns are cancelled, and running campaigns are aborted.

Archived campaigns are hidden from the Campaigns page, but can still be viewed in the Archived tab.

Rate limit - 5 requests/second, per API key.

Sample request body:

{
  "campaignIds": [
    12345,
    12346
  ]
}

# POST /api/campaigns/cancel

Cancel a scheduled or recurring campaign
API reference: USDC-based projects, EDC-based projects

Cancel a campaign, given a campaign ID.

# POST /api/campaigns/create

Create a new campaign
API reference: USDC-based projects, EDC-based projects

Use this endpoint to create a new blast or triggered campaign from an existing template. This endpoint can create email, push notification, web push notification, SMS, and in-app message campaigns. It cannot create embedded message campaigns.

The new campaign receives a copy of the template specified by templateId. Because it's a copy, the campaign's templateId won't match the templateId specified in the request, and edits to the campaign's template will not affect the original template.

# Creating a triggered campaign

To create a triggered campaign:

• In the request body, specify a name and templateId. Add dataFields as needed.
• Omit listIds from the request body.

The new triggered campaign will be in the Ready state. Before the campaign can start sending, activate it using the POST /api/campaigns/activateTriggered endpoint or in the Iterable UI.

To learn more about activating and sending triggered campaigns, read Activating a Triggered Campaign.

Sample request body:

{
  "name": "Sample Triggered Campaign",
  "templateId": 28533
}

# Creating a blast campaign that sends immediately

To create a blast campaign that sends immediately to all specified recipients:

• In the request body, specify a name and templateId. Add dataFields as needed.
• Omit sendAt from the request body.
• Set listIds to an array of list IDs to which Iterable should send the campaign.
• If necessary, specify suppressionListIds, too.

Sample request body:

{
  "name": "Sample Blast Campaign",
  "templateId": 28533,
  "listIds": [
    5925,
    6094
  ],
  "suppressionListIds": [
    6095
  ]
}

# Creating a blast campaign scheduled for a future time

To create a blast campaign scheduled to send simultaneously to all specified recipients at a specific future time:

• In the request body, specify a name and templateId. Add dataFields as needed.
• Set listIds to an array of list IDs to which Iterable should send the campaign.
• If necessary, specify suppressionListIds.
• Set sendAt to a UTC time in format YYYY-MM-DD HH:MM:SS, to indicate when Iterable should send the campaign. For send times in the past, Iterable sends the campaign immediately.

Sample request body:

{
  "name": "Sample Blast Campaign",
  "templateId": 28533,
  "listIds": [
    5925,
    6094
  ],
  "suppressionListIds": [
    6095
  ],
  "sendAt": "2024-09-15 00:00:00"
}

# Creating a scheduled blast campaign for a future time (based on recipient time zone)

To create a blast campaign scheduled to send to each recipient at a specific local time in their own time zone:

• In the request body, specify a name and templateId. Add dataFields as needed.
• Set listIds to an array of list IDs to which Iterable should send the campaign.
• If necessary, specify suppressionListIds.
• Set sendMode to RecipientTimeZone.
• Set startTimeZone to the first time zone that should receive the campaign at the specified time.
  • Recipients in time zones to the east of startTimeZone receive the campaign at the same moment in time as recipients in startTimeZone.
  • Recipients in time zones to the west of startTimeZone receive the campaign when their local time matches the local time at which users received the campaign in startTimeZone.
• Set defaultTimeZone to the time zone to use for sending to recipients whose time zone is unknown. Use a value such as America/New_York.
• Set sendAt to a UTC time in format YYYY-MM-DD HH:MM:SS, up to 21 days in the future.
  • Iterable uses the local time in startTimeZone at sendAt as the campaign's local send time in all time zones, starting with startTimeZone and moving west.
  • For example, if sendAt represents 4:00pm in startTimeZone, Iterable sends the campaign at 4:00pm in startTimeZone, and at 4:00pm in time zones to the west of startTimeZone, too.
  • Recipients in time zones east of startTimeZone receive the message at the same moment in time as recipients in startTimeZone.
• If, when using RecipientTimeZone, you specify a past send time:
  • Recipients in startTimeZone, and time zones to the east of startTimeZone, receive the campaign immediately.
  • Recipients in time zones to the west of the startTimeZone receive the campaign when their local time matches the current local time in startTimeZone.

For example, to send a campaign on March 20th, 2024, at 4:00pm local time in all time zones starting with America/Denver:

• In the request body, Specify a name and templateId. Add dataFields as needed.
• Specify lists and suppression lists.
• Set sendMode to RecipientTimeZone.
• Set startTimeZone toAmerica/Denver.
• Set defaultTimeZoneto America/Denver (or whatever time zone you'd like to use for recipients without a time zone).
• Set sendAt to 2024-03-20 22:00:00 .
  • This UTC time is 4:00pm in the startTimeZone, which we set to America/Denver.
  • Therefore, the campaign will send at 4:00pm local time in time zones to the west of America/Denver, too.

Sample request body:

{
  "name": "Sample Blast Campaign",
  "templateId": 28533,
  "listIds": [
    5925,
    6094
  ],
  "suppressionListIds": [
    6095
  ],
  "sendMode": "RecipientTimeZone",
  "startTimeZone": "America/Denver",
  "defaultTimeZone": "America/Denver",
  "sendAt": "2024-03-20 22:00:00"
}

In this example:

• Recipients in New York (east of Denver, the starting time zone) receive the campaign at 4:00pm Denver time, which is 6:00pm local time in New York.
• Recipients in Denver receive the campaign at 4:00pm local time in Denver.
• Recipients in Los Angeles receive the campaign at 4:00pm local time in Los Angeles.
• Recipients without a timeZone field on their user profiles receive the campaign at 4:00pm Denver time, since Denver is the default time zone.

# POST /api/campaigns/deactivateTriggered

Deactivate a triggered campaign
API reference: USDC-based projects, EDC-based projects

Deactivates a triggered campaign, given its campaignId (in the request body).

Use this endpoint to change an API-triggered campaign from the Running state to the Finished state.

Sample request body:

{
  "campaignId": 12345
}

To learn more about activating and sending triggered campaigns, read Activating a Triggered Campaign.

# GET /api/campaigns/metrics

Get metrics for campaigns
API reference: USDC-based projects, EDC-based projects

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

# GET /api/campaigns/recurring/{id}/childCampaigns

Get child campaigns of a recurring campaign
API reference: USDC-based projects, EDC-based projects

Retrieves metadata about campaigns (for example, id, createdAt, name, templateId, etc.)., in the project associated with the API key, that were generated by a recurring campaign.

Sample:

GET https://api.iterable.com/api/campaigns/recurring/12345/childCampaigns

# POST /api/campaigns/trigger

Trigger a campaign
API reference: USDC-based projects, EDC-based projects

Triggers the send of a campaign to a specific user or list of users. This endpoint can be used to:

• Send a blast campaign to a specific user or list of users.
• Trigger the send of a triggered campaign to a specific user or list of users.

To learn more about activating and sending triggered campaigns, read Activating a Triggered Campaign.

# Catalogs

# GET /api/catalogs

Get catalog names
API reference: USDC-based projects, EDC-based projects

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 /api/catalogs/{catalogName}

Delete a catalog
API reference: USDC-based projects, EDC-based projects

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.

# POST /api/catalogs/{catalogName}

Create a catalog
API reference: USDC-based projects, EDC-based projects

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.

# DELETE /api/catalogs/{catalogName}/items/{itemId}

Delete a catalog item
API reference: USDC-based projects, EDC-based projects

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.

# GET /api/catalogs/{catalogName}/items/{itemId}

Get a specific catalog item
API reference: USDC-based projects, EDC-based projects

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.

# PATCH /api/catalogs/{catalogName}/items/{itemId}

Create or update a catalog item
API reference: USDC-based projects, EDC-based projects

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.

# PUT /api/catalogs/{catalogName}/items/{itemId}

Create or replace a catalog item
API reference: USDC-based projects, EDC-based projects

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.

# DELETE /api/catalogs/{catalogName}/items

Bulk delete catalog items
API reference: USDC-based projects, EDC-based projects

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 /api/catalogs/{catalogName}/items

Get the catalog items for a catalog
API reference: USDC-based projects, EDC-based projects

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.

# POST /api/catalogs/{catalogName}/items

Bulk create catalog items
API reference: USDC-based projects, EDC-based projects

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 /api/catalogs/{catalogName}/fieldMappings

Get field mappings for a catalog
API reference: USDC-based projects, EDC-based projects

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.

# PUT /api/catalogs/{catalogName}/fieldMappings

Set a catalog's field mappings (data types)
API reference: USDC-based projects, EDC-based projects

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.

# Channels

# GET /api/channels

Get channels
API reference: USDC-based projects, EDC-based projects

Lists all of the message channels contained in the Iterable 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"
    }
  ]
}

# Commerce

Commerce APIs allow you to track user purchases and update shopping carts. To learn more about how to use these APIs, read Managing Commerce Events and Shopping Cart Items

# POST /api/commerce/updateCart

Update a user's shopping cart items
API reference: USDC-based projects, EDC-based projects

Updates shoppingCartItems field on the user profile.

This endpoint's 2XX response indicates when an unrecognized field is allowed or dropped. Control this behavior by using the optional createNewFields parameter, and/or the project's setting to allow or drop fields. To learn more about this setting, read Data Schema Management Overview.

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://example.com/images/macadamianuts.jpg",
      "url": "iterable.com"
    }
  ]
}

# POST /api/commerce/trackPurchase

Track a purchase
API reference: USDC-based projects, EDC-based projects

Tracks when a user makes a purchase and clears shoppingCartItems on their profile. Including a campaignId attributes the purchase to a specific Iterable campaign.

This endpoint's 2XX response indicates when an unrecognized field is allowed or dropped. Control this behavior by using the optional createNewFields parameter, and/or the project's setting to allow or drop fields. To learn more about this setting, read Data Schema Management Overview.

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. The generated id should be stored for use in subsequent event updates.

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": "123 Main St",
    "shippingAddress2": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": 94107
  }
}

Sample response where an id of "12345" is passed in the track request:

{
    "msg": "Event with id: 12345 tracked.",
    "code": "Success",
    "params": {
        "id": "12345"
    }
}

Sample response when no id is passed in the track request:

{
    "msg": "Event with id: 1397b147db9c41f187a39844beba9c tracked.",
    "code": "Success",
    "params": {
        "id": "1397b147db9c41f187a39844beba9c"
    }
}

# Email

# POST /api/email/cancel

Cancel an email to a user
API reference: USDC-based projects, EDC-based projects

Cancels an email to a specific user. Request must include a campaignId and an email or userId, or just a scheduledMessageId.

Learn about identifying users in API requests.

# POST /api/email/target

Send an email to an email address
API reference: USDC-based projects, EDC-based projects

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

# GET /api/email/viewInBrowser

View a previously sent email
API reference: USDC-based projects, EDC-based projects

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/api/email/viewInBrowser?email=user%40example.com&messageId=340c333dea5e43cea6de24170d8a81c8

# Embedded Messaging

# GET /api/embedded-messaging/messages

Get a user's embedded messages
API reference: USDC-based projects, EDC-based projects

This endpoint tracks a single embeddedSession event, and one embeddedImpression event for each of the session's impressions.

An embeddedSession event represents a period of time when a user is viewing a page or a screen where embedded messages can be displayed (in one or many placements).

An embeddedImpression event represents the number of times a given embedded message was visible during the session, and the total amount of time the message was visible (in seconds) across all those appearances.

This endpoint does not create events for test messages (proofs).

Learn about identifying users in API requests.

Sample request:

GET https://api.iterable.com/api/embedded-messaging/messages?email=user@example.com

Sample response body:

{
  "placements": [
    {
      "placementId": 202,
      "embeddedMessages": [
        {
          "metadata": {
            "messageId": "...",
            "placementId": 0,
            "campaignId": 1234567,
            "isProof": false
          },
          "elements": {
            "title": "Take our survey!",
            "body": "Tell us how we're doing. Take our survey!",
            "mediaUrl": "https://example.com/images/example.png",
            "buttons": [
              {
                "id": "surveyButton",
                "title": "Take survey",
                "action": {
                  "type": "openUrl",
                  "data": "https://example.com/survey"
                }
              }
            ],
            "text": [
              {
                "id": "",
                "label": "color",
                "text": "#FF0000"
              }
            ],
            "defaultAction": {
              "type": "openUrl",
              "data": "https://example.com/"
            }
          },
          "payload": {
            "premiumMember": true
          }
        }
      ]
    }
  ]
}

Every embedded message returned by this endpoint has a metadata object, including messageId, placementId, campaignId, and isProof fields. Other fields are present in the API response only if they have data.

# Events

# POST /api/embedded-messaging/events/session

Track an embedded message session and related impressions
API reference: USDC-based projects, EDC-based projects

This endpoint tracks a single embeddedSession event, and one embeddedImpression event for each of the session's impressions.

An embeddedSession event represents a period of time when a user is viewing a page or a screen where embedded messages can be displayed (in one or many placements).

An embeddedImpression event represents the number of times a given embedded message was visible during the session, and the total amount of time the message was visible (in seconds) across all those appearances.

This endpoint does not create events for test messages (proofs).

Learn about identifying users in API requests.

Sample request:

POST https://api.iterable.com/api/embedded-messaging/events/session

{
  "email": "user@example.com",
  "session": {
     "id": "...",
     "start": 1699424658,
     "end": 1699424778
  },
  "impressions": [
    {
      "messageId": "...",
      "placementId": 0,
      "displayCount": 3,
      "displayDuration": 25
    },
    {
      "messageId": "...",
      "placementId": 0,
      "displayCount": 2,
      "displayDuration": 15
    }
  ],
  "deviceInfo": {
    "deviceId": "...",
    "platform": "iOS",
    "appPackageName": "com.example.app"
  },
  "createdAt": 1699424800
}

Include a userId or email, but not both. createdAt is an optional Unix timestamp that indicates when the event was created (if not provided, it's assigned the time that Iterable receives the event).

# POST /api/embedded-messaging/events/received

Track an embedded message received event
API reference: USDC-based projects, EDC-based projects

This endpoint tracks that a given embedded message was received on a device. It creates an embeddedReceived event in Iterable.

An embeddedReceived event indicates that a device has retrieved a message. It does not mean that the message has been displayed.

Iterable's SDKs automatically call this endpoint for each embedded message they retrieve. If you're not using an SDK, call this endpoint once per embedded message you retrieve from Iterable's API.

For test messages (proofs), no events are created.

Learn about identifying users in API requests.

Sample request:

POST https://api.iterable.com/api/embedded-messaging/events/received

{
  "email": "user@example.com", 
  "messageId": "...",
  "deviceInfo": {
    "deviceId": "...",
    "platform": "iOS",
    "appPackageName": "com.example.app"
  },
  "createdAt": 1699424800
}

Include a userId or email, but not both. createdAt is an optional Unix timestamp that indicates when the event was created (if not provided, it's assigned the time that Iterable receives the event).

# POST /api/embedded-messaging/events/click

Track an embedded message click
API reference: USDC-based projects, EDC-based projects

This endpoint tracks a click on an embedded message. It creates an embeddedClick event.

For test messages (proofs), no events are created.

Learn about identifying users in API requests.

Sample request:

POST https://api.iterable.com/api/embedded-messaging/events/click

{
  "email": "user@example.com",
  "messageId": "...",
  "buttonIdentifier": "surveyButton",
  "targetUrl": "https://example.com/survey",
  "deviceInfo": {
    "deviceId": "...",
    "platform": "iOS",
    "appPackageName": "com.example.app"
  },
  "createdAt": 1699424800
}

Include a userId or email, but not both. createdAt is an optional Unix timestamp that indicates when the event was created (if not provided, it's assigned the time that Iterable receives the event).

# POST /api/events/inAppConsume

Consume or delete an in-app message
API reference: USDC-based projects, EDC-based projects

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": "9c438a20d26e4e9f8ad4edea23f811cd",
  "deleteAction": "inbox-swipe",
  "messageContext": {
    "location": "inbox",
    "saveToInbox": true,
    "silentInbox": false
  },
  "deviceInfo": {
    "deviceId": "A40EB980-A3F6-ACE6-4B3C-B6CFFF641F74",
    "platform": "iOS",
    "appPackageName": "com.example.testapp"
  }
}

# POST /api/events/trackInAppClick

Track an in-app message click
API reference: USDC-based projects, EDC-based projects

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": "9c438a20d26e4e9f8ad4edea23f811cd",
  "clickedUrl": "https://www.iterable.com"
}

# POST /api/events/trackInAppClose

Track the closing of an in-app message
API reference: USDC-based projects, EDC-based projects

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": "9c438a20d26e4e9f8ad4edea23f811cd",
  "clickedUrl": "https://www.iterable.com",
  "messageContext": {
    "saveToInbox": true,
    "silentInbox": true,
    "location": "in-app"
  },
  "closeAction": "link",
  "deviceInfo": {
    "deviceId": "",
    "platform": "iOS",
    "appPackageName": "com.example.testapp"
  }
}

# POST /api/events/trackInAppDelivery

Track the delivery of an in-app message
API reference: USDC-based projects, EDC-based projects

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": "9c438a20d26e4e9f8ad4edea23f811cd",
  "messageContext": {
    "saveToInbox": true,
    "silentInbox": true
  },
  "deviceInfo": {
    "deviceId": "A40EB980-A3F6-ACE6-4B3C-B6CFFF641F74",
    "platform": "iOS",
    "appPackageName": "com.example.testapp"
  }
}

# POST /api/events/trackInAppOpen

Track an in-app message open
API reference: USDC-based projects, EDC-based projects

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": "9c438a20d26e4e9f8ad4edea23f811cd"
}

# POST /api/events/track

Track an event
API reference: USDC-based projects, EDC-based projects

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

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.

This endpoint's 2XX response indicates when an unrecognized field is allowed or dropped. Control this behavior by using the optional createNewFields parameter, and/or the project's setting to allow or drop fields. To learn more about this setting, read Data Schema Management Overview.

Sample request body:

{
  "email": "user@example.com",
  "eventName": "startedMembership",
  "id": "12345",
  "dataFields": {
    "source": "facebook",
    "membershipType": "monthly"
  },
  "userId": "1",
  "campaignId": 123,
  "templateId": 123,
  "createNewFields": true
}

In this example, source is an unrecognized data field.

Sample response body:

{
  "msg": "Event with id: f8bc79gghh47f45798b00032de21a12cf2 tracked. Fields that were created were: [startedMembership.source]",
  "code": "Success",
  "params": {
    "id": "f8bc79eebb9d4d98ba3e32d000d67dmf2"
  }
}

# POST /api/events/trackWebPushClick

Track a web push click
API reference: USDC-based projects, EDC-based projects

Learn about identifying users in API requests.

# POST /api/events/trackPushOpen

Track a mobile push open
API reference: USDC-based projects, EDC-based projects

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": "9c438a20d26e4e9f8ad4edea23f811cd",
  "dataFields": {
    "openedMostRecentPush": true
  }
}

# GET /api/events/{email}

Get user events
API reference: USDC-based projects, EDC-based projects

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/api/events/user%40example.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": "6b92db5f79874561bc5b1dd1337f7a35",
      "eventType": "emailSend"
    },
    {
      "contentId": 329261,
      "recurringCampaignId": 12345,
      "email": "user@example.com",
      "createdAt": "2016-09-30 19:50:00 +00:00",
      "campaignId": 67890,
      "templateId": 22222,
      "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
      "eventType": "emailSend"
    }
  ]
}

# GET /api/events/byUserId/{userId}

Get user events by userId
API reference: USDC-based projects, EDC-based projects

Get events for a specific user, by userId.

Learn about identifying users in API requests.

# POST /api/events/trackBulk

Bulk track events
API reference: USDC-based projects, EDC-based projects

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.

This endpoint's 2XX response indicates when an unrecognized field is allowed or dropped. Control this behavior by using the optional createNewFields parameter, and/or the project's setting to allow or drop fields. To learn more about this setting, read Data Schema Management Overview.

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

# Experiments

# GET /api/experiments/metrics

Get metrics for experiments
API reference: USDC-based projects, EDC-based projects

Get metrics for experiments(s). Note that we currently only export email experiment metrics.

Sample:

GET https://api.iterable.com/api/experiments/metrics?experimentId=12345&campaignId=23456&startDateTime=2017-06-01&endDateTime=2017-07-01

# Export

CSV, JSON, and user event export APIs are synchronous, and respond with requested data:

• GET /api/export/data.csv
• GET /api/export/data.json
• GET /api/export/userEvents

For high volume requests (up to 100GB), use Iterable's asynchronous export APIs:

• POST /api/export/start
• GET /api/export/{jobId}/files
• DELETE /api/export/{jobId}

# GET /api/export/data.csv

Export data to CSV
API reference: USDC-based projects, EDC-based projects

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.

# GET /api/export/data.json

Export data to JSON
API reference: USDC-based projects, EDC-based projects

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
}

# GET /api/export/userEvents

Export user events
API reference: USDC-based projects, EDC-based projects

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

# POST /api/export/start

Start export
API reference: USDC-based projects, EDC-based projects

Starts a data export. The export processes as a background job.

Required parameters:

• outputFormat - Type of output file: text/csv or application/x-json-stream.

• dataTypeName - Type of data to export:

  customEvent, emailBounce, emailClick, emailComplaint, emailOpen, emailSend, emailSendSkip, emailSubscribe, emailUnSubscribe, embeddedClick, embeddedDismiss, embeddedImpression, embeddedReceived, embeddedSend, embeddedSendSkip, hostedUnsubscribeClick, inAppClick, inAppClose, inAppDelete, inAppDelivery, inAppOpen, inAppRecall, inAppSend, inAppSendSkip, inboxMessageImpression, inboxSession, purchase, pushBounce, pushOpen, pushSend, pushSendSkip, pushUninstall, smsBounce, smsClick, smsReceived, smsSend, smsSendSkip, smsUsageInfo, user, webPushClick, webPushSend, webPushSendSkip

To refine your request, use any of the following optional parameters:

• startDateTime - The start of the period. Inclusive. Use any date format supported by Iterable.
• endDateTime - The end of the period to export. Exclusive. Use any date format supported by Iterable.
• omitFields - Fields to omit from the export (comma-separated).
• onlyFields - Only include these fields in the export (comma-separated). This parameter limits the export columns explicitly to what's listed. It doesn't filter out null values.
• campaignId - The campaign to export data for.
• delimiter - CSV file delimiter, default is , (comma).

Save the returned jobId to check job status and retrieve export files using GET /api/export/{jobId}/files.

Concurrent request limit: Iterable simultaneously processes up to 4 jobs per organization. Additional jobs are queued for processing later.

Sample request body:

{
    "outputFormat": "text/csv",
    "dataTypeName": "user",
    "startDateTime": "2025-01-01",
    "endDateTime": "2025-03-01",
    "onlyFields": "email,locale,firstName,lastName"
}

Sample response body:

{
  "jobId": 99999
}

# GET /api/export/{jobId}/files

Get export files
API reference: USDC-based projects, EDC-based projects

Gets the job status and links for exported files with the POST /api/export/start endpoint.

Job states can be enqueued, running, completed, or failed. Occasionally, a job status may change from running to enqueued because it had to restart. When this happens, the job maintains progress and begins where it previously stopped. Iterable uses an exponential backoff pattern for retries—when Iterable has had to retry a job several times, the delay is progressively longer.

Exports are limited to 100GB in total size, with files up to 10MB each.

Files are added to the list as the export job is running. Paginate through the files by using the last file name in the response as the startAfter value for the next request. Iterable returns up to 10 files per request.

Export files have secured links to a private Iterable repository. The links are valid for 30 minutes, and after that time you must request new links. After seven days, the files are deleted. After 30 days, all information about the job is deleted.

Example:

GET /api/export/{jobId}/files?startAfter=file-name.csv

Sample response body:

{
    "jobId": 99999,
    "jobState": "completed",
    "exportTruncated": false,
    "files": [
        {
            "file": "file-name.csv",
            "url": "<some-URL>"
        }
    ]
}

# DELETE /api/export/{jobId}

Cancel export
API reference: USDC-based projects, EDC-based projects

Cancels a queued or running export created with the POST /api/export/start endpoint.

# In-app messages

# GET /api/inApp/getPriorityMessage

Get a user's most relevant in-app message
API reference: USDC-based projects, EDC-based projects

Get a user's most relevant in-app message.

Learn about identifying users in API requests.

# GET /api/inApp/getMessages

Get a user's in-app messages
API reference: USDC-based projects, EDC-based projects

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/api/inApp/getMessages?email=user%40example.com&userId=1234&count=123

Sample JSON response:

{
  "inAppMessages": [
    {
      "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
      "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).

# POST /api/inApp/cancel

Cancel a scheduled in-app message
API reference: USDC-based projects, EDC-based projects

Cancels the sending of a scheduled in-app message to a specific user.

Sample JSON body:

{
  "email": "user@example.com",
  "campaignId": 13770
}

Learn about identifying users in API requests.

# POST /api/inApp/target

Send an in-app notification to a user
API reference: USDC-based projects, EDC-based projects

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.

Sample JSON body:

{
  "campaignId": 13770,
  "recipientEmail": "user@example.com",
  "dataFields": {
     "newUser": "FALSE"
  },
  "sendAt": "2016-08-25 23:25:00 +00:00"
}

Learn about identifying users in API requests.

# Web in-app messages

# GET /api/inApp/web/getMessages

Get a user's web in-app messages
API reference: USDC-based projects, EDC-based projects

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

# Journeys (workflows)

# GET /api/journeys

Get all journeys in the project
API reference: USDC-based projects, EDC-based projects

This endpoint returns an array of journeys that exist in the Iterable project associated with the API key found in the request.

• By default, this endpoint returns all non-archived journeys. To fetch archived journeys instead, set the state URL parameter to Archived.

• To page results, use these query parameters:

  • page – The page number to return. Default is 1.
  • pageSize – The number of journeys to return in each page. Default is 10, maximum is 50.

Sample request:

https://api.iterable.com/api/journeys?page=1&pageSize=50&state=Archived

Sample response body:

{
    "journeys": [
        {
            "id": 123456,
            "createdAt": 1623962210749,
            "updatedAt": 1623962210754,
            "name": "Example archived workflow #1",
            "journeyType": "Published",
            "creatorUserId": "user@example.com",
            "enabled": false,
            "startTileId": 2004669,
            "triggerEventNames": [
                "apiTrigger"
            ],
            "isArchived": true,
            "description": ""
        },
        {
            "id": 123499,
            "createdAt": 1629132761167,
            "updatedAt": 1629132764980,
            "name": "Example archived workflow #2",
            "journeyType": "Published",
            "creatorUserId": "user@example.com",
            "enabled": false,
            "startTileId": 2215538,
            "triggerEventNames": [
                "apiTrigger"
            ],
            "isArchived": true,
            "description": ""
        }
    ],
    "totalJourneysCount": 2
}

# POST /api/workflows/triggerWorkflow

Trigger a workflow
API reference: USDC-based projects, EDC-based projects

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

# Lists

# DELETE /api/lists/{listId}

Delete a list
API reference: USDC-based projects, EDC-based projects

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/api/lists/21398

# GET /api/lists

Get lists
API reference: USDC-based projects, EDC-based projects

Returns the project's static lists and their descriptions (if set).

Sample:

GET https://api.iterable.com/api/lists

Sample response body:

{
  "lists": [
    {
      "id": 12345,
      "name": "September subscribers",
      "description": "Users who subscribed in September 2022.",
      "createdAt": 1234567891011,
      "listType": "Standard"
    }
  ]
}

# POST /api/lists

Create a static list
API reference: USDC-based projects, EDC-based projects

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

# POST /api/lists/subscribe

Add subscribers to list
API reference: USDC-based projects, EDC-based projects

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

# POST /api/lists/unsubscribe

Remove users from a list
API reference: USDC-based projects, EDC-based projects

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 /api/lists/getUsers

Get users in a list
API reference: USDC-based projects, EDC-based projects

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/api/lists/getUsers?listId=21401

# GET /api/lists/{listId}/size

Get count of users in list
API reference: USDC-based projects, EDC-based projects

Get the number of users within a list.

# Message types

# GET /api/messageTypes

List message types
API reference: USDC-based projects, EDC-based projects

Lists all message types in the 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
    }
  ]
}

# Metadata store

# DELETE /api/metadata/{table}/{key}

Delete a single metadata key/value
API reference: USDC-based projects, EDC-based projects

Deletes the specified item from the table.

Asynchronous. 200 response indicates a valid request that will be processed. Data may not be deleted immediately. To verify completion, call GET /api/metadata/{table}/{key}.

# GET /api/metadata/{table}/{key}

Get the metadata value of a single key
API reference: USDC-based projects, EDC-based projects

Get the metadata value of a single key.

# PUT /api/metadata/{table}/{key}

Create or replace metadata
API reference: USDC-based projects, EDC-based projects

Creates or replaces the item associated with the specified key.

Asynchronous. 200 response indicates a valid request that will be processed. Updates may not be made immediately. To verify completion, call GET /api/metadata/{table}/{key}.

# DELETE /api/metadata/{table}

Delete a table
API reference: USDC-based projects, EDC-based projects

Deletes a specified table.

Asynchronous. 200 response indicates a valid request that will be processed. Table may not be deleted immediately. To verify completion, call GET /api/metadata/{table}.

# GET /api/metadata/{table}

List keys in a table
API reference: USDC-based projects, EDC-based projects

List keys in a given table.

# GET /api/metadata

List available tables
API reference: USDC-based projects, EDC-based projects

List available tables.

# Push notifications

# POST /api/push/cancel

Cancel a push notification to a user
API reference: USDC-based projects, EDC-based projects

Cancels a push notification to a specific user. Request must include a campaignId and an email or userId, or just a scheduledMessageId.

Learn about identifying users in API requests.

# POST /api/push/target

Send push notification to user
API reference: USDC-based projects, EDC-based projects

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

# SMS

# POST /api/sms/cancel

Cancel an SMS to a user
API reference: USDC-based projects, EDC-based projects

Cancels an SMS to a specific user. Must include either an email address AND campaignId, or just a scheduledMessageId.

Sample request body:

{
  "email": "user@example.com",
  "campaignId": 15354,
  "scheduledMessageId": "210badf49fe54f2591d64ad0d055f4fb",
  "userId": "1"
}

Learn about identifying users in API requests.

# POST /api/sms/target

Send SMS notification to user
API reference: USDC-based projects, EDC-based projects

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

# Subscriptions

# DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}

Unsubscribe a single user
API reference: USDC-based projects, EDC-based projects

• 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/user%40example.com
  

• Learn about identifying users in API requests.

# PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}

Subscribe a single user
API reference: USDC-based projects, EDC-based projects

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

• If you're subscribing a user to a double opt-in message type, the user skips the SMS Double Opt-In flow and is immediately subscribed to the message type. To engage a user in the SMS Double Opt-In flow, use the POST /api/subscriptions/subscribeToDoubleOptIn endpoint.

• 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/user%40example.com
  

• Learn about identifying users in API requests.

# DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/byUserId/{userId}

Unsubscribe a single user by userId
API reference: USDC-based projects, EDC-based projects

• 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
  

# PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/byUserId/{userId}

Subscribe a single user by their userId
API reference: USDC-based projects, EDC-based projects

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

• If you-re subscribing a user to a double opt-in message type, the user skips the SMS Double Opt-In flow and is immediately subscribed to the message type. To engage a user in the SMS Double Opt-In flow, use the POST /api/subscriptions/subscribeToDoubleOptIn endpoint.

• 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
  

• Learn about identifying users in API requests.

# PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}

Bulk subscription action on a list of users
API reference: USDC-based projects, EDC-based projects

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

• If you're subscribing users to a double opt-in message type, the users skip the SMS Double Opt-In flow and are immediately subscribed to the message type. To engage a user in the SMS Double Opt-In flow, use the POST /api/subscriptions/subscribeToDoubleOptIn endpoint.

• 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
  

  Request body:

  {
    "users": [
      "user@example.com",
      "user2@example.com"
    ],
    "usersByUserId": [
      "user1234567"
    ]
  }
  

# POST /api/subscriptions/subscribeToDoubleOptIn

Trigger a double opt-in subscription flow
API reference: USDC-based projects, EDC-based projects

This endpoint triggers a SMS Double Opt-In subscription flow for a user. When you call this endpoint, Iterable sends a subscription confirmation message to the user for the specified message type(s).

Once the user responds to the subscription confirmation message, Iterable subscribes them to the message types specified in the request body.

This endpoint can only be used with double opt-in message types for the SMS channel. To learn more about double opt-in message types and how to use this API, read SMS Double Opt-In.

• For messageTypeIds, provide an array of SMS double opt-in message type IDs to which the user should be subscribed.

  If the request body includes a message type that is not a double opt-in message type, the request fails with a 400 status code and an error message provides the failing message type ID.

• For userId or email, provide the user ID or email address of the user to subscribe. Learn about identifying users in API requests.

• For phoneNumber, provide the phone number to set on the specified user's profile. Required for users who don't already have a phone number set.

• For brandName, provide the brand name to use in the double opt-in confirmation message. Optional. Provide to override the brand name set in the message type.

This is an asynchronous API. It returns 202 on success.

Request body:

{
  "messageTypeIds": [
  ],
  "userId": "string",
  "email": "string",
  "phoneNumber": "string",
  "brandName": "string"
}

Sample response:

Request for double opt-in subscription accepted

# Templates

# GET /api/templates

Get project templates
API reference: USDC-based projects, EDC-based projects

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

# GET /api/templates/getByClientTemplateId

Get an email template by clientTemplateId
API reference: USDC-based projects, EDC-based projects

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.

# GET /api/templates/email/get

Get an email template by templateId
API reference: USDC-based projects, EDC-based projects

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

# POST /api/templates/email/upsert

Create email template
API reference: USDC-based projects, EDC-based projects

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

# POST /api/templates/email/update

Update email template
API reference: USDC-based projects, EDC-based projects

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

# GET /api/templates/push/get

Get a push template
API reference: USDC-based projects, EDC-based projects

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
}

# POST /api/templates/push/upsert

Create a push template
API reference: USDC-based projects, EDC-based projects

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

# POST /api/templates/push/update

Update push template
API reference: USDC-based projects, EDC-based projects

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 /api/templates/sms/get

Get an SMS template
API reference: USDC-based projects, EDC-based projects

Returns content and metadata for a specific SMS template.

Sample JSON response:

{
  "templateId": 100692,
  "name": "SMS testing",
  "message": "Here is example message",
  "messageTypeId": 4769
}

# POST /api/templates/sms/upsert

Create an SMS template
API reference: USDC-based projects, EDC-based projects

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

# POST /api/templates/sms/update

Update SMS template
API reference: USDC-based projects, EDC-based projects

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 /api/templates/inapp/get

Get an in-app template
API reference: USDC-based projects, EDC-based projects

Gets an in-app template, by templateId and locale.

# POST /api/templates/inapp/upsert

Create an in-app template
API reference: USDC-based projects, EDC-based projects

Create an in-app template if it doesn't exist yet, otherwise update all in-app templates which match the name provided.

# POST /api/templates/inapp/update

Update in-app template
API reference: USDC-based projects, EDC-based projects

Updates an in-app template.

# Users

# GET /api/users/forgotten

Get hashed forgotten users in compliance with GDPR
API reference: USDC-based projects, EDC-based projects

Returns a hash for each email address currently forgotten by your project. Each forgotten email is lowercased, trimmed, and hashed using SHA-256 encryption.

This endpoint only works for email-based and hybrid projects. For userID-based projects, use GET /api/users/forgottenUserIds.

Learn about identifying users in API requests.

# GET /api/users/forgottenUserIds

Get hashed forgotten userIds in compliance with GDPR
API reference: USDC-based projects, EDC-based projects

Returns a hash for each userId currently forgotten by your project. Each forgotten userId is lowercased, trimmed, and hashed using SHA-256 encryption.

This endpoint only works for userID-based and hybrid projects. For email-based projects, use GET /api/users/forgotten.

# POST /api/users/forget

Forget a user in compliance with GDPR
API reference: USDC-based projects, EDC-based projects

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

# POST /api/users/unforget

Unforget a user in compliance with GDPR
API reference: USDC-based projects, EDC-based projects

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. Iterable generally processes unforget requests in six hours.

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

# DELETE /api/users/{email}

Delete a user by email
API reference: USDC-based projects, EDC-based projects

Sample:

DELETE https://api.iterable.com/api/users/user%40example.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 /api/users/{email}

Get a user by email (path parameter)
API reference: USDC-based projects, EDC-based projects

Get a user by email address (passed as a path parameter).

If the email address contains non-alphanumeric characters, use GET /api/users/getByEmail instead.

Sample:

GET https://api.iterable.com/api/users/user%40example.com

Learn about identifying users in API requests.

# GET /api/users/getByEmail

Get a user by email (query parameter)
API reference: USDC-based projects, EDC-based projects

Get a user by email address (passed as a query parameter).

Returns the same data as GET /api/users/{email}, but supports email values that contain non-alphanumeric characters, which should be URL-encoded before being passed to this endpoint.

Learn about identifying users in API requests.

# POST /api/users/update

Update user data
API reference: USDC-based projects, EDC-based projects

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

This endpoint's 2XX response indicates when an unrecognized field is allowed or dropped. Control this behavior by using the optional createNewFields parameter, and/or the project's setting to allow or drop fields. To learn more about this setting, read Data Schema Management Overview.

# POST /api/users/bulkUpdate

Bulk update user data
API reference: USDC-based projects, EDC-based projects

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

This endpoint's 2XX response indicates when an unrecognized field is allowed or dropped. Control this behavior by using the optional createNewFields parameter, and/or the project's setting to allow or drop fields. To learn more about this setting, read Data Schema Management Overview.

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 or userListIds 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"
      }
    }
  ]
}

# DELETE /api/users/byUserId/{userId}

Delete user by userId
API reference: USDC-based projects, EDC-based projects

Deletes a user (identified by userId).

Sample:

GET https://api.iterable.com/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 /api/users/byUserId/{userId}

Get a user by userId (path parameter)
API reference: USDC-based projects, EDC-based projects

Get a user by userId (passed as a path parameter).

If the userId address contains non-alphanumeric characters, use GET /api/users/byUserId instead.

Sample:

GET https://api.iterable.com/api/users/byUserId?userId=testUserId

Learn about identifying users in API requests.

# GET /api/users/byUserId

Get a user by userId (query parameter)
API reference: USDC-based projects, EDC-based projects

Get a user by userId address (passed as a query parameter).

Returns the same data as GET /api/users/byUserId/{userId}, but supports userId values that contain non-alphanumeric characters, which should be URL-encoded before being passed to this endpoint.

Learn about identifying users in API requests.

# POST /api/users/registerBrowserToken

Register a browser token for web push
API reference: USDC-based projects, EDC-based projects

Learn about identifying users in API requests.

# POST /api/users/updateSubscriptions

Update user subscriptions
API reference: USDC-based projects, EDC-based projects

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",
  "userListIds": [
    5,
    6,
    7
  ],
  "unsubscribedChannelIds": [
    100
  ],
  "unsubscribedMessageTypeIds": [
    100
  ],
  "campaignId": 123,
  "templateId": 123
}

# POST /api/users/bulkUpdateSubscriptions

Bulk update user subscriptions
API reference: USDC-based projects, EDC-based projects

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

# POST /api/users/updateEmail

Update user email
API reference: USDC-based projects, EDC-based projects

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.

# GET /api/users/getFields

Get all user fields
API reference: USDC-based projects, EDC-based projects

Gets all user profile fields in a project.

Sample:

GET https://api.iterable.com/api/users/getFields

Sample JSON response:

{
  "fields": {
    "phoneNumber": "string",
    "email": "string",
    "lastName": "string",
    "firstName": "string",
    "signupDate": "date",
    "profileUpdatedAt": "date",
    "signupSource": "string"
  }
}

# GET /api/users/getSentMessages

Get messages sent to a user
API reference: USDC-based projects, EDC-based projects

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/api/users/getSentMessages?email=user%40example.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": "9c438a20d26e4e9f8ad4edea23f811cd",
      "campaignId": 123,
      "templateId": 456,
      "createdAt": "2016-10-04 00:54:00 +00:00"
    },
    {
      "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
      "campaignId": 321,
      "templateId": 654,
      "createdAt": "2016-09-30 19:50:00 +00:00"
    }
  ]
}

# POST /api/auth/jwts/invalidate

Invalidate all JWTs issued for a user
API reference: USDC-based projects, EDC-based projects

Invalidates all JWTs issued for a given user before the current time or a specified time.

# POST /api/users/disableDevice

Disable pushes to a mobile device
API reference: USDC-based projects, EDC-based projects

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

# POST /api/users/registerDeviceToken

Register a device token for push
API reference: USDC-based projects, EDC-based projects

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

# Verify

# POST /api/verify/sms/begin

Begin SMS Verification
API reference: USDC-based projects, EDC-based projects

Sends an SMS verification code to phoneNumber, using the specified verificationProfileId.

Verification codes are sent from a pool of sender IDs reserved for this purpose, not from your sender IDs.

Sample request body:

{
  "verificationProfileId": 12345,
  "phoneNumber": "+14155550132"
}

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

# POST /api/verify/sms/check

Check SMS Verification Code
API reference: USDC-based projects, EDC-based projects

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": "+14155550132",
  "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

# Webhooks

# GET /api/webhooks

Get webhooks
API reference: USDC-based projects, EDC-based projects

List the webhooks in the project.

# POST /api/webhooks

Update webhook
API reference: USDC-based projects, EDC-based projects

Update a webhook.

# Web push notifications

# POST /api/webPush/cancel

Cancel a web push notification to a user
API reference: USDC-based projects, EDC-based projects

Cancels a web push notification to a specific user. Request must include a campaignId and an email or userId, or just a scheduledMessageId.

Learn about identifying users in API requests.

# POST /api/webPush/target

Send web push notification to user
API reference: USDC-based projects, EDC-based projects

Sends a web push notification to a specific user. Request data fields override user profile data fields. A reference to the user profile is provided via the profile field, to help resolve field collisions.

Learn about identifying users in API requests.

# Want to learn more?

For more information about some of the topics in this article, check out these resources. Iterable Academy is open to everyone — you don't need to be an Iterable customer!

Iterable Academy

• Foundations: Introduction to API

Support docs

• API Keys
• API Overview and Sample Payloads
• API reference docs (USDC-based projects)
• API reference docs (EDC-based projects)