{"article":{"id":204780579,"url":"https://iterable.zendesk.com/api/v2/help_center/en-us/articles/204780579.json","html_url":"https://support.iterable.com/hc/en-us/articles/204780579-Iterable-API-Endpoints-and-Sample-Payloads","author_id":372568349631,"comments_disabled":true,"draft":false,"promoted":false,"position":0,"vote_sum":0,"vote_count":0,"upvote_count":0,"downvote_count":0,"section_id":360008913351,"created_at":"2015-07-07T01:24:56Z","updated_at":"2026-10-02T21:40:54Z","name":"Iterable API Endpoints and Sample Payloads\n","title":"Iterable API Endpoints and Sample Payloads\n","source_locale":"en-us","locale":"en-us","outdated":false,"outdated_locales":[],"edited_at":"2026-10-02T21:40:54Z","user_segment_id":null,"permission_group_id":149406,"content_tag_ids":[],"label_names":[],"body":"

Use Iterable's API to interact with a project's users, templates, campaigns,\njourneys, and more. This article describes how to use each of Iterable's API\nendpoints, and provides sample payloads.

\n# Iterable's API endpoints

\n
\n

\n# Campaigns

\n# GET /api/campaigns\n

List campaign metadata
API Explorer: USDC-based projects,\nEDC-based projects

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

When a campaign has labels:

Sample JSON response:

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

\n# GET /api/campaigns/{id}\n

Get campaign details
API Explorer: USDC-based projects,\nEDC-based projects

Retrieves detailed information about a specific campaign by its ID.

When a campaign has labels, the response includes both labels (label names)\nand labelIds (label IDs).

Sample JSON response:

{\n  \"id\": 59530,\n  \"createdAt\": 1475452500507,\n  \"updatedAt\": 1475452500591,\n  \"startAt\": 1475535300000,\n  \"endedAt\": 1475542440016,\n  \"name\": \"Example campaign #1\",\n  \"templateId\": 93661,\n  \"createdByUserId\": \"user@example.com\",\n  \"campaignState\": \"Finished\",\n  \"messageMedium\": \"Email\",\n  \"listIds\": [\n    16182\n  ],\n  \"suppressionListIds\": [],\n  \"sendSize\": 3,\n  \"labelIds\": [\n    12345\n  ],\n  \"labels\": [\n    \"newsletter\"\n  ],\n  \"dataFields\": {\n    \"customField\": \"value\"\n  },\n  \"sendMode\": \"Immediate\",\n  \"recipientTimeZone\": {\n    \"defaultTimeZone\": \"America/New_York\",\n    \"startTimeZone\": \"America/New_York\"\n  }\n}\n
\n

\n# POST /api/campaigns/abort\n

Abort a campaign
API Explorer: USDC-based projects,\nEDC-based projects

Abort a campaign, given a campaign ID.

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

Schedule a campaign
API Explorer: USDC-based projects,\nEDC-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.\nThis request places the campaign in the Scheduled state.

Sample request body:

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

\n# POST /api/campaigns/activateTriggered\n

Activate a triggered campaign
API Explorer: USDC-based projects,\nEDC-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\nto the Running state.

Sample request body:

{\n  \"campaignId\": 12345\n}\n
\n

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

\n# POST /api/campaigns/archive\n

Archive campaigns
API Explorer: USDC-based projects,\nEDC-based projects

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

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

Sample request body:

{\n  \"campaignIds\": [\n    12345,\n    12346\n  ]\n}\n
\n

\n# POST /api/campaigns/cancel\n

Cancel a scheduled or recurring campaign
API Explorer: USDC-based projects,\nEDC-based projects

Cancel a campaign, given a campaign ID.

\n# POST /api/campaigns/create\n

Create a new campaign
API Explorer: USDC-based projects,\nEDC-based projects

Use this endpoint to create a new blast or triggered campaign from an existing\ntemplate. This endpoint can create email, push notification, web push\nnotification, SMS, and in-app message campaigns. It can't create embedded\nmessage campaigns. Global suppression lists\nare not automatically applied to campaigns created by this endpoint. If you\nwant to apply a global suppression list to a campaign created with this endpoint,\ninclude the list ID in the suppressionListIds request parameter.

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

To associate existing labels with the new campaign, include labelIds in the\nrequest body. labelIds must contain label IDs from the same project, and you\ncan include up to 50 label IDs. You can find the ID for each label in the\nProject Settings page.

\n

TIP

To learn more about starting and default time zones, read\nSending or Scheduling a Blast Campaign.

\n

\n# Creating a triggered campaign

To create a triggered campaign:

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

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

Sample request body:

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

\n# Creating a blast campaign that sends immediately

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

Sample request body:

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

\n# Creating a campaign with labels

To create a blast or triggered campaign with labels, include labelIds in the\nrequest body. Labels must already exist in the project, and you can include up to\n50 label IDs. You can find the ID for each label in the Project Settings page.

Sample request body:

{\n  \"name\": \"Sample Blast Campaign\",\n  \"templateId\": 28533,\n  \"listIds\": [\n    5925,\n    6094\n  ],\n  \"labelIds\": [\n    12345,\n    67890\n  ]\n}\n
\n

\n# Creating a blast campaign scheduled for a future time

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

Sample request body:

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

\n# 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\nlocal time in their own time zone:

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

Sample request body:

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

In this example:

\n# POST /api/campaigns/deactivateTriggered\n

Deactivate a triggered campaign
API Explorer: USDC-based projects,\nEDC-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\nstate to the Finished state.

Sample request body:

{\n  \"campaignId\": 12345\n}\n
\n

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

\n# GET /api/campaigns/metrics\n

Get metrics for campaigns
API Explorer: USDC-based projects,\nEDC-based projects

Gets analytic info such as id, bounces, clicks, conversions, purchases,\netc. from a campaign. A start and end date can be added to select the desired\nrange 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 \n59355,0,0,,0,0,,,,,0.0,3,,,,0,0,0,,0\n
\n

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

Get child campaigns of a recurring campaign
API Explorer: USDC-based projects,\nEDC-based projects

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

Sample:

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

Sample JSON response excerpt:

{\n  \"campaigns\": [\n    {\n      \"id\": 12346,\n      \"name\": \"Example recurring campaign send\",\n      \"messageMedium\": \"Email\",\n      \"labelIds\": [12345],\n      \"labels\": [\"newsletter\"]\n    }\n  ]\n}\n
\n

\n# POST /api/campaigns/trigger\n

Trigger a campaign
API Explorer: USDC-based projects,\nEDC-based projects

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

\n

NOTE

Iterable's built-in campaign sending limit (which prevents a marketing campaign\nfrom being sent to the same user twice in an 18-hour period) applies to all\nmessages sent from a marketing channel,\nincluding triggered messages. To override this limit for a given triggered\ncampaign, include \"allowRepeatMarketingSends\": true in the request body of the\nAPI call.

\n

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

\n# POST /api/campaigns/{campaignId}/send\n

Send existing campaign now
API Explorer: USDC-based projects,\nEDC-based projects

Sends an existing campaign immediately. This endpoint can be used to send a\ncampaign that is in the Ready state.

Sample JSON response:

{\n  \"success\": true,\n  \"messageId\": \"12345\"\n}\n
\n

\n# Catalogs

\n# GET /api/catalogs\n

Get catalog names
API Explorer: USDC-based projects,\nEDC-based projects

Lists the names of all catalogs in the project associated with an API key.

Example:

GET https://api.iterable.com/api/catalogs\n
\n

Paging:

Sample JSON response body:

{\n  \"msg\": \"\",\n  \"code\": \"Success\",\n  \"params\": {\n    \"catalogNames\": [\n      {\n        \"name\": \"Trucks\"\n      }\n    ],\n    \"totalCatalogsCount\": 1\n  }\n}\n
\n

On success, this API returns HTTP status code 200.

\n# DELETE /api/catalogs/{catalogName}\n

Delete a catalog
API Explorer: USDC-based projects,\nEDC-based projects

Deletes a catalog and all its items. This cannot be undone.

Example:

DELETE https://api.iterable.com/api/catalogs/Trucks\n
\n

Sample JSON response body:

{\n  \"msg\": \"Successfully deleted catalog Trucks\",\n  \"code\": \"Success\",\n  \"params\": null\n}\n
\n

On success, this API returns HTTP status code 200.

\n# POST /api/catalogs/{catalogName}\n

Create a catalog
API Explorer: USDC-based projects,\nEDC-based projects

Creates a new catalog in the project associated with the API key. Each catalog\nin an Iterable project must have a unique name that is no longer than 255\ncharacters and contains only letters, numbers and dashes (no spaces, underscores\nor other special characters).

Example:

POST https://api.iterable.com/api/catalogs/Trucks\n
\n

Sample JSON response body:

{\n  \"msg\": \"\",\n  \"code\": \"Success\",\n  \"params\": {\n    \"id\": 740,\n    \"name\": \"Trucks\",\n    \"url\": \"/api/catalogs/Trucks\"\n  }\n}\n
\n

On success, this API returns HTTP status code 201.

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

Delete a catalog item
API Explorer: USDC-based projects,\nEDC-based projects

Deletes a single catalog item. This is an asynchronous call; 202 response code\nindicates that the request has been received and will be processed.

Example:

DELETE https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckA\n
\n

Sample JSON response body:

{\n  \"msg\": \"Received request to deleted item ID PickupTruckA from catalog Trucks\",\n  \"code\": \"Success\",\n  \"params\": null\n}\n
\n

On success, this API returns HTTP status code 202.

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

Get a specific catalog item
API Explorer: USDC-based projects,\nEDC-based projects

Gets the details of a specific catalog item.

Example:

GET https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckA\n
\n

Sample JSON response body:

{\n  \"msg\": \"\",\n  \"code\": \"Success\",\n  \"params\": {\n    \"catalogName\": \"Trucks\",\n    \"itemId\": \"PickupTruckA\",\n    \"size\": 251,\n    \"lastModified\": 1555662886000,\n    \"value\": {\n      \"used\": false,\n      \"current_location\": {\n        \"lat\": 37.773972,\n        \"lon\": -122.431297\n      },\n      \"price\": 35000,\n      \"manufactureDate\": \"2019-01-15\",\n      \"options\": [\n        \"manual transmission\",\n        \"sunroof\",\n        \"premium stereo\"\n      ],\n      \"fullLength\": 230.25,\n      \"previousOwner\": {\n        \"firstName\": \"John\",\n        \"lastName\": \"Smith\"\n      }\n    }\n  }\n}\n
\n

On success, this API returns HTTP status code 200.

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

Create or update a catalog item
API Explorer: USDC-based projects,\nEDC-based projects

Updates (or creates) a catalog item with the values found in the request body.\nAny already-existing fields not included in the request body remain as is.\nThis is an asynchronous call; 202 response code indicates that the request has\nbeen received and will be processed.

Example:

PATCH https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckB\n
\n

Request headers:

Sample request body:

{\n  \"update\": {\n    \"price\": 45000\n  }\n}\n
\n

Sample JSON response body:

{\n  \"msg\": \"\",\n  \"code\": \"Success\",\n  \"params\": {\n    \"catalogName\": \"Trucks\",\n    \"itemId\": \"PickupTruckB\",\n    \"url\": \"/api/catalogs/Trucks/items/PickupTruckB\"\n  }\n}\n
\n

On success, this API returns HTTP status code 202.

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

Create or replace a catalog item
API Explorer: USDC-based projects,\nEDC-based projects

Writes over (or creates) a catalog item with the values found in the request\nbody. Any already-existing fields not included in the request body are deleted.\nThis is an asynchronous call; 202 response code indicates that the request has\nbeen 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,\nunderscores or other special characters), must be unique, and can contain no\nmore than 255 characters.

Example:

PUT https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckA\n
\n

Request headers:

Sample request body:

{\n  \"value\": {\n    \"used\": false\n  }\n}\n
\n

Sample JSON response body:

{\n  \"msg\": \"\",\n  \"code\": \"Success\",\n  \"params\": {\n    \"catalogName\": \"Trucks\",\n    \"itemId\": \"PickupTruckA\",\n    \"url\": \"/api/catalogs/Trucks/items/PickupTruckA\"\n  }\n}\n
\n

On success, this API returns HTTP status code 202.

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

Bulk delete catalog items
API Explorer: USDC-based projects,\nEDC-based projects

Deletes multiple catalog items. This is an asynchronous call; 202 response code\nindicates that the request has been received and will be processed.

Example:

DELETE https://api.iterable.com/api/catalogs/Trucks/items\n
\n

Request headers:

Sample request body:

{\n  \"itemIds\": [\n    \"PickupTruckA\",\n    \"PickupTruckB\"\n  ]\n}\n
\n

Sample JSON response body:

{\n  \"msg\": \"Successfully received request to delete 2 items from catalog Trucks\",\n  \"code\": \"Success\",\n  \"params\": null\n}\n
\n

On success, this API returns HTTP status code 202.

\n# GET /api/catalogs/{catalogName}/items\n

Get the catalog items for a catalog
API Explorer: USDC-based projects,\nEDC-based projects

Lists all catalog items in a catalog.

Example:

GET https://api.iterable.com/api/catalogs/Trucks/items\n
\n

Paging:

Sample JSON response body:

{\n  \"msg\": \"\",\n  \"code\": \"Success\",\n  \"params\": {\n    \"catalogItemsWithProperties\": [\n      {\n        \"catalogName\": \"Trucks\",\n        \"itemId\": \"PickupTruckB\",\n        \"size\": 242,\n        \"lastModified\": 1555662886000,\n        \"value\": {\n          \"used\": true,\n          \"current_location\": {\n            \"lat\": 39.742043,\n            \"lon\": -104.991531\n          },\n          \"price\": 29500,\n          \"manufactureDate\": \"2018-06-12\",\n          \"options\": [\n            \"automatic transmission\",\n            \"keyless entry\"\n          ],\n          \"fullLength\": 215.75,\n          \"previousOwner\": {\n            \"firstName\": \"Jane\",\n            \"lastName\": \"Jones\"\n          }\n        }\n      },\n      {\n        \"catalogName\": \"Trucks\",\n        \"itemId\": \"PickupTruckA\",\n        \"size\": 251,\n        \"lastModified\": 1555662886000,\n        \"value\": {\n          \"used\": false,\n          \"current_location\": {\n            \"lat\": 37.773972,\n            \"lon\": -122.431297\n          },\n          \"price\": 35000,\n          \"manufactureDate\": \"2019-01-15\",\n          \"options\": [\n            \"manual transmission\",\n            \"sunroof\",\n            \"premium stereo\"\n          ],\n          \"fullLength\": 230.25,\n          \"previousOwner\": {\n            \"firstName\": \"John\",\n            \"lastName\": \"Smith\"\n          }\n        }\n      }\n    ],\n    \"totalItemsCount\": 2\n  }\n}\n
\n

On success, this API returns HTTP status code 200.

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

Bulk create catalog items
API Explorer: USDC-based projects,\nEDC-based projects

Creates up to 1,000 catalog items at a time (each one having a max size of 30kb).\nThis is an asynchronous API; 202 response code indicates that the request has\nbeen received and will be processed.

The request body should specify a JSON object with a top-level document key\nand an associated object. In the document object, each key corresponds to the\nID of a catalog item, and the key's associated object contains the catalog\nitem's fields.

Catalog items must have unique IDs (within a catalog). They may contain letters,\nnumbers and dashes (no spaces, underscores or other special characters), and\nmust be no longer than 255 characters.

If the catalog already contains an item having the same ID as one provided in\nthe request body, the existing item is completely overwritten by the item\nspecified in the request body Do not use the period character in catalog item\nfield names.

Example:

POST https://api.iterable.com/api/catalogs/Trucks/items\n
\n

Request headers:

Sample request body:

{\n  \"documents\": {\n    \"PickupTruckA\": {\n      \"options\": [\n        \"manual transmission\",\n        \"sunroof\",\n        \"premium stereo\"\n      ],\n      \"manufactureDate\": \"2019-01-15\",\n      \"current_location\": {\n        \"lat\": 37.773972,\n        \"lon\": -122.431297\n      },\n      \"fullLength\": 230.25,\n      \"used\": true,\n      \"price\": 35000,\n      \"previousOwner\": {\n        \"firstName\": \"John\",\n        \"lastName\": \"Smith\"\n      }\n    },\n    \"PickupTruckB\": {\n      \"options\": [\n        \"automatic transmission\",\n        \"keyless entry\"\n      ],\n      \"manufactureDate\": \"2018-06-12\",\n      \"current_location\": {\n        \"lat\": 39.742043,\n        \"lon\": -104.991531\n      },\n      \"fullLength\": 215.75,\n      \"used\": true,\n      \"price\": 29500,\n      \"previousOwner\": {\n        \"firstName\": \"Jane\",\n        \"lastName\": \"Jones\"\n      }\n    }\n  }\n}\n
\n

Sample JSON response body:

{\n  \"msg\": \"Request to bulk-upload documents into Trucks processed successfully\",\n  \"code\": \"Success\",\n  \"params\": null\n}\n
\n

On success, this API returns HTTP status code 202.

\n# GET /api/catalogs/{catalogName}/fieldMappings\n

Get field mappings for a catalog
API Explorer: USDC-based projects,\nEDC-based projects

Lists the data types assigned to the various fields found in the catalog items\nin a particular catalog.

Example:

GET https://api.iterable.com/api/catalogs/Trucks/fieldMappings\n
\n

Sample JSON response body (no field types defined):

{\n  \"msg\": \"\",\n  \"code\": \"Success\",\n  \"params\": {\n    \"definedMappings\": {},\n    \"undefinedFields\": [\n      \"used\",\n      \"current_location\",\n      \"price\",\n      \"manufactureDate\",\n      \"options\",\n      \"fullLength\",\n      \"previousOwner\"\n    ]\n  }\n}\n
\n

Sample JSON response body (many field types defined):

{\n  \"msg\": \"\",\n  \"code\": \"Success\",\n  \"params\": {\n    \"definedMappings\": {\n      \"used\": \"boolean\",\n      \"current_location\": \"geo_location\",\n      \"price\": \"long\",\n      \"manufactureDate\": \"date\",\n      \"options\": \"string\",\n      \"previousOwner.lastName\": \"string\",\n      \"previousOwner\": \"object\",\n      \"previousOwner.firstName\": \"string\",\n      \"fullLength\": \"double\"\n    },\n    \"undefinedFields\": []\n  }\n}\n
\n

On success, this API returns HTTP status code 200.

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

Set a catalog's field mappings (data types)
API Explorer: USDC-based projects,\nEDC-based projects

Sets the data types for the various fields found in the catalog items in a\nparticular catalog.

Example:

PUT https://api.iterable.com/api/catalogs/Trucks/fieldMappings\n
\n

Request headers:

Sample request body:

{\n  \"mappingsUpdates\": [\n    {\n      \"fieldName\": \"used\",\n      \"fieldType\": \"boolean\"\n    },\n    {\n      \"fieldName\": \"manufactureDate\",\n      \"fieldType\": \"date\"\n    },\n    {\n      \"fieldName\": \"current_location\",\n      \"fieldType\": \"geo_location\"\n    },\n    {\n      \"fieldName\": \"price\",\n      \"fieldType\": \"long\"\n    },\n    {\n      \"fieldName\": \"options\",\n      \"fieldType\": \"string\"\n    },\n    {\n      \"fieldName\": \"fullLength\",\n      \"fieldType\": \"double\"\n    },\n    {\n      \"fieldName\": \"previousOwner\",\n      \"fieldType\": \"object\",\n      \"children\": [\n        {\n          \"fieldName\": \"firstName\",\n          \"fieldType\": \"string\"\n        },\n        {\n          \"fieldName\": \"lastName\",\n          \"fieldType\": \"string\"\n        }\n      ]\n    }\n  ]\n}\n
\n

Sample JSON response body:

{\n    \"msg\": \"\",\n    \"code\": \"Success\",\n    \"params\": null\n}\n
\n

On success, this API returns HTTP status code 200.

\n# Channels

\n# GET /api/channels\n

Get channels
API Explorer: USDC-based projects,\nEDC-based projects

Lists all of the message channels contained in the Iterable project.

Sample JSON response:

{\n  \"channels\": [\n    {\n      \"id\": 3422,\n      \"name\": \"Push Marketing Channel\",\n      \"channelType\": \"Marketing\",\n      \"messageMedium\": \"Push\"\n    },\n    {\n      \"id\": 3421,\n      \"name\": \"Transactional Channel\",\n      \"channelType\": \"Transactional\",\n      \"messageMedium\": \"Email\"\n    },\n    {\n      \"id\": 3420,\n      \"name\": \"Marketing Channel\",\n      \"channelType\": \"Marketing\",\n      \"messageMedium\": \"Email\"\n    }\n  ]\n}\n
\n

\n# Commerce

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

\n# POST /api/commerce/updateCart\n

Update a user's shopping cart items
API Explorer: USDC-based projects,\nEDC-based projects

Updates shoppingCartItems field on the user profile.

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

Learn about identifying users in API requests.

\n

NOTE

It's generally best to treat price as a double, not a long. To do that,\ninclude a number with a decimal in the first call that you use to cast that\nfield. Use a non-zero decimal value to cast the field as a double (example:\n5.55). Otherwise, the field is cast as a long.

\n

Sample request body:

{\n  \"user\": {\n    \"email\": \"user@example.com\",\n    \"dataFields\": {\n      \"currentCartTotal\": 34\n    },\n    \"userId\": \"1\",\n    \"mergeNestedObjects\": true\n  },\n  \"items\": [\n    {\n      \"id\": \"2\",\n      \"sku\": \"4\",\n      \"name\": \"Iterable T-shirt\",\n      \"description\": \"100% cotton shirt. Show how much you love your favorite marketing automation platform!\",\n      \"categories\": [\n        \"clothing\",\n        \"swag\"\n      ],\n      \"price\": 20.5,\n      \"quantity\": 1,\n      \"imageUrl\": \"https://static.iterable.com/iterable/15-10-03-iterableshirt.png\",\n      \"url\": \"iterable.com\"\n    },\n    {\n      \"id\": \"3\",\n      \"sku\": \"5\",\n      \"name\": \"Macadamia Nuts\",\n      \"description\": \"Full of healthy fats! Made in Hawaii.\",\n      \"categories\": [\n        \"food\"\n      ],\n      \"price\": 5.5,\n      \"quantity\": 2,\n      \"imageUrl\": \"https://example.com/images/macadamianuts.jpg\",\n      \"url\": \"iterable.com\"\n    }\n  ]\n}\n
\n

\n# POST /api/commerce/trackPurchase\n

Track a purchase
API Explorer: USDC-based projects,\nEDC-based projects

Tracks when a user makes a purchase and clears shoppingCartItems on their\nprofile. Including a campaignId attributes the purchase to a specific Iterable\ncampaign.

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

Learn about identifying users in API requests.

\n

NOTE

We recommend casting the required price and total fields as doubles instead\nof longs. To do that, include a number with a decimal in the first call that you\nuse to cast that field. Use a non-zero decimal value to cast the field as a\ndouble (example: 5.55). Otherwise, the field is be cast as a long.

\n

An optional string id parameter may be passed as one of the top-level\nparameters. If a purchase event exists with that id, the event is updated. If\nno id is specified, a new id is automatically generated and returned. The\ngenerated id should be stored for use in subsequent event updates.

An id value:

\n

NOTE

The createdAt field can be blank for new purchase events, and will be set to\nthe time the event is received. Set this value (as a Unix formatted timestamp)\nonly if you're sending historic events.

\n

Sample request body:

{\n  \"user\": {\n    \"email\": \"user@example.com\",\n    \"dataFields\": {\n      \"totalPurchases\": 5\n    },\n    \"userId\": \"1\"\n  },\n  \"items\": [\n    {\n      \"id\": \"1\",\n      \"sku\": \"1\",\n      \"name\": \"Iterable Stickers\",\n      \"description\": \"Put these stickers anywhere and everywhere!\",\n      \"categories\": [\n        \"stickers\",\n        \"novelty\"\n      ],\n      \"price\": 5.5,\n      \"quantity\": 2,\n      \"imageUrl\": \"https://static.iterable.com/iterable-demo-v1/15-03-04-Iterable_stickers.jpg\",\n      \"url\": \"iterable.com\"\n    }\n  ],\n  \"campaignId\": 14348,\n  \"templateId\": 29592,\n  \"total\": 11,\n  \"dataFields\": {\n    \"shippingAddress1\": \"123 Main St\",\n    \"shippingAddress2\": \"\",\n    \"city\": \"San Francisco\",\n    \"state\": \"CA\",\n    \"zip\": 94107\n  }\n}\n
\n

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

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

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

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

NOTE

The POST /api/commerce/trackPurchase\nendpoint requires an array of items, but any events that are created by\ninvoking this endpoint contain an array named shoppingCartItems (not\nitems).

When segmenting your users into lists, you can access data in this array by\nreferencing the shoppingCartItems field (not items).

Similarly, journeys that are triggered by trackPurchase can access data in\nthis array by referencing shoppingCartItems (not items).

\n

\n# Email

\n# POST /api/email/cancel\n

Cancel an email to a user
API Explorer: USDC-based projects,\nEDC-based projects

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

Learn about identifying users in API requests.

\n# POST /api/email/target\n

Send an email to an email address
API Explorer: USDC-based projects,\nEDC-based projects

Sends a triggered email campaign to specified email address. If sendAt field\nis not included, the message is sent immediately. The JSON passed in the\ndataFields section is indexed on the emailSend event as transactionalData.

Learn about identifying users in API requests.

\n

NOTE

This is an asynchronous call; a 200 response means that the request has been\nreceived, not that the email has been sent.

\n

Sample request body:

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

\n# GET /api/email/viewInBrowser\n

View a previously sent email
API Explorer: USDC-based projects,\nEDC-based projects

View a copy of a previously sent email. Must include both a user's email address\nand the message id of the sent email.

Sample:

GET https://api.iterable.com/api/email/viewInBrowser?email=user%40example.com&messageId=340c333dea5e43cea6de24170d8a81c8\n
\n

\n# Embedded Messaging

\n# GET /api/embedded-messaging/messages\n

Get a user's embedded messages
API Explorer: USDC-based projects,\nEDC-based projects

This endpoint returns embedded messages for which the specified user is eligible,\ngrouped by placementId.\nA user is eligible if they're selected by the dynamic list that's associated with\nthe message's Iterable campaign.

By default, this endpoint returns data for all placements that have messages for\nthe user. To constrain the response to specific placements, provide one or more\nplacementId query parameters.

Sample request:

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

Sample response body:

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

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

\n# Events

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

Track an embedded message session and related impressions
API Explorer: USDC-based projects,\nEDC-based projects

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

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

An embeddedImpression\nevent represents the number of times a given embedded message was visible during\nthe session, and the total amount of time the message was visible (in seconds)\nacross 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\n
\n
{\n  \"email\": \"user@example.com\",\n  \"session\": {\n     \"id\": \"...\",\n     \"start\": 1699424658,\n     \"end\": 1699424778\n  },\n  \"impressions\": [\n    {\n      \"messageId\": \"...\",\n      \"placementId\": 0,\n      \"displayCount\": 3,\n      \"displayDuration\": 25\n    },\n    {\n      \"messageId\": \"...\",\n      \"placementId\": 0,\n      \"displayCount\": 2,\n      \"displayDuration\": 15\n    }\n  ],\n  \"deviceInfo\": {\n    \"deviceId\": \"...\",\n    \"platform\": \"iOS\",\n    \"appPackageName\": \"com.example.app\"\n  },\n  \"createdAt\": 1699424800\n}\n
\n

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

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

Track an embedded message received event
API Explorer: USDC-based projects,\nEDC-based projects

This endpoint tracks that a given embedded message was received on a device. It\ncreates an embeddedReceived\nevent in Iterable.

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

Iterable's SDKs automatically call this endpoint for each embedded message they\nretrieve. If you're not using an SDK, call this endpoint once per embedded\nmessage 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\n
\n
{\n  \"email\": \"user@example.com\", \n  \"messageId\": \"...\",\n  \"deviceInfo\": {\n    \"deviceId\": \"...\",\n    \"platform\": \"iOS\",\n    \"appPackageName\": \"com.example.app\"\n  },\n  \"createdAt\": 1699424800\n}\n
\n

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

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

Track an embedded message click
API Explorer: USDC-based projects,\nEDC-based projects

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

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\n
\n
{\n  \"email\": \"user@example.com\",\n  \"messageId\": \"...\",\n  \"buttonIdentifier\": \"surveyButton\",\n  \"targetUrl\": \"https://example.com/survey\",\n  \"deviceInfo\": {\n    \"deviceId\": \"...\",\n    \"platform\": \"iOS\",\n    \"appPackageName\": \"com.example.app\"\n  },\n  \"createdAt\": 1699424800\n}\n
\n

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

\n# POST /api/events/inAppConsume\n

Consume or delete an in-app message
API Explorer: USDC-based projects,\nEDC-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\ncall it automatically.

Learn about identifying users in API requests.

If an incoming in-app message is not configured to use the mobile inbox, use\nthis API to \"consume\" it from the server queue after the user sees it.\nOtherwise, call this API when the user explicitly deletes an inbox-enabled\nmessage (by clicking a delete button in its content, swiping it in the inbox,\netc.).

If you pass a deleteAction value to this endpoint, Iterable generates an\ninAppDelete event (otherwise, it does not).

Sample request body:

{\n  \"email\": \"user@example.com\",\n  \"userId\": \"user123\",\n  \"messageId\": \"9c438a20d26e4e9f8ad4edea23f811cd\",\n  \"deleteAction\": \"inbox-swipe\",\n  \"messageContext\": {\n    \"location\": \"inbox\",\n    \"saveToInbox\": true,\n    \"silentInbox\": false\n  },\n  \"deviceInfo\": {\n    \"deviceId\": \"A40EB980-A3F6-ACE6-4B3C-B6CFFF641F74\",\n    \"platform\": \"iOS\",\n    \"appPackageName\": \"com.example.testapp\"\n  }\n}\n
\n

\n# POST /api/events/trackInAppClick\n

Track an in-app message click
API Explorer: USDC-based projects,\nEDC-based projects

Creates an inAppClick event for the specified user, message and URL. When not\nusing one of Iterable's mobile SDKs, call this endpoint when a user taps on a\nbutton or link in an in-app message.

Learn about identifying users in API requests.

Sample request body:

{\n  \"email\": \"user@example.com\",\n  \"userId\": \"user123\",\n  \"messageId\": \"9c438a20d26e4e9f8ad4edea23f811cd\",\n  \"clickedUrl\": \"https://www.iterable.com\"\n}\n
\n

\n# POST /api/events/trackInAppClose\n

Track the closing of an in-app message
API Explorer: USDC-based projects,\nEDC-based projects

Creates an inAppClose event for a specific user and in-app message. When not\nusing Iterable's mobile SDKs, call this endpoint to indicate that the user\ntapped a close button or link to close a particular in-app message.

Learn about identifying users in API requests.

Sample request body:

{\n  \"email\": \"user@example.com\",\n  \"userId\": \"user123\",\n  \"messageId\": \"9c438a20d26e4e9f8ad4edea23f811cd\",\n  \"clickedUrl\": \"https://www.iterable.com\",\n  \"messageContext\": {\n    \"saveToInbox\": true,\n    \"silentInbox\": true,\n    \"location\": \"in-app\"\n  },\n  \"closeAction\": \"link\",\n  \"deviceInfo\": {\n    \"deviceId\": \"\",\n    \"platform\": \"iOS\",\n    \"appPackageName\": \"com.example.testapp\"\n  }\n}\n
\n

\n# POST /api/events/trackInAppDelivery\n

Track the delivery of an in-app message
API Explorer: USDC-based projects,\nEDC-based projects

Creates an inAppDelivery event for a specific user, device and message. When\nnot using Iterable's mobile SDKs, call this endpoint to indicate that a\nparticular message has been delivered to a particular device for a particular\nuser. Take care not to call this endpoint multiple times for the same\nmessage/device/user combination.

Learn about identifying users in API requests.

Sample request body:

{\n  \"email\": \"user@example.com\",\n  \"userId\": \"user123\",\n  \"messageId\": \"9c438a20d26e4e9f8ad4edea23f811cd\",\n  \"messageContext\": {\n    \"saveToInbox\": true,\n    \"silentInbox\": true\n  },\n  \"deviceInfo\": {\n    \"deviceId\": \"A40EB980-A3F6-ACE6-4B3C-B6CFFF641F74\",\n    \"platform\": \"iOS\",\n    \"appPackageName\": \"com.example.testapp\"\n  }\n}\n
\n

\n# POST /api/events/trackInAppOpen\n

Track an in-app message open
API Explorer: USDC-based projects,\nEDC-based projects

Creates an inAppOpen event for the specified user and message. When not using\none of Iterable's mobile SDKs, call this endpoint when a mobile app displays an\nin-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:

{\n  \"email\": \"user@example.com\",\n  \"userId\": \"user123\",\n  \"messageId\": \"9c438a20d26e4e9f8ad4edea23f811cd\"\n}\n
\n

\n# POST /api/events/track\n

Track an event
API Explorer: USDC-based projects,\nEDC-based projects

Saves custom events in Iterable (user logins, signups, app opens, etc.).

You can use these events in segmentation, to trigger journeys,\nand to track custom conversions.\nAdditionally, in a template, you can use the fields of a campaign-triggering\nevent 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\nparameters. If an event exists with that id, the event is updated. If no id\nis specified, a new id is automatically generated and returned.

An id value must:

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

Sample request body:

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

In this example, source is an unrecognized data field.

Sample response body:

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

\n# POST /api/events/trackWebPushClick\n

Track a web push click
API Explorer: USDC-based projects,\nEDC-based projects

Learn about identifying users in API requests.

\n# POST /api/events/trackPushOpen\n

Track a mobile push open
API Explorer: USDC-based projects,\nEDC-based projects

Tracks a mobile push notification open.

Include a campaignId to attribute the open to the Iterable campaign that\nsent the push notification.

Learn about identifying users in API requests.

Sample request body:

{\n  \"email\": \"user@example.com\",\n  \"userId\": \"2\",\n  \"campaignId\": 12345,\n  \"templateId\": 67890,\n  \"messageId\": \"9c438a20d26e4e9f8ad4edea23f811cd\",\n  \"dataFields\": {\n    \"openedMostRecentPush\": true\n  }\n}\n
\n

\n# GET /api/events/{email}\n

Get user events
API Explorer: USDC-based projects,\nEDC-based projects

Returns a user's events, including system events and custom events. The default\nvalue for limit is 30.

Learn about identifying users in API requests.

Sample:

GET https://api.iterable.com/api/events/user%40example.com\n
\n

Sample JSON response:

{\n  \"events\": [\n    {\n      \"contentId\": 330397,\n      \"recurringCampaignId\": 12345,\n      \"email\": \"user@example.com\",\n      \"createdAt\": \"2016-10-04 00:54:00 +00:00\",\n      \"campaignId\": 67890,\n      \"templateId\": 11111,\n      \"messageId\": \"6b92db5f79874561bc5b1dd1337f7a35\",\n      \"eventType\": \"emailSend\"\n    },\n    {\n      \"contentId\": 329261,\n      \"recurringCampaignId\": 12345,\n      \"email\": \"user@example.com\",\n      \"createdAt\": \"2016-09-30 19:50:00 +00:00\",\n      \"campaignId\": 67890,\n      \"templateId\": 22222,\n      \"messageId\": \"9c438a20d26e4e9f8ad4edea23f811cd\",\n      \"eventType\": \"emailSend\"\n    }\n  ]\n}\n
\n

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

Get user events by userId
API Explorer: USDC-based projects,\nEDC-based projects

Get events for a specific user, by userId.

Learn about identifying users in API requests.

\n# POST /api/events/trackBulk\n

Bulk track events
API Explorer: USDC-based projects,\nEDC-based projects

Tracks multiple custom events.

Events are created asynchronously and processed separately from the non-bulk\nevent tracking endpoint. Thus, if you need to make sure events are tracked in\norder, send all of them to the same endpoint (either bulk or non-bulk).

Learn about identifying users in API requests.

Important notes:

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

Sample request body:

{\n  \"events\": [\n    {\n      \"email\": \"user@example.com\",\n      \"eventName\": \"startedMembership\",\n      \"id\": \"12345\",\n      \"dataFields\": {\n        \"source\": \"facebook\",\n        \"membershipType\": \"monthly\"\n      },\n      \"userId\": \"1\",\n      \"campaignId\": 123,\n      \"templateId\": 123\n    },\n    {\n      \"email\": \"user@example.com\",\n      \"eventName\": \"quizCompleted\",\n      \"id\": \"45678\",\n      \"dataFields\": {\n        \"score\": 9\n      }\n    }\n  ]\n}\n
\n

\n# Experiments

\n# GET /api/experiments/metrics\n

Get metrics for experiments
API Explorer: USDC-based projects,\nEDC-based projects

Exports experiment metrics as CSV. This endpoint returns data only for email\nexperiments. You can:

Sample:

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

\n# Export

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

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

\n# GET /api/export/data.csv\n

Export data to CSV
API Explorer: USDC-based projects,\nEDC-based projects

Exports different types of data (purchases, user created, email sends, email\nopens, etc.) in CSV format. When the call is made, a string is returned as a\n.csv file. This file is then available for download.

\n# GET /api/export/data.json\n

Export data to JSON
API Explorer: USDC-based projects,\nEDC-based projects

Exports different types of data (purchases, user created, email sends, email\nopens, etc) in JSON format.

Sample response:

{\n  \"contentId\": 243307,\n  \"recurringCampaignId\": 41777,\n  \"email\": \"user@example.com\",\n  \"createdAt\": \"2016-07-08 19:50:00 +00:00\",\n  \"campaignId\": 43521,\n  \"templateId\": 71213\n}\n{\n  \"contentId\": 242909,\n  \"email\": \"user@example.com\",\n  \"createdAt\": \"2016-07-08 16:58:19 +00:00\",\n  \"campaignId\": 43444,\n  \"templateId\": 71115\n}\n{\n  \"contentId\": 243307,\n  \"recurringCampaignId\": 41777,\n  \"email\": \"user2@example.com\",\n  \"createdAt\": \"2016-07-08 19:50:00 +00:00\",\n  \"campaignId\": 43521,\n  \"templateId\": 71213\n}\n{\n  \"contentId\": 243307,\n  \"recurringCampaignId\": 41777,\n  \"email\": \"user3@example.com\",\n  \"createdAt\": \"2016-07-08 19:50:00 +00:00\",\n  \"campaignId\": 43521,\n  \"templateId\": 71213\n}\n
\n
\n

NOTE

The range field pulls information based off of the profile update field.

\n

\n# GET /api/export/userEvents\n

Export user events
API Explorer: USDC-based projects,\nEDC-based projects

{\n  \"name\": \"Jane Docs\",\n  \"email\": \"user@example.com\",\n  \"lastName\": \"Docs\",\n  \"firstName\": \"Jane\",\n  \"profileUpdatedAt\": \"2025-06-22 00:58:55 +00:00\",\n  \"itblInternal\": {\n    \"documentCreatedAt\": \"2025-06-22 00:58:55 +00:00\",\n    \"documentUpdatedAt\": \"2025-06-22 00:58:55 +00:00\"\n  },\n  \"createdAt\": \"2020-06-22 00:58:55 +00:00\",\n  \"signupSource\": \"Import\",\n  \"messageTypeIds\": [],\n  \"emailListIds\": [  // Note: This could be \"userListIds\" depending on project type\n    1111111\n  ],\n  \"channelIds\": [],\n  \"_type\": \"emailSubscribe\"\n}\n{\n  \"_id\": \"50bc32394fa14ef8dh24a17b5b6da768\",\n  \"eventName\": \"viewedItem\",\n  \"email\": \"user@example.com\",\n  \"viewedItem\": {\n    \"email\": \"user@example.com\"\n  },\n  \"createdAt\": \"2025-06-28 02:12:02 +00:00\",\n  \"eventUpdatedAt\": \"2025-06-28 02:12:02 +00:00\",\n  \"itblInternal\": {\n    \"documentCreatedAt\": \"2025-06-28 02:12:02 +00:00\",\n    \"documentUpdatedAt\": \"2025-06-28 02:12:02 +00:00\"\n  },\n  \"_type\": \"customEvent\"\n}\n
\n

\n# POST /api/export/start\n

Start export
API Explorer: USDC-based projects,\nEDC-based projects

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

Required parameters:

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

\n

IMPORTANT

The omitFields and onlyFields parameters are space-sensitive. Do not\ninclude spaces after commas in field names. Use \"email,locale,firstName\"\ninstead of \"email, locale, firstName\".

\n

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

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

Sample request body:

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

Sample response body:

{\n  \"jobId\": 99999\n}\n
\n

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

Get export files
API Explorer: USDC-based projects,\nEDC-based projects

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

Job states can be enqueued, running, completed, or failed. Occasionally,\na job status may change from running to enqueued because it had to restart.\nWhen this happens, the job maintains progress and begins where it previously\nstopped. Iterable uses an exponential backoff pattern for retries—when Iterable\nhas 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\nfiles by using the last file name in the response as the startAfter value for\nthe next request. Iterable returns up to 10 files per request.

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

Example:

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

Sample response body:

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

\n# DELETE /api/export/{jobId}\n

Cancel export
API Explorer: USDC-based projects,\nEDC-based projects

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

\n# GET /api/export/jobs\n

Get export jobs
API Explorer: USDC-based projects,\nEDC-based projects

Returns a list of recent export jobs for the current project. Only includes\njobs for the current project and not other projects.

Optional parameters:

Sample JSON response:

{\n  \"jobs\": [\n    {\n      \"id\": 3562,\n      \"dataTypeName\": \"user\",\n      \"jobState\": \"completed\",\n      \"scheduledStartTime\": \"2023-12-19T10:12:27.732-06:00\",\n      \"endTime\": \"2023-12-19T10:12:28.214-06:00\",\n      \"bytesExported\": 2453629\n    }\n  ]\n}\n
\n

\n# In-app messages

\n# GET /api/inApp/getPriorityMessage\n

Get a user's most relevant in-app message
API Explorer: USDC-based projects,\nEDC-based projects

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

Learn about identifying users in API requests.

\n# GET /api/inApp/getMessages\n

Get a user's in-app messages
API Explorer: USDC-based projects,\nEDC-based projects

Gets the in-app messages available for a specific user. This endpoint returns\nnew messages and messages that have already been saved to a user's mobile inbox.\nEach message has a read field that indicates whether or not it has already\nbeen seen.

If you'd like this API to return selective in-app messages for a specific\napp/platform combination (as well as non-selective in-app messages), include\npackageName and platform as query parameters in your request.

If you don't include both of these parameters, the API returns only\nnon-selective in-app messages (i.e., in-app messages sent with the selective\nin-app messaging feature disabled).

Sample request:

GET https://api.iterable.com/api/inApp/getMessages?email=user%40example.com&userId=1234&count=123\n
\n

Sample JSON response:

{\n  \"inAppMessages\": [\n    {\n      \"messageId\": \"9c438a20d26e4e9f8ad4edea23f811cd\",\n      \"campaignId\": 0,\n      \"createdAt\": \"2022-11-10T16:58:14.933Z\",\n      \"expiresAt\": \"2022-11-10T16:58:14.933Z\",\n      \"content\": {\n        \"html\": \"string\",\n        \"inAppDisplaySettings\": {\n          \"top\": {},\n          \"right\": {},\n          \"bottom\": {},\n          \"left\": {},\n          \"bgColor\": {\n            \"alpha\": 0,\n            \"hex\": \"string\"\n          },\n          \"shouldAnimate\": true\n        },\n        \"webInAppDisplaySettings\": {\n          \"position\": {}\n        }\n      },\n      \"customPayload\": {},\n      \"trigger\": {\n        \"type\": {}\n      },\n      \"saveToInbox\": true,\n      \"inboxMetadata\": {\n        \"title\": \"string\",\n        \"subtitle\": \"string\",\n        \"icon\": \"string\"\n      },\n      \"priorityLevel\": 0,\n      \"read\": true,\n      \"jsonOnly\": true,\n      \"typeOfContent\": {},\n      \"messageType\": {}\n    }\n  ]\n}\n
\n

priorityLevel indicates an in-app messages's display priority:

By default, Iterable's mobile SDKs display greater priority messages first\n(proof, then critical, then high, then medium, then low), sorting the messages\nin each individual priority level by send time (first sent, first displayed).

\n# POST /api/inApp/cancel\n

Cancel a scheduled in-app message
API Explorer: USDC-based projects,\nEDC-based projects

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

Sample JSON body:

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

Learn about identifying users in API requests.

\n# POST /api/inApp/target\n

Send an in-app notification to a user
API Explorer: USDC-based projects,\nEDC-based projects

Sends an existing in-app message campaign to a specific user. Use sendAt to\nschedule a future send and dataFields to override user profile fields.

Sample JSON body:

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

Learn about identifying users in API requests.

\n# Web in-app messages

\n# GET /api/inApp/web/getMessages\n

Get a user's web in-app messages
API Explorer: USDC-based projects,\nEDC-based projects

This endpoint is functionally the same as GET /api/inApp/getMessages,\nbut with platform always set to Web (cannot be changed).

This endpoint is used by Iterable's web SDK\nto fetch in-browser messages\n(in-app messages that target a website).

\n# Journeys (workflows)

\n# GET /api/journeys\n

Get all journeys in the project
API Explorer: USDC-based projects,\nEDC-based projects

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

Sample request:

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

Sample response body:

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

\n# POST /api/workflows/triggerWorkflow\n

Trigger a workflow
API Explorer: USDC-based projects,\nEDC-based projects

Triggers a journey for a single user and/or all users on a list. Works for both\nstatic and dynamic lists.

Learn about identifying users in API requests.

Sample request body (JSON):

{\n  \"email\": \"user@example.com\",\n  \"workflowId\": 2765,\n  \"listId\": 6094,\n  \"dataFields\": {\n    \"signupSource\": \"google\",\n    \"optIn\": true\n  }\n}\n
\n

\n# Lists

\n# DELETE /api/lists/{listId}\n

Delete a list
API Explorer: USDC-based projects,\nEDC-based projects

Deletes a list. All users who are part of the deleted list have the list removed\nfrom their profile.

The list must not be in use. Attempting to delete a list in use will cause the\nrequest to fail with a 409 Conflict response code and a message indicating\nwhere the list is active.

Sample request:

https://api.iterable.com/api/lists/21398\n
\n

\n# GET /api/lists\n

Get lists
API Explorer: USDC-based projects,\nEDC-based projects

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

Sample:

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

Sample response body:

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

\n# POST /api/lists\n

Create a static list
API Explorer: USDC-based projects,\nEDC-based projects

Creates a new, empty, static list, with the specified name. Returns the list\nID.

Sample request body:

{\n  \"name\": \"September subscribers\",\n  \"description\": \"Users who subscribed in September 2022.\"\n}\n
\n

\n# POST /api/lists/subscribe\n

Add subscribers to list
API Explorer: USDC-based projects,\nEDC-based projects

Adds a subscriber to an existing static list.

Learn about identifying users in API requests.

Sample request body:

{\n  \"listId\": 123,\n  \"subscribers\": [\n    {\n      \"email\": \"user@example.com\",\n      \"dataFields\": {\n        \"firstName\": \"Sherry\",\n        \"hasCat\": true\n      },\n      \"userId\": \"1\"\n    }\n  ]\n}\n
\n

\n# POST /api/lists/unsubscribe\n

Remove users from a list
API Explorer: USDC-based projects,\nEDC-based projects

Removes one or more subscribers from an existing static list.

Learn about identifying users in API requests.

Sample request body:

{\n  \"listId\": 1,\n  \"subscribers\": [\n    {\n      \"email\": \"user@example.com\"\n    },\n    {\n      \"email\": \"user2@example.com\"\n    }\n  ],\n  \"campaignId\": 123,\n  \"channelUnsubscribe\": false\n}\n
\n

\n# GET /api/lists/getUsers\n

Get users in a list
API Explorer: USDC-based projects,\nEDC-based projects

Returns a string of all the users who are on a list. Works for both static and\ndynamic lists

Sample:

GET https://api.iterable.com/api/lists/getUsers?listId=21401\n
\n

\n# GET /api/lists/previewUsers\n

Preview users in a list
API Explorer: USDC-based projects,\nEDC-based projects

Returns a random sample of users from a static or dynamic list.

Accepted path parameters:

Sample request:

GET https://api.iterable.com/api/lists/previewUsers?listId=12345&size=5\n
\n

Sample response (text/plain):

user1@example.com\nuser2@example.com\nuser3@example.com\nuser4@example.com\nuser5@example.com\n
\n

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

Get count of users in list
API Explorer: USDC-based projects,\nEDC-based projects

Get the number of users within a list.

\n# Message types

\n# GET /api/messageTypes\n

List message types
API Explorer: USDC-based projects,\nEDC-based projects

Lists all message types in the project.

Sample JSON response:

{\n  \"messageTypes\": [\n    {\n      \"id\": 3868,\n      \"name\": \"Push Marketing Message\",\n      \"channelId\": 3422\n    },\n    {\n      \"id\": 3867,\n      \"name\": \"Transactional Message\",\n      \"channelId\": 3421\n    },\n    {\n      \"id\": 3866,\n      \"name\": \"Marketing Message\",\n      \"channelId\": 3420\n    }\n  ]\n}\n
\n

\n# Metadata store

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

Delete a single metadata key/value
API Explorer: USDC-based projects,\nEDC-based projects

Deletes the specified item from the table.

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

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

Get the metadata value of a single key
API Explorer: USDC-based projects,\nEDC-based projects

Get the metadata value of a single key.

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

Create or replace metadata
API Explorer: USDC-based projects,\nEDC-based projects

Creates or replaces the item associated with the specified key.

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

\n# DELETE /api/metadata/{table}\n

Delete a table
API Explorer: USDC-based projects,\nEDC-based projects

Deletes a specified table.

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

\n# GET /api/metadata/{table}\n

List keys in a table
API Explorer: USDC-based projects,\nEDC-based projects

List keys in a given table.

\n# GET /api/metadata\n

List available tables
API Explorer: USDC-based projects,\nEDC-based projects

List available tables.

\n# Push notifications

\n# POST /api/push/cancel\n

Cancel a push notification to a user
API Explorer: USDC-based projects,\nEDC-based projects

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

Learn about identifying users in API requests.

\n# POST /api/push/target\n

Send push notification to user
API Explorer: USDC-based projects,\nEDC-based projects

Sends a triggered push notification to a specific user.

Request data fields override existing user profile data fields. Campaign must be\nset up in Iterable beforehand. If sendAt field is not included, the message is\nsent immediately.

Learn about identifying users in API requests.

Sample request body:

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

\n# RCS

\n# POST /api/rcs/target\n

Send an RCS message to a user
API Explorer: USDC-based projects,\nEDC-based projects

Sends an RCS campaign to a specified user. Data fields included in the API\nrequest body take precedence over data fields on the user's profile. Campaign\nmust be set up in Iterable prior to sending the API request. If the sendAt\nfield is not included, the message is sent immediately.

Sample request body:

{\n  \"campaignId\": 1234567,\n  \"recipientEmail\": \"user@example.com\",\n  \"dataFields\": {},\n  \"sendAt\": \"2026-10-15 17:00:00\",\n  \"allowRepeatMarketingSends\": true\n}\n
\n

Include a recipientUserId or recipientEmail, but not both. Learn more about\nidentifying users in API requests.

sendAt uses YYYY-MM-DD HH:MM:SS in UTC. allowRepeatMarketingSends defaults\nto true.

On success, this endpoint returns status code 200 and creates an rcsSend\nevent on the specified user's Iterable profile.

\n# POST /api/rcs/cancel\n

Cancel a scheduled RCS message
API Explorer: USDC-based projects,\nEDC-based projects

Cancels a scheduled RCS message for a specified user. Request must include a\ncampaignId and an email or userId, or just a scheduledMessageId.

Sample request body:

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

Learn about identifying users in API requests.

On success, this endpoint returns status code 200, and the campaign is not sent\nto the specified user.

\n# SMS

\n# POST /api/sms/cancel\n

Cancel an SMS to a user
API Explorer: USDC-based projects,\nEDC-based projects

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

Sample request body:

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

Learn about identifying users in API requests.

\n# POST /api/sms/target\n

Send SMS notification to user
API Explorer: USDC-based projects,\nEDC-based projects

Sends an SMS to a specific user. Request data fields override existing user\nprofile data fields. Campaign must be set up in Iterable beforehand. If sendAt\nfield is not included, the message is sent immediately.

Learn about identifying users in API requests.

Sample request body:

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

\n# Snippets

Iterable's Snippets API allows you to create, retrieve, update, and delete\nsnippets.

To learn more about snippets and how they work as reusable content, see\nSnippets Overview.

Here are some things to know when working with the Snippets API:

\n# Identifying snippets

Iterable identifies snippets by either their name or id. For endpoints that\naccept an identifier path parameter, you can use either the name or id\nvalue.

When you create a snippet, provide a unique name (string). Iterable assigns\nan id (numeric) for the snippet upon creation.

\n# Snippet content

When a snippet is referenced in a template, the content is what displays to\nthe user when Iterable renders the campaign. The content parameter is a\nstring that can include HTML, CSS (inline styles), Handlebars expressions, and\ndata feed references. Handlebars expressions must be valid, and a snippet can't\nreference itself.

\n# Variables in content

\n

Iterable supports Handlebars expressions in snippet content. Sometimes these\nexpressions are referred to as merge tags, and they often reference user\nprofile fields, event fields, or other kinds of variables that provide dynamic\ncontent.

You can use the variables array to list variable names used in your snippet’s\ncontent. These variables allow you to create dynamic, customizable content by\nreferencing them as Handlebars expressions within the snippet (for example,\n{{variableName}}). Then, when you add the snippet to a template, you can\nspecify values for each variable, making the snippet’s output flexible and\ndelivering custom content in each template.

Variable names are case-sensitive and should be simple identifiers (letters,\nnumbers, underscores). They can be unique to the snippet, or they can be any\nfield name that you can reference in a template.

To learn more, read Customizing Snippets with Variables.

\n
\n

\n# GET /api/snippets\n

Get all snippets
API Explorer: USDC-based projects,\nEDC-based projects

Retrieves all snippets for the project, including all fields for each snippet.

Sample request:

GET https://api.iterable.com/api/snippets\n
\n

Sample JSON response:

{\n  \"snippets\": [\n    {\n      \"id\": 12345,\n      \"name\": \"Copyright_year\",\n      \"content\": \"© 2025 Fiterable, Inc.\",\n      \"description\": \"Copyright year snippet\",\n      \"createdAt\": \"2025-01-01T10:00:00Z\",\n      \"updatedAt\": \"2025-01-15T14:30:00Z\",\n      \"createdBy\": \"user@example.com\",\n      \"updatedBy\": \"user2@example.com\",\n      \"projectId\": 789\n    },\n    {\n      \"id\": 12346,\n      \"name\": \"Welcome_Banner\",\n      \"content\": \"<div style='background-color: {{bannerColor}};'>Welcome {{firstName}}!</div>\",\n      \"description\": \"Welcome banner with customizable color\",\n      \"variables\": [\"bannerColor\", \"firstName\"],\n      \"createdAt\": \"2025-01-01T10:00:00Z\",\n      \"updatedAt\": \"2025-01-15T14:30:00Z\",\n      \"createdBy\": \"user1@example.com\",\n      \"updatedBy\": \"user2@example.com\",\n      \"projectId\": 789\n    },\n    ...\n  ]\n}\n
\n

\n# POST /api/snippets\n

Create a snippet
API Explorer: USDC-based projects,\nEDC-based projects

Creates a new snippet in the project.

Sample request body:

{\n  \"name\": \"Welcome_Banner\",\n  \"content\": \"<div style='background-color: {{bannerColor}};'>Welcome {{firstName}}!</div>\",\n  \"createdByUserId\": \"user@example.com\",\n  \"description\": \"Welcome banner with customizable color\",\n  \"variables\": [\"bannerColor\", \"firstName\"]\n}\n
\n

Sample JSON response:

{\n  \"snippetId\": 12346\n}\n
\n

\n# GET /api/snippets/{identifier}\n

Get snippet by ID or name
API Explorer: USDC-based projects,\nEDC-based projects

Retrieves a specific snippet by its id or name.

Sample requests:

GET https://api.iterable.com/api/snippets/12345\n
\n
GET https://api.iterable.com/api/snippets/Welcome_Banner\n
\n

Sample JSON response:

{\n  \"snippet\": {\n    \"id\": 12345,\n    \"name\": \"Welcome_Banner\",\n    \"content\": \"<div style='background-color: {{bannerColor}};'>Welcome {{firstName}}!</div>\",\n    \"description\": \"Welcome banner with customizable color\",\n    \"variables\": [\"bannerColor\", \"firstName\"],\n    \"createdAt\": \"2025-01-01T10:00:00Z\",\n    \"updatedAt\": \"2025-01-15T14:30:00Z\",\n    \"createdBy\": \"user1@example.com\",\n    \"updatedBy\": \"user2@example.com\",\n    \"projectId\": 789\n  }\n}\n
\n

\n# PUT /api/snippets/{identifier}\n

Create or update a snippet
API Explorer: USDC-based projects,\nEDC-based projects

Updates a snippet if it already exists, or creates a new one if it doesn't.

A successful update returns a 200 status code. If a new snippet is created,\nIterable returns a 201 status code.

\n

IMPORTANT

Note that the name field cannot be changed after creation, so this endpoint\ndoes not support updating the name field in the request body.

\n

Sample request body:

{\n  \"content\": \"<div style='background-color: {{bannerColor}};'>Welcome {{capitalize firstName}}!</div>\",\n  \"description\": \"Updated welcome banner with customizable color\",\n  \"variables\": [\"bannerColor\", \"firstName\"]\n}\n
\n

Sample JSON response:

{\n  \"snippetId\": 12346\n}\n
\n

\n# DELETE /api/snippets/{identifier}\n

Delete a snippet
API Explorer: USDC-based projects,\nEDC-based projects

Deletes a snippet by its numeric ID or string name.

\n

IMPORTANT

Before deleting a snippet, check that it isn't used in any active templates.\nTo learn how to check, read See Where Snippets Are Used.

\n

Sample requests:

DELETE https://api.iterable.com/api/snippets/12345\n
\n
DELETE https://api.iterable.com/api/snippets/Welcome_Banner\n
\n

Sample JSON response:

{\n  \"snippetId\": 12345\n}\n
\n

\n# Subscriptions

The following APIs manage user subscriptions to message channels, message types,\nand email lists.

\n

NOTE

Iterable's Subscriptions API and opt-in message types are enabled by default\nfor all organizations created after September 2019.

Because of a breaking API change, organizations created before September 2019\ndon't have Iterable's Subscriptions API or opt-in message types enabled by\ndefault. If your organization was created before this date, your customer\nsuccess manager must enable this feature.

To learn more about the impact of this update, read Breaking API Change.

\n

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

Unsubscribe a single user
API Explorer: USDC-based projects,\nEDC-based projects

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

Subscribe a single user
API Explorer: USDC-based projects,\nEDC-based projects

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

Unsubscribe a single user by userId
API Explorer: USDC-based projects,\nEDC-based projects

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

Subscribe a single user by their userId
API Explorer: USDC-based projects,\nEDC-based projects

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

Bulk subscription action on a list of users
API Explorer: USDC-based projects,\nEDC-based projects

\n# POST /api/subscriptions/subscribeToDoubleOptIn\n

Trigger a double opt-in subscription flow
API Explorer: USDC-based projects,\nEDC-based projects

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

Once the user responds to the subscription confirmation message, Iterable\nsubscribes 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\nchannel. To learn more about double opt-in message types and how to use this\nAPI, read SMS Double Opt-In.

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

Request body:

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

Sample response:

Request for double opt-in subscription accepted\n
\n

\n# Templates

\n

IMPORTANT

Iterable's template APIs allow you to read and update all templates. They are\nnot restricted to base templates (unless otherwise specified) — you can use\nthem to read and update templates associated with blast campaigns, triggered\ncampaigns, and journey campaigns, changing their content for future sends.

\n

\n# GET /api/templates\n

Get project templates
API Explorer: USDC-based projects,\nEDC-based projects

Gets info for the templates in a project. Includes the templateId, creation\nand modification times, the name of the template, the creator of the template\nand the message type used.

\n

NOTE

If you leave templateType blank, the endpoint returns base templates only.

\n

Sample:

GET https://api.iterable.com/api/templates?templateType=Base&messageMedium=Email\n
\n

Sample JSON response:

{\n  \"templates\": [\n    {\n      \"templateId\": 86596,\n      \"createdAt\": 1473368899828,\n      \"updatedAt\": 1473370111852,\n      \"name\": \"Regular editor\",\n      \"creatorUserId\": \"user@example.com\",\n      \"messageTypeId\": 3867\n    },\n    {\n      \"templateId\": 68178,\n      \"createdAt\": 1466810056349,\n      \"updatedAt\": 1470431713441,\n      \"name\": \"Photography Welcome Message\",\n      \"creatorUserId\": \"user@example.com\",\n      \"messageTypeId\": 3866\n    }\n  ]\n}\n
\n

\n# GET /api/templates/getByClientTemplateId\n

Get an email template by clientTemplateId
API Explorer: USDC-based projects,\nEDC-based projects

Gets an array of template ids that match a client template id. If the client has\nset a clientTemplateId on any email template(s), then this call return those\ntemplates.

\n# GET /api/templates/email/get\n

Get an email template by templateId
API Explorer: USDC-based projects,\nEDC-based projects

Returns HTML and metadata for a specific email template.

Sample JSON response:

{\n  \"templateId\": 86596,\n  \"name\": \"My name of template\",\n  \"fromName\": \"Customer Success\",\n  \"fromEmail\": \"user@example.com\",\n  \"replyToEmail\": \"replyTo@example.com\",\n  \"subject\": \"My Subject of message\",\n  \"preheaderText\": \"preheader message here\",\n  \"ccEmails\": [],\n  \"bccEmails\": [],\n  \"html\": \"<html>\\n\\n<head>\\n<title></title>\\n</head>\\n\\n<body>\\n <p>\\n {{userPropertyParameter}}\\n </p>\\n</body>\\n\\n</html>\",\n  \"plainText\": \"Optional plain text message\",\n  \"cacheDataFeed\": false,\n  \"mergeDataFeedContext\": true,\n  \"messageTypeId\": 3867,\n  \"creatorUserId\": \"user@example.com\"\n}\n
\n

\n# POST /api/templates/email/upsert\n

Create email template
API Explorer: USDC-based projects,\nEDC-based projects

Creates a new email template if one does not exist, or updates all templates\nwith the specified client template id.

Sample request body:

{\n  \"clientTemplateId\": 112233,\n  \"name\": \"Lots of Cats\",\n  \"fromName\": \"Felicia the Cat\",\n  \"fromEmail\": \"user@example.com\",\n  \"replyToEmail\": \"replyTo@example.com\",\n  \"subject\": \"Rank These Cats\",\n  \"preheaderText\": \"10 out of 10!\",\n  \"html\": \"<html><body><p>So many cats!</p></body></html>\"\n}\n
\n

\n# POST /api/templates/email/update\n

Update email template
API Explorer: USDC-based projects,\nEDC-based projects

Updates a specific email template. Only fields specified are updated.

Sample request body:

{\n  \"templateId\": 53081,\n  \"name\": \"Lots of Cats\",\n  \"fromName\": \"Felicia the Cat\",\n  \"fromEmail\": \"replyto@example.com\",\n  \"replyToEmail\": \"replyto@example.com\",\n  \"subject\": \"Rank These Cats\",\n  \"preheaderText\": \"10 out of 10!\",\n  \"html\": \"<html><body><p>So many cats!</p></body></html>\"\n }\n
\n
\n

NOTE

This call does not work on templates made with the Drag and Drop Editor.

\n

\n# POST /api/templates/email/proof\n

Send email template proof
API Explorer: USDC-based projects,\nEDC-based projects

Send a proof of an email template to a specific user for testing and preview\npurposes.

Sample request body:

{\n  \"templateId\": 53081,\n  \"recipientEmail\": \"test@example.com\",\n  \"dataFields\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\"\n  }\n}\n
\n

Sample JSON response:

{\n  \"success\": true,\n  \"messageId\": \"12345\"\n}\n
\n

\n# POST /api/templates/email/preview\n

Preview email template with custom data
API Explorer: USDC-based projects,\nEDC-based projects

Generate an HTML preview of an email template that renders with custom data.\nThis endpoint simulates how a template would appear when sent to a user,\nallowing you to test template rendering with specific user, event, and/or data\nfeed data.

\n

NOTE

Some content elements are processed during send time that change HTML of the\nmessage body, such as rewritten links, a tracking pixel, and an\nauto-appended unsubscribe block\n(if enabled).

This endpoint previews the HTML of the template with the custom data rendered,\nbut does not reflect the final HTML of the message that a user receives.

\n

Sample request body:

{\n  \"dataFields\": {\n    \"firstName\": \"Sarah\",\n    \"lastName\": \"Johnson\",\n    \"email\": \"sarah.johnson@example.com\",\n    \"eventName\": \"purchase\",\n    \"totalValue\": 149.99,\n    \"productName\": \"Premium Wireless Headphones\"\n  },\n  \"dataFeed\": {\n    \"companyName\": \"Example Corp\",\n    \"supportEmail\": \"support@example.net\"\n  },\n  \"fetchDataFeeds\": false\n}\n
\n

Sample response:

<!DOCTYPE html> <html> <head> <meta charset=\"UTF-8\"> <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\"> <title>Welcome Sarah</title> </head> <body style=\"font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px; background-color: #f5f5f5;\"> <div style=\"background-color: white; padding: 20px; border-radius: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.1);\"> <div style=\"background-color: #4a90e2; color: white; padding: 20px; border-radius: 5px; margin-bottom: 20px;\"> <h1 style=\"margin: 0; font-size: 24px;\">Welcome Sarah!</h1> </div> <div style=\"background-color: #f8f9fa; padding: 15px; border-left: 4px solid #4a90e2; margin: 15px 0;\"> <h2 style=\"margin-top: 0; color: #333;\">Your Account</h2> <p style=\"margin: 5px 0;\"><strong>Email:</strong> sarah.johnson@example.com</p> <p style=\"margin: 5px 0;\"><strong>Name:</strong> Sarah Johnson</p> </div> <div style=\"background-color: #e8f5e8; padding: 15px; border-left: 4px solid #28a745; margin: 15px 0;\"> <h2 style=\"margin-top: 0; color: #333;\">Recent Activity</h2> <p style=\"margin: 5px 0;\"><strong>Event:</strong> purchase</p> <p style=\"margin: 5px 0;\"><strong>Amount:</strong> $149.99</p> <p style=\"margin: 5px 0;\"><strong>Product:</strong> Premium Wireless Headphones</p> </div> <div style=\"margin-top: 20px; padding: 15px; background-color: #f8f9fa; border-radius: 5px;\"> <p>Hello Sarah,</p> <p>Thank you for your purchase! We hope you enjoy your Premium Wireless Headphones.</p> <p>Best regards,<br>The Example Corp Team</p> <p style=\"font-size: 12px; color: #666;\">Questions? Contact us at <a href=\"mailto:support@example.net\" style=\"color: #4a90e2;\">support@example.net</a></p> </div> </div> <div><a href=\"https://www.example.net\" rel=\"noopener\" target=\"_blank\">Link</a></div> <div></div> <div><img height=\"220\" src=\"https://library.iterable.com/0000/00000/09c730f1d8d94c39a015211ab936af88-b7.png\" width=\"220\"></div> <div></div> </body> </html>\n
\n

\n# GET /api/templates/embedded/get\n

Get an embedded message template
API Explorer: USDC-based projects,\nEDC-based projects

Returns content and metadata for a specific embedded message template.

Sample JSON response:

{\n  \"templateId\": 12345,\n  \"name\": \"Welcome Embedded Message\",\n  \"title\": \"Welcome to Our App!\",\n  \"body\": \"Thanks for joining us. We're excited to have you on board.\",\n  \"elements\": {\n    \"text\": [\n      {\n        \"label\": \"greeting\",\n        \"text\": \"Hello {{firstName}}!\"\n      },\n      {\n        \"label\": \"description\",\n        \"text\": \"You've been a member since {{joinDate}}.\"\n      }\n    ],\n    \"buttons\": [\n      {\n        \"id\": \"btn_get_started\",\n        \"title\": \"Get Started\",\n        \"action\": {\n          \"type\": \"openUrl\",\n          \"data\": \"https://example.com/get-started\"\n        }\n      },\n      {\n        \"id\": \"btn_learn_more\",\n        \"title\": \"Learn More\",\n        \"action\": {\n          \"type\": \"openUrl\",\n          \"data\": \"https://example.com/learn-more\"\n        }\n      }\n    ],\n    \"mediaUrl\": \"https://example.com/images/welcome-banner.jpg\",\n    \"mediaUrlCaption\": \"Welcome banner image\",\n    \"defaultAction\": {\n      \"type\": \"openUrl\",\n      \"data\": \"https://example.com/default-action\"\n    }\n  },\n  \"payload\": {\n    \"customData\": \"value\",\n    \"deepLink\": \"myapp://welcome\"\n  },\n  \"placementId\": \"home_screen\",\n  \"clientTemplateId\": \"embedded_welcome_001\",\n  \"messageTypeId\": 5001,\n  \"locale\": \"en\",\n  \"isDefaultLocale\": true,\n  \"campaignId\": 7890,\n  \"campaignDataFields\": {\n    \"promoCode\": \"WELCOME2026\",\n    \"discountPercent\": 10\n  }\n}\n
\n

\n# POST /api/templates/embedded/upsert\n

Create an embedded message template
API Explorer: USDC-based projects,\nEDC-based projects

Create an embedded message template if it doesn't exist yet, otherwise updates\nthe embedded message template that matches the name provided.

Sample request body:

{\n  \"clientTemplateId\": \"embedded_welcome_001\",\n  \"name\": \"Welcome Embedded Message\",\n  \"title\": \"Welcome to Our App!\",\n  \"body\": \"Thanks for joining us. We're excited to have you on board.\",\n  \"elements\": {\n    \"text\": [\n      {\n        \"label\": \"greeting\",\n        \"text\": \"Hello {{firstName}}!\"\n      },\n      {\n        \"label\": \"description\",\n        \"text\": \"You've been a member since {{joinDate}}.\"\n      }\n    ],\n    \"buttons\": [\n      {\n        \"id\": \"btn_get_started\",\n        \"title\": \"Get Started\",\n        \"action\": {\n          \"type\": \"openUrl\",\n          \"data\": \"https://example.com/get-started\"\n        }\n      },\n      {\n        \"id\": \"btn_learn_more\",\n        \"title\": \"Learn More\",\n        \"action\": {\n          \"type\": \"openUrl\",\n          \"data\": \"https://example.com/learn-more\"\n        }\n      }\n    ],\n    \"mediaUrl\": \"https://example.com/images/welcome-banner.jpg\",\n    \"mediaUrlCaption\": \"Welcome banner image\",\n    \"defaultAction\": {\n      \"type\": \"openUrl\",\n      \"data\": \"https://example.com/default-action\"\n    }\n  },\n  \"payload\": {\n    \"customData\": \"value\",\n    \"deepLink\": \"myapp://welcome\"\n  },\n  \"placementId\": \"home_screen\",\n  \"messageTypeId\": 5001,\n  \"locale\": \"en\",\n  \"isDefaultLocale\": true,\n  \"creatorUserId\": \"marketing-team@example.com\"\n}\n
\n

\n# POST /api/templates/embedded/update\n

Update embedded message template
API Explorer: USDC-based projects,\nEDC-based projects

Updates a specific embedded message template. Only updates the field(s) included\nin the request body.

Sample request body:

{\n  \"templateId\": 12345,\n  \"name\": \"Welcome Embedded Message Updated\",\n  \"title\": \"Welcome to Our App - Updated!\",\n  \"body\": \"Thanks for joining us. We're excited to have you on board. Check out our new features!\",\n  \"elements\": {\n    \"text\": [\n      {\n        \"label\": \"greeting\",\n        \"text\": \"Hello {{firstName}}! Welcome back.\"\n      },\n      {\n        \"label\": \"description\",\n        \"text\": \"You've been a member since {{joinDate}}. Thanks for being part of our community.\"\n      }\n    ],\n    \"buttons\": [\n      {\n        \"id\": \"btn_get_started\",\n        \"title\": \"Get Started\",\n        \"action\": {\n          \"type\": \"openUrl\",\n          \"data\": \"https://example.com/get-started\"\n        }\n      }\n    ],\n    \"mediaUrl\": \"https://example.com/images/welcome-banner-v2.jpg\",\n    \"mediaUrlCaption\": \"Welcome banner image\",\n    \"defaultAction\": {\n        \"type\": \"openUrl\",\n        \"data\": \"https://example.com/default-action\"\n      }\n  },\n  \"payload\": {\n    \"customData\": \"updated_value\",\n    \"deepLink\": \"myapp://welcome\",\n    \"version\": \"2.0\"\n  }\n}\n
\n

\n# GET /api/templates/push/get\n

Get a push template
API Explorer: USDC-based projects,\nEDC-based projects

Returns content and metadata for a specific push notification template.

Sample JSON response:

{\n  \"templateId\": 0,\n  \"createdAt\": \"2022-09-29T17:23:42.748Z\",\n  \"updatedAt\": \"2022-09-29T17:23:42.748Z\",\n  \"name\": \"string\",\n  \"title\": \"string\",\n  \"message\": \"string\",\n  \"payload\": {},\n  \"badge\": \"string\",\n  \"wake\": true,\n  \"relevanceScore\": 0,\n  \"interruptionLevel\": \"passive\",\n  \"locale\": \"string\",\n  \"messageTypeId\": 0,\n  \"sound\": \"string\",\n  \"buttons\": [\n    {\n      \"identifier\": \"string\",\n      \"title\": \"string\",\n      \"buttonType\": \"default\",\n      \"action\": {\n        \"type\": \"string\",\n        \"data\": \"string\"\n      },\n      \"openApp\": true,\n      \"requiresUnlock\": true,\n      \"inputPlaceholder\": \"string\",\n      \"inputTitle\": \"string\",\n      \"actionIcon\": {\n        \"iconType\": {},\n        \"imageName\": \"string\"\n      }\n    }\n  ],\n  \"deeplink\": {\n    \"ios\": \"string\",\n    \"android\": \"string\"\n  },\n  \"richMedia\": {\n    \"ios\": \"string\",\n    \"android\": \"string\"\n  },\n  \"dataFeedIds\": [\n    0\n  ],\n  \"cacheDataFeed\": true,\n  \"mergeDataFeedContext\": true,\n  \"clientTemplateId\": \"string\",\n  \"campaignId\": {},\n  \"isSilentPush\": true\n}\n
\n

\n# POST /api/templates/push/upsert\n

Create a push template
API Explorer: USDC-based projects,\nEDC-based projects

Creates a new template if one does not exist, or updates all templates with the\nspecified name.

Sample request body:

{\n  \"clientTemplateId\": \"string\",\n  \"name\": \"string\",\n  \"title\": \"string\",\n  \"message\": \"string\",\n  \"payload\": {\n    \"underlying\": {},\n    \"fields\": [\n      {\n        \"_1\": \"string\",\n        \"_2\": {}\n      }\n    ],\n    \"value\": {}\n  },\n  \"badge\": \"string\",\n  \"wake\": true,\n  \"relevanceScore\": 0,\n  \"interruptionLevel\": \"passive\",\n  \"locale\": \"string\",\n  \"messageTypeId\": 0,\n  \"sound\": \"string\",\n  \"buttons\": [\n    {\n      \"identifier\": \"string\",\n      \"title\": \"string\",\n      \"buttonType\": \"default\",\n      \"action\": {\n        \"type\": \"string\",\n        \"data\": \"string\"\n      },\n      \"openApp\": true,\n      \"requiresUnlock\": true,\n      \"inputPlaceholder\": \"string\",\n      \"inputTitle\": \"string\",\n      \"actionIcon\": {\n        \"iconType\": {},\n        \"imageName\": \"string\"\n      }\n    }\n  ],\n  \"deeplink\": {\n    \"ios\": \"string\",\n    \"android\": \"string\"\n  },\n  \"richMedia\": {\n    \"ios\": \"string\",\n    \"android\": \"string\"\n  },\n  \"dataFeedIds\": [\n    0\n  ],\n  \"cacheDataFeed\": true,\n  \"mergeDataFeedContext\": true,\n  \"creatorUserId\": \"string\",\n  \"isSilentPush\": true,\n  \"messageMedium\": {}\n}\n
\n

\n# POST /api/templates/push/update\n

Update push template
API Explorer: USDC-based projects,\nEDC-based projects

Updates a specific push template. Most fields are optional. Include the fields\nyou wish to update.

Sample request body:

{\n  \"templateId\": 0,\n  \"createdAt\": \"2022-09-29T17:23:42.683Z\",\n  \"updatedAt\": \"2022-09-29T17:23:42.683Z\",\n  \"name\": \"string\",\n  \"title\": \"string\",\n  \"message\": \"string\",\n  \"payload\": {},\n  \"badge\": \"string\",\n  \"wake\": true,\n  \"relevanceScore\": 0,\n  \"interruptionLevel\": \"passive\",\n  \"locale\": \"string\",\n  \"messageTypeId\": 0,\n  \"sound\": \"string\",\n  \"buttons\": [\n    {\n      \"identifier\": \"string\",\n      \"title\": \"string\",\n      \"buttonType\": \"default\",\n      \"action\": {\n        \"type\": \"string\",\n        \"data\": \"string\"\n      },\n      \"openApp\": true,\n      \"requiresUnlock\": true,\n      \"inputPlaceholder\": \"string\",\n      \"inputTitle\": \"string\",\n      \"actionIcon\": {\n        \"iconType\": {},\n        \"imageName\": \"string\"\n      }\n    }\n  ],\n  \"deeplink\": {\n    \"ios\": \"string\",\n    \"android\": \"string\"\n  },\n  \"richMedia\": {\n    \"ios\": \"string\",\n    \"android\": \"string\"\n  },\n  \"dataFeedIds\": [\n    0\n  ],\n  \"cacheDataFeed\": true,\n  \"mergeDataFeedContext\": true,\n  \"clientTemplateId\": \"string\",\n  \"campaignId\": {},\n  \"isSilentPush\": true\n}\n
\n

To indicate that a template should send as a silent push notification, rather\nthan a standard push notification, set isSilentPush to true.

Silent push notifications don't visibly appear to your user. Instead, they pass\nJSON data to your app (the payload), which can use this data as needed — to\nkick off a download, to tell the app to display an app store review prompt, etc.\nOn iOS, you can also use a silent push to set the badge field, which updates\nthe badge on your app's icon.

\n# POST /api/templates/push/proof\n

Send push template proof
API Explorer: USDC-based projects,\nEDC-based projects

Send a proof of a push template to a specific user for testing and preview\npurposes.

Sample request body:

{\n  \"templateId\": 53081,\n  \"recipientEmail\": \"test@example.com\",\n  \"dataFields\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\"\n  }\n}\n
\n

Sample JSON response:

{\n  \"success\": true,\n  \"messageId\": \"12345\"\n}\n
\n

\n# POST /api/templates/sms/upsert\n

Create an SMS template
API Explorer: USDC-based projects,\nEDC-based projects

Creates a new template if one does not exist or updates all templates with the\nspecified client template id.

Sample request body:

{\n  \"clientTemplateId\": 112233,\n  \"name\": \"SMS Test\",\n  \"message\": \"Hello There!\",\n  \"locale\": \"en\",\n  \"messageTypeId\": \"1234\"\n} \n
\n

\n# POST /api/templates/sms/update\n

Update SMS template
API Explorer: USDC-based projects,\nEDC-based projects

Updates a specific SMS template. Most fields are optional. Include the fields\nyou wish to update.

Sample request body:

{\n  \"templateId\": 123,\n  \"name\": \"My SMS Title\",\n  \"message\": \"I like animals.\",\n  \"locale\": \"fr\",\n  \"messageTypeId\": 531\n}\n
\n

\n# GET /api/templates/sms/get\n

Get an SMS template
API Explorer: USDC-based projects,\nEDC-based projects

Returns content and metadata for a specific SMS template.

Sample JSON response:

{\n  \"templateId\": 100692,\n  \"name\": \"SMS testing\",\n  \"message\": \"Here is example message\",\n  \"locale\": \"en\",\n  \"messageTypeId\": 531\n}\n
\n

\n# POST /api/templates/sms/proof\n

Send SMS template proof
API Explorer: USDC-based projects,\nEDC-based projects

Send a proof of an SMS template to a specific user for testing and preview\npurposes.

Sample request body:

{\n  \"templateId\": 53081,\n  \"recipientEmail\": \"test@example.com\",\n  \"dataFields\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\"\n  }\n}\n
\n

Sample JSON response:

{\n  \"success\": true,\n  \"messageId\": \"12345\"\n}\n
\n

\n# GET /api/templates/inapp/get\n

Get an in-app template
API Explorer: USDC-based projects,\nEDC-based projects

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

Sample JSON response:

{\n  \"templateId\": 00000000,\n  \"name\": \"My In-App template\",\n  \"html\": \"<!DOCTYPE html>\\n<html>\\n<head>\\n</head>\\n<body>\\n\\n</body>\\n</html>\",\n  \"inAppDisplaySettings\": {\n    \"top\": {\n      \"percentage\": 0\n    },\n    \"right\": {\n      \"percentage\": 0\n    },\n    \"bottom\": {\n      \"percentage\": 0\n    },\n    \"left\": {\n      \"percentage\": 0\n    }\n  },\n  \"webInAppDisplaySettings\": {\n    \"position\": \"Full\"\n  },\n  \"messageTypeId\": 000000,\n  \"isDefaultLocale\": true\n}\n
\n

\n# POST /api/templates/inapp/preview\n

Preview in-app template with custom data
API Explorer: USDC-based projects,\nEDC-based projects

Generate a fully rendered HTML preview of an in-app template using custom data.\nThis endpoint simulates how a template would appear when sent to a user,\nallowing you to test template rendering with specific user, event, and/or data\nfeed data.

Sample request body:

{\n  \"dataFields\": {\n    \"firstName\": \"John\",\n    \"loginCount\": 5,\n    \"lastLogin\": \"2023-01-15\"\n  },\n  \"dataFeed\": {\n    \"appName\": \"MyApp\",\n    \"version\": \"2.1.4\",\n    \"releaseNotes\": \"Dark mode, improved notifications\",\n    \"supportUrl\": \"https://example.com/support\"\n  },\n  \"fetchDataFeeds\": false\n}\n\n
\n

Sample response:

<!DOCTYPE html> <html> <head> </head> <body> <div class=\"welcome\">Welcome back John! You've opened MyApp 5 times. Last login: 2023-01-15.</div><div class=\"releaseNotes\">New in version 2.1.4: Dark mode, improved notifications. Need help? Visit https://example.com/support</div></body> </html>\n
\n

\n# POST /api/templates/inapp/upsert\n

Create an in-app template
API Explorer: USDC-based projects,\nEDC-based projects

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

\n# POST /api/templates/inapp/update\n

Update in-app template
API Explorer: USDC-based projects,\nEDC-based projects

Updates an in-app template.

\n# POST /api/templates/inapp/proof\n

Send in-app template proof
API Explorer: USDC-based projects,\nEDC-based projects

Send a proof of an in-app template to a specific user for testing and preview\npurposes.

Sample request body:

{\n  \"templateId\": 53081,\n  \"recipientEmail\": \"test@example.com\",\n  \"dataFields\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\"\n  }\n}\n
\n

Sample JSON response:

{\n  \"success\": true,\n  \"messageId\": \"12345\"\n}\n
\n

\n# POST /api/templates/bulkDelete\n

Bulk delete templates
API Explorer: USDC-based projects,\nEDC-based projects

Deletes one or more base templates. Templates associated with a campaign cannot\nbe deleted.

Sample request body:

{\n  \"ids\": [123, 456, 789]\n}\n
\n

Sample JSON response:

{\n  \"success\": true,\n  \"messageId\": \"12345\"\n}\n
\n

\n# Users

\n# Understanding message type subscriptions in User API responses

Iterable provides different types of subscription policies for message types:\nopt-in and opt-out. The primary difference for each type is whether users are\nsubscribed to or unsubscribed from the message type by default, and whether\nuser action is required to create or end their subscription.

By default, Iterable's Users API only returns explicit user subscriptions,\nand does not include implicit subscription statuses. As a result, API GET\nrequests return a partial view of a user's subscription statuses because they\ndo not include message types that the user is subscribed to or unsubscribed\nfrom by default. You can change this behavior by asking your account manager to\nenable implied subscriptions\nfor your project.

\n# Implied subscriptions in User API responses (optional)

Iterable's implied subscriptions feature enhances the User API to provide a\nmore complete and authoritative view of a user's message type subscriptions.\nThis is particularly beneficial when you use a mix of opt-in and opt-out\nmessage types and need a reliable way to determine a user's full subscription\nstatus.

When implied subscriptions is enabled, the following User API endpoints return\nboth explicit and implied subscription statuses:

Response bodies include the following additional parameters:

Example response body:

{\n  \"user\": {\n    \"email\": \"user@example.com\",\n    \"userId\": \"12345\",\n    \"dataFields\": {\n      \"firstName\": \"John\",\n      \"subscribedMessageTypeIds\": [],\n      \"unsubscribedMessageTypeIds\": [3]\n    },\n    \"allSubscribedMessageTypeIds\": [2, 4],\n    \"allUnsubscribedMessageTypeIds\": [1, 3]\n  }\n}\n
\n

It's also important to know that when implied subscriptions is enabled, the\nrequest payloads for User API endpoints that update subscriptions\ndo not change, and the same fields are expected in the request body:

\n

IMPORTANT

The parameters introduced by implied subscriptions\n(allSubscribedMessageTypeIds and allUnsubscribedMessageTypeIds) are\nincluded in the response bodies for the above referenced endpoints. They are\ngenerated dynamically at the time of the API request, and are not stored in the\nuser profile. Similarly, allSubscribedMessageTypeIds and\nallUnsubscribedMessageTypeIds should not be included in user update\nrequests.

Doing so can introduce the following problems:

    \n

  • These fields do not manage user subscriptions in Iterable, even when the\nrequest is accepted. This can create false expectations of changes to user\nsubscriptions that were not actually made and can cause confusion for your\nusers, problems with your preference center, and potential compliance issues.

  • If your project allows unrecognized user profile fields,\nwhich creates new user profile fields whenever an API request contains a\nfield that is not yet defined in the project's data schema, including\nallSubscribedMessageTypeIds and/or allUnsubscribedMessageTypeIds\ncan inadvertently create new user profile fields that are considered custom.\nThis can cause confusion in your user profile data because the field(s)\nappear to be managed by Iterable, which is not the case.

    • \n

Instead, update the user with their new subscription preferences using the\nstandard fields, subscribedMessageTypeIds and unsubscribedMessageTypeIds.\nOnly explicit subscriptions are stored in the user profile and expected in User\nAPI updates.

\n

To learn more about how implied subscriptions changes the functionality of a\ncustom preference center, see Using implied subscriptions in your preference center.

To enable implied subscriptions for your project, contact your Iterable account\nmanager.

\n# GET /api/users/forgotten\n

Get hashed forgotten users in compliance with GDPR
API Explorer: USDC-based projects,\nEDC-based projects

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

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

Learn about identifying users in API requests.

\n# GET /api/users/forgottenUserIds\n

Get hashed forgotten userIds in compliance with GDPR
API Explorer: USDC-based projects,\nEDC-based projects

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

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

\n# POST /api/users/forget\n

Forget a user in compliance with GDPR
API Explorer: USDC-based projects,\nEDC-based projects

\n

IMPORTANT

Processing times to forget a user in Iterable:

    \n
  • It can take up to ten minutes for Iterable to initiate forgetting a user.
  • User data will be fully forgotten within 30 days of the forget request.
    • \n

Use this endpoint only for handling \"right to be forgotten\" requests.

\n

This endpoint:

For a given user, call this endpoint for each project necessary.

Before forgetting or unforgetting a user, consider your\nproject type:

\n

NOTE

As of January 21, 2025, the POST /api/users/forget\nAPI endpoint can be called a maximum of 1000 times in a 24-hour period in an\nIterable project. See New limits for GDPR forget/unforget requests\nto learn more.

\n

\n# POST /api/users/unforget\n

Unforget a user in compliance with GDPR
API Explorer: USDC-based projects,\nEDC-based projects

Restores a given Iterable project's ability to store information about and send\nmessages to a user who had previously been forgotten.\nHowever, it does not recover any data stored about the user before they were\nforgotten.

For a given user, call this endpoint for each project necessary. Iterable\ngenerally processes unforget requests in six hours.

Before forgetting or unforgetting a user, consider your\nproject type:

\n

NOTE

As of January 21, 2025, the POST /api/users/unforget\nAPI endpoint can be called a maximum of 1000 times in a 24-hour period in an\nIterable project. See New limits for GDPR forget/unforget requests\nto learn more.

\n

\n# DELETE /api/users/{email}\n

Delete a user by email
API Explorer: USDC-based projects,\nEDC-based projects

\n

WARNING

This endpoint completely deletes the specified user profile, including\nsubscription settings and event history. If the user is ever re-added, their\nprofile will be empty and subscribed to everything by default. Deleting a user\nremoves their historic campaign metrics, too.

\n

Sample:

DELETE https://api.iterable.com/api/users/user%40example.com\n
\n

Before deleting users, consider your project type.\nIn email-based projects and hybrid projects, you can delete users by email or\nuserId. In userID-based projects, you can delete users only by userId.

\n# GET /api/users/{email}\n

Get a user by email (path parameter)
API Explorer: USDC-based projects,\nEDC-based projects

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

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

Sample:

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

Learn about identifying users in API requests.

\n# GET /api/users/getByEmail\n

Get a user by email (query parameter)
API Explorer: USDC-based projects,\nEDC-based projects

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

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

Learn about identifying users in API requests.

\n# POST /api/users/update\n

Update user data
API Explorer: USDC-based projects,\nEDC-based projects

Updates a user profile with the specified data. Learn about identifying users\nin API requests.

If you set mergeNestedObjects to true (defaults to false), the API merges\ndata in top-level objects rather than overwriting it with the values found\non the request. To learn more, read How mergeNestedObjects works.

For example, consider this user profile:

{\n  \"email\": \"user@example.com\",\n  \"mySettings\": {\n    \"mobile\": true\n  }\n}\n
\n

And this API request to POST /api/users/update:

{\n  \"email\": \"user@example.com\",\n  \"mergeNestedObjects\": true,\n  \"dataFields\": {\n    \"mySettings\": {\n      \"email\": true\n    }\n  }\n}\n
\n

Because mergeNestedObjects was true, the resulting user profile is:

{\n  \"email\": \"user@example.com\",\n  \"mySettings\": {\n    \"mobile\": true,\n    \"email\": true\n  }\n}\n
\n

If mergeNestedObjects had been false, the resulting user profile would\ninstead have been:

{\n  \"email\": \"user@example.com\",\n  \"mySettings\": {\n    \"email\": true\n  }\n}\n
\n

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

\n# POST /api/users/bulkUpdate\n

Bulk update user data
API Explorer: USDC-based projects,\nEDC-based projects

Bulk updates user data. This endpoint adds and overwrites user profile fields as\nneeded. 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\nobjects with the values provided for them in the request body, set\nmergeNestedObjects to true. To learn more, see How mergeNestedObjects works.

When updating an existing field, you cannot change its data type (the new value\nmust have the same data type as the old value).

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

Iterable handles requests to this endpoint separately from requests to\nsingle-user endpoints (update, updateEmail, updateSubscriptions, etc.).\nFor a given user, in a short period of time, only use single-user calls or bulk\nupdate calls. Otherwise, results may be inconsistent.

When updating the emailListIds or userListIds field, this endpoint does not\ngenerate subscribe or unsubscribe events. The same is true for updates to\nunsubscribedChannelIds and unsubscribedMessageTypeIds (but these can only\nbe updated by this endpoint in projects where the opt-in message types feature\nis not enabled).

To create a user profile for a user without a known email address:

Sample request body:

{\n  \"users\": [\n    {\n      \"email\": \"user@example.com\",\n      \"userId\": \"0192837821\",\n      \"dataFields\": {\n        \"favoriteColor\": \"orange\"\n      }\n    },\n    {\n      \"email\": \"user2@example.com\",\n      \"userId\": \"9281928374\",\n      \"dataFields\": {\n        \"favoriteColor\": \"blue\"\n      }\n    },\n    {\n      \"userId\": \"2394029394\",\n      \"preferUserId\": true,\n      \"dataFields\": {\n        \"favoriteColor\": \"red\"\n      }\n    }\n  ]\n}\n
\n

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

Delete user by userId
API Explorer: USDC-based projects,\nEDC-based projects

Deletes a user (identified by userId).

\n

WARNING

This endpoint completely deletes the specified user profile, including\nsubscription settings and event history. If the user is ever re-added, their\nprofile will be empty and subscribed to everything by default. Deleting a user\nremoves their historic campaign metrics, too.

\n

Sample:

GET https://api.iterable.com/api/users/byUserId/{userId}\n
\n

Before deleting users, consider your project type.\nIn email-based projects and hybrid projects, you can delete users by email or\nuserId. In userID-based projects, you can delete users only by userId.

\n# GET /api/users/byUserId/{userId}\n

Get a user by userId (path parameter)
API Explorer: USDC-based projects,\nEDC-based projects

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

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

Sample:

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

Learn about identifying users in API requests.

\n# GET /api/users/byUserId\n

Get a user by userId (query parameter)
API Explorer: USDC-based projects,\nEDC-based projects

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

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

Learn about identifying users in API requests.

\n# POST /api/users/registerBrowserToken\n

Register a browser token for web push
API Explorer: USDC-based projects,\nEDC-based projects

Learn about identifying users in API requests.

\n# POST /api/users/updateSubscriptions\n

Update user subscriptions
API Explorer: USDC-based projects,\nEDC-based projects

Updates a user's subscription settings with new settings.

Additional notes:

Sample request body:

{\n  \"email\": \"user@example.com\",\n  \"userId\": \"0192837821\",\n  \"userListIds\": [\n    5,\n    6,\n    7\n  ],\n  \"unsubscribedChannelIds\": [\n    100\n  ],\n  \"unsubscribedMessageTypeIds\": [\n    100\n  ],\n  \"campaignId\": 123,\n  \"templateId\": 123,\n  \"validateChannelAlignment\": false\n}\n
\n

\n# POST /api/users/bulkUpdateSubscriptions\n

Bulk update user subscriptions
API Explorer: USDC-based projects,\nEDC-based projects

Updates one or more users' subscription preferences.

Additional notes:

Sample request body:

{\n  \"updateSubscriptionsRequests\": [\n    {\n      \"email\": \"user@example.com\",\n      \"userId\": \"0192837821\",\n      \"unsubscribedChannelIds\": [\n        12345,\n        23456\n      ],\n      \"unsubscribedMessageTypeIds\": [\n        65432\n      ],\n      \"campaignId\": 34567,\n      \"templateId\": 456789\n    },\n    {\n      \"email\": \"user2@example.com\",\n      \"userId\": \"2131238573\",\n      \"unsubscribedChannelIds\": [\n        12345\n      ],\n      \"campaignId\": 34567,\n      \"templateId\": 456789\n    }\n  ]\n}\n
\n

\n# POST /api/users/updateEmail\n

Update user email
API Explorer: USDC-based projects,\nEDC-based projects

Updates a user's email.

\n

IMPORTANT

Use this endpoint with email-based projects. To update\nan email in a userID-based or hybrid project, use POST /api/users/update.

\n

In the request body, specify currentEmail or currentUserId, but not both. If\nyou provide both, currentEmail takes precedence.

Sample request body:

{\n  \"currentEmail\": \"oldEmail@example.com\",\n  \"newEmail\": \"newEmail@example.com\"\n}\n
\n

Another sample request body:

{\n  \"currentUserId\": \"user1234567\",\n  \"newEmail\": \"newEmail@example.com\"\n}\n
\n

Returns an error if the new email already exists in Iterable, or if the new\nemail has been forgotten via a GDPR request.

Learn more about identifying users in API requests.

\n# GET /api/users/getFields\n

Get all user fields
API Explorer: USDC-based projects,\nEDC-based projects

Gets all user profile fields in a project.

Sample:

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

Sample JSON response:

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

\n# GET /api/users/getSentMessages\n

Get messages sent to a user
API Explorer: USDC-based projects,\nEDC-based projects

Returns a list of sent messages to a user within a certain time period.\nIncludes the messageId, campaignId, templateId and createdAt data. Does\nnot include the body of the message. campaignId, excludeBlastCampaigns,\nstartDateTime 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\n
\n

Sample JSON response:

{\n  \"messages\": [\n    {\n      \"messageId\": \"9c438a20d26e4e9f8ad4edea23f811cd\",\n      \"campaignId\": 123,\n      \"templateId\": 456,\n      \"createdAt\": \"2016-10-04 00:54:00 +00:00\"\n    },\n    {\n      \"messageId\": \"9c438a20d26e4e9f8ad4edea23f811cd\",\n      \"campaignId\": 321,\n      \"templateId\": 654,\n      \"createdAt\": \"2016-09-30 19:50:00 +00:00\"\n    }\n  ]\n}\n
\n

\n# POST /api/auth/jwts/invalidate\n

Invalidate all JWTs issued for a user
API Explorer: USDC-based projects,\nEDC-based projects

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

\n# POST /api/users/disableDevice\n

Disable pushes to a mobile device
API Explorer: USDC-based projects,\nEDC-based projects

Disables device. Prevents it from receiving push notifications.\nMust include the device token.

Learn about identifying users in API requests.

If the token exists on multiple user profiles, including email disables\nthe token for that one email address only. If email is not included, the toke\nis disabled from all user profiles. The same is true for including or not\nincluding userId.

Sample request body:

{\n  \"token\": \"sampleToken123\",\n  \"email\": \"user@example.com\",\n  \"userId\": \"2\"\n}\n
\n

\n# POST /api/users/registerDeviceToken\n

Register a device token for push
API Explorer: USDC-based projects,\nEDC-based projects

Registers a mobile device token to enable push notifications.

The applicationName parameter value should be the Package Name in the\nDetails page of your mobile app, as found in Settings > Apps and websites, and\nis also called the Website Identifier when you are creating a new mobile\napp.

Learn about identifying users in API requests.

\n

TIP

Learn more about sending push notifications with Iterable.

\n

Sample request body:

{\n  \"email\": \"user@example.com\",\n  \"device\": {\n    \"token\": \"sampletoken123\",\n    \"platform\": \"APNS\",\n    \"applicationName\": \"com.example.pizzatracker\",\n    \"dataFields\": {\n      \"phoneModel\": \"iPhone 6 plus\"\n    }\n  },\n  \"userId\": \"2\"\n}\n
\n

\n# POST /api/users/merge\n

Merge users
API Explorer: USDC-based projects,\nEDC-based projects

Combines two user profiles into one, including user profile fields, system\nevents, and custom events. Specify a source user profile and a destination user\nprofile. The source user profile is deleted after the merge.

To understand how to use this endpoint to merge user profiles, how data is\nmerged, and important considerations prior to merging, read\nMerging User Profiles.

Asynchronous processing time - Iterable processes the merge operation in the\nbackground. A successful response from the API does not indicate that the merge\nhas completed, but that the merge operation has been initiated. The source\nprofile is deleted after 5+ minutes. Before that point, the source profile\nremains in Iterable, and its data may not yet be visible on the destination\nprofile.

\n# API key requirements

Here are some things to keep in mind when selecting an API key\nto call this endpoint:

API key types:

JWT-enabled API keys:

When calling this endpoint with a JWT-enabled API key, provide a valid JWT\ntoken for the destination user, not the source user.

\n# Specifying users to merge

In the JSON body for your request, identify a source user (sourceEmail or\nsourceUserId) and a destination user (destinationEmail or\ndestinationUserId), depending on your project type and the identifiers of the\nuser profiles you're merging. The destination identifier is the user's final\nidentifier after the merge.

\n# Merging fields

When you merge two user profiles, Iterable merges the data from the source\nprofile into the destination profile in the following manner:

\n# Merging array data

Iterable can merge the contents of specific arrays if you specify\nthis behavior in the body of your merge API request.

To merge an array, include an arrayMerge field (optional), containing an\narray of objects, in the body of the user merge API request. Each object in the arrayMerge array must have a field property (required).

To specify how to remove duplicates from the merged array:

The order of the merged array is not guaranteed. Arrays can be combined in any\norder.

\n# Example requests

Example request #1, email-based project

POST https://api.iterable.com/api/users/merge

{\n    \"sourceEmail\": \"user1@example.com\",\n    \"destinationEmail\": \"user2@example.com\"\n}\n
\n

Example request #2, email-based project

POST https://api.iterable.com/api/users/merge

{\n    \"sourceUserId\": \"exampleUser3\",\n    \"destinationEmail\": \"user3@example.com\"\n}\n
\n

Example request #3, email-based project

POST https://api.iterable.com/api/users/merge

{\n    \"sourceUserId\": \"exampleUser4\",\n    \"destinationUserId\": \"exampleUser5\"\n}\n
\n

Example request #4, hybrid project

POST https://api.iterable.com/api/users/merge

{\n    \"sourceEmail\": \"user6@example.com\",\n    \"destinationEmail\": \"user7@example.com\"\n}\n
\n

Example request #5, hybrid project

POST https://api.iterable.com/api/users/merge

{\n    \"sourceEmail\": \"user8@example.com\",\n    \"destinationUserId\": \"exampleUser9\"\n}\n
\n

Example request #6, hybrid project

POST https://api.iterable.com/api/users/merge

{\n    \"sourceUserId\": \"exampleUser10\",\n    \"destinationEmail\": \"user11@example.com\"\n}\n
\n

Example request #7, userID-based project

POST https://api.iterable.com/api/users/merge

{\n    \"sourceUserId\": \"exampleUser12\",\n    \"destinationUserId\": \"exampleUser13\"\n}\n
\n

Example request #8, hybrid project, array merging

POST https://api.iterable.com/api/users/merge

{\n    \"sourceUserId\": \"exampleUser10\",\n    \"destinationEmail\": \"user11@example.com\",\n    \"arrayMerge\": [ \n        { \"field\": \"arrayOfObjects1\", \"dedupeBy\": \"fieldA\" }, \n        { \"field\": \"arrayOfObjects2\" } \n    ]\n}\n
\n

In this example:

\n# Response body

On success, this endpoint returns status code 200, with this JSON response body:

{\n    \"msg\": \"\",\n    \"code\": \"Success\",\n    \"params\": null\n}\n
\n

On failure, this endpoint returns a corresponding HTTP status code, with a JSON\nresponse body similar to this:

{\n    \"msg\": \"Invalid destinationEmail exampleUser1\",\n    \"code\": \"InvalidEmailAddressError\",\n    \"params\": null\n}\n
\n

\n# Response status codes

Possible values for HTTP status code, message, and code:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
HTTP status code Message Code
200 Success Success
400 Invalid sourceEmail {email} InvalidEmailAddressError
400 Invalid destinationEmail {email} InvalidEmailAddressError
400 Invalid sourceUserId {userId} ({reason, e.g. “too long” or “empty”}) InvalidUserIdError
400 Invalid destinationUserId {userId} ({reason, e.g. “too long” or “empty”}) InvalidUserIdError
400 Either sourceEmail or sourceUserId must be set, but not both BadParams
400 Either destinationEmail or destinationUserId must be set, but not both BadParams
400 Cannot merge, sourceEmail {email} does not exist BadParams
400 Cannot merge, sourceUserId {userId} does not exist BadParams
409 Cannot merge, sourceEmail {email} forgotten ForgottenUserError
409 Cannot merge, sourceUserId {userId} forgotten ForgottenUserError
409 Cannot merge, destinationEmail {email} forgotten ForgottenUserError
409 Cannot merge, destinationUserId {userId} forgotten ForgottenUserError
400 User key update already in progress for user GenericError
400 Merging user by sourceEmail not supported for User ID project BadParams
400 Merging user by destinationEmail not supported for User ID project BadParams
400 Cannot merge, {dedupeBy} is not a top-level field BadParams
400 Cannot merge. On {source or destination} user, the array specified by {field} is contained in an array. BadParams
400 Cannot merge, {field} is a system field BadParams
400 Cannot merge, dedupeBy field {dedupeBy} is present for non-object arrayMerge field {field} BadParams
403 Your project does not have access to the merge user profile feature. Please talk to your CSM for access Forbidden
500 Merge user from {0} to {1} failed DatabaseError

\n# Verify

\n# POST /api/verify/sms/begin\n

Begin SMS Verification
API Explorer: USDC-based projects,\nEDC-based projects

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

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

Sample request body:

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

To find a verificationProfileId, look on the Settings > Sending Platforms\npage in Iterable. Open the Twilio or Telnyx account you use to send SMS\nverification messages, open the Verification Profiles menu, and grab a\nverification profile ID from the right-most column.

Call this endpoint only for projects that use Iterable SMS to send SMS messages.\nIf you use your own Twilio or Telnyx account, call their verification endpoints\ndirectly.

To use this endpoint, first ask your Iterable customer success manager to add\nSMS phone verification to your project. To learn more, read\nSMS Phone Verification

\n# POST /api/verify/sms/check\n

Check SMS Verification Code
API Explorer: USDC-based projects,\nEDC-based projects

Checks whether the code included in the request body matches the most recent,\nnon-expired, not-yet-verified SMS verification code sent to phoneNumber by the\nspecified verificationProfileId.

Sample request body:

{\n  \"verificationProfileId\": 12345,\n  \"phoneNumber\": \"+14155550132\",\n  \"code\": \"13579\"\n}\n
\n

To find a verificationProfileId, look on the Settings > Sending Platforms\npage in Iterable. Open the Twilio or Telnyx account you use to send SMS\nverification messages, open the Verification Profiles menu, and grab a\nverification profile ID from the right-most column.

For code, provide the code entered by your users in your mobile app or website\nafter you sent them a verification SMS.

If code is correct, this endpoint returns a 200 response with a JSON body\nthat has a params object with status set to verified. For example:

{\n    \"msg\": \"\",\n    \"code\": \"Success\",\n    \"params\": {\n        \"status\": \"verified\"\n    }\n}\n
\n

If code is incorrect, this endpoint returns a 200 response with a JSON body\nthat has a params object with status set to rejected. For example:

{\n    \"msg\": \"incorrect verification code\",\n    \"code\": \"Success\",\n    \"params\": {\n        \"status\": \"rejected\"\n    }\n}\n
\n

Call this endpoint only for projects that use Iterable SMS to send SMS messages.\nIf you use your own Twilio or Telnyx account, call their verification endpoints\ndirectly.

To use this endpoint, first ask your Iterable customer success manager to add\nSMS phone verification to your project. To learn more, read\nSMS Phone Verification

\n# Webhooks

\n# GET /api/webhooks\n

Get webhooks
API Explorer: USDC-based projects,\nEDC-based projects

List the webhooks in the project.

\n# POST /api/webhooks\n

Update webhook
API Explorer: USDC-based projects,\nEDC-based projects

Update a webhook.

\n# Web push notifications

\n# POST /api/webPush/cancel\n

Cancel a web push notification to a user
API Explorer: USDC-based projects,\nEDC-based projects

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

Learn about identifying users in API requests.

\n# POST /api/webPush/target\n

Send web push notification to user
API Explorer: USDC-based projects,\nEDC-based projects

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

Learn about identifying users in API requests.

\n# WhatsApp

\n# POST /api/whatsApp/target\n

Send WhatsApp campaign to user
API Explorer: USDC-based projects,\nEDC-based projects

Sends a WhatsApp campaign to a specified user. Data fields included in the API\nrequest body take precedence over data fields on the user’s profile. Campaign\nmust be set up in Iterable prior to sending the API request. If the sendAt\nfield is not included, the message is sent immediately.

Sample request body:

{  \n  \"campaignId\": 1234567,  \n  \"dataFields\": {},  \n  \"recipientEmail\": \"user@example.com\",  \n  \"sendAt\": \"string\"  \n}\n
\n

Include a recipientUserId or recipientEmail, but not both. Learn more about\nidentifying users in API requests.

On success, this endpoint returns status code 200 and creates a whatsAppSend\nevent on the specified user's Iterable profile.

\n# POST /api/whatsApp/cancel\n

Cancel a WhatsApp campaign for a user
API Explorer: USDC-based projects,\nEDC-based projects

Cancels a WhatsApp campaign for a specified user. Must include either the\ncampaignId field or the scheduledMessageId field. If using the campaignId\nfield, must also specify the appropriate user identifier (email or userId\nfield) for your project type.

Sample request body:

{  \n  \"email\": \"user@example.com\",  \n  \"campaignId\": 1234567,  \n  \"scheduledMessageId\": \"210badf49fe54f2591d64ad0d055f4fb\",  \n  \"userId\": 12345\n}\n
\n

On success, this endpoint returns status code 200, and the campaign is not sent\nto the specified user.

\n# Want to learn more?

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

Iterable Academy

Support docs

\n
","user_segment_ids":[]}}