API Overview and Sample Payloads

This article includes a complete overview of each Iterable API type, how to use them, sample requests and best practices.

When submitting an API call, you can enter your API key either in the URI or in the headers.

Skip to more specific sections here:

1. Where is my API Key?
2. Where are Iterable's API Docs?
3. Where do I put my API key in the request?
4. API Endpoints
   • Lists
   • Events
   • Users
   • Push
   • inApp
   • Experiments
   • SMS
   • Templates
   • Campaigns
   • Commerce
   • Email
   • Export
   • Workflows
     
     

Where is my API Key?

You can find your API Key by going to Integrations > API Keys in Iterable's left side menu.

Where are Iterable's API Docs?

You can add users into Iterable, update users, send events, access data, create campaigns and much more with Iterable's APIs.

To view Iterable's API Explorer, go to Support > API Documentation on the left side menu.

You will see a list of our APIs with different functions.

You can also send sample requests on this page.

Where do I put my API key in the request?

The base URI is api.iterable.com.

You can put the API key directly in the query string, using api_key or apiKey. An example of an API call for the events track API would be:

https://api.iterable.com/api/events/track?apiKey=yourkeyhere

You can also place your API key in the header. The name of the header field for the API key is Api_Key or Api-Key.

In our API Explorer docs, before entering your JSON payload, you'll need to authorize the API key in the Authentication Header section on the upper left hand corner of the page. If you enter the JSON payload first, once you authorize the key, the JSON payload will be erased and need to be re-entered. 

API Endpoints

Lists 

Add Subscribers to List

This is used to add a subscriber to an existing static list.

Sample JSON Body:

{
   "listId": 123,
   "subscribers": [
       {
           "email": "sherry@iterable.com",
           "dataFields": {              <-- (optional)
               "firstName": "Sherry",
               "hasCat": true
           },
           "userId": "1"               <-- (optional)
       }
   ]
} 

Delete Static List

This is used to delete a list. All users who are part of the deleted list will have the list removed from their profile.

Sample:

https://api.iterable.com:443/api/lists/21398?api_key=[API_KEY]

Remove Users from List

This is used to remove one or more subscribers from an existing static list.

Sample JSON Body:

{
   "listId": 1,
   "subscribers": [{
      "email": "sherry@iterable.com"
    }, {
      "email": "jeremy@iterable.com"
    }],
   "campaignId": 123,                         <-- (optional)
   "channelUnsubscribe": false              <-- (optional)
}

Get Users in List

Returns a string of all the users who are on a list. Works for both Standard and Dynamic lists

Sample: 

https://api.iterable.com:443/api/lists/getUsers?listId=21401&api_key=[API_KEY]

Get Lists from Project

This will return all the static lists in a project.

Sample: 

https://api.iterable.com:443/api/lists?api_key=[API_KEY]

Create Static List

Use this to create a new, empty, standard list with the specified name. Upon creation of the new list, it will return the list ID.

Sample JSON Body:

{
    "name":"exampleListName"
}

Events

Get Events Associated with a User

Use this to receive events associated with a user profile. This will include custom events and Iterable-standard events like "Sent an Email", "Opened email" and "Clicked a link". The default value for "limit" is 30 - if no override is set, the user's last 30 events will be returned.

Sample:

https://api.iterable.com:443/api/events/jeremy%40iterable.com?api_key=[API_KEY]

Response:

{
   "events": [{
      "contentId": 330397,
      "recurringCampaignId": 12345,
      "email": "jeremy@iterable.com",
      "createdAt": "2016-10-04 00:54:00 +00:00",
      "campaignId": 67890,
      "templateId": 11111,
      "messageId": "1234example9876",
      "eventType": "emailSend"
}, {
      "contentId": 329261,
      "recurringCampaignId": 12345,
      "email": "jeremy@iterable.com",
      "createdAt": "2016-09-30 19:50:00 +00:00",
      "campaignId":67890,
      "templateId": 22222,
      "messageId": "9876example1234",
      "eventType": "emailSend"
}]
}

Track Event

Use this to send custom events, such as user logins, signups and app opens to Iterable. These events can then be used to trigger workflows or for custom conversion tracking in campaigns. Data fields in custom event calls can be used to populate merge parameters in templates. You can also segment on these events in the user profile. If 'createdAt' field is not included, event will be sent immediately. Either email or userId must be passed in to identify the user. If both are passed in, email takes precedence.

An optional String id parameter may be passed as one of the top level parameters. If an event exists with that id, the event will be updated. If no id is specified, a new id will automatically be generated and returned.

Sample JSON Body:

{
   "email": "sherry@iterable.com",         <-- (optional)
   "eventName": "startedMembership",
   "id": "12345",                          <-- (optional)
   "dataFields": {                         <-- (optional)
       "source": "facebook",
       "membershipType": "monthly"
     },
   "userId": "1",                  <-- (optional)
   "campaignId": 123,              <-- (optional)
   "templateId": 123               <-- (optional)
}

Track Push Open

Use this to track a mobile push notification open. Either email or userId must be passed in to identify the user. If both are passed in, email takes precedence. Include the campaignId in the call and it will attribute the open to the Iterable campaign that sent the notification. Learn more about Iterable push notifications here.

Sample JSON Body:

{
   "email": "jeremy@iterable.com"",  <-- (optional)
   "userId": "2",                    <-- (optional)
   "campaignId": 12345,              <-- (optional)
   "templateId": 67890,              <-- (optional)
   "messageId": "01234567890",       <-- (optional)
   "dataFields": {                   <-- (optional)
      "openedMostRecentPush": true
   }
}

Track In-App Click

Use this to track an in-app notification click. Either email or userId must be passed in to identify the user. If both are passed in, email takes precedence. Learn more about Iterable in-app notifications here.

Sample JSON Body:

{
   "email": "chris@iterable.com"",    <-- (optional)
   "userId": "123",                   <-- (optional)
   "messageId": "01234567890",
   "buttonIndex": 12345               <-- (optional)
}

Consume an In-App Notification

Either email or userId must be passed in to identify the user. If both are passed in, email takes precedence.

Sample JSON Body:

{
   "email": "chris@iterable.com"",    <-- (optional)
   "userId": "123",                   <-- (optional)
   "messageId": "01234567890",
}

Track In-App Open

Use this to track an in-app notification open. Either email or userId must be passed in to identify the user. If both are passed in, email takes precedence. Learn more about Iterable in-app notifications here.

Sample JSON Body:

{
   "email": "chris@iterable.com",     <-- (optional)
   "userId": "123",                   <-- (optional)
   "messageId": "01234567890",
   "buttonIndex": 12345               <-- (optional)
}

Users 

Bulk Update Subscriptions

Updates one or more users' subscription preferences. Include campaign and/or template ID to attribute unsubscribes to campaigns and templates. Either email or userId is required.

Note: This endpoint will overwrite existing subscription preferences if fields are set and not null.

Sample JSON Body:

{
  "updateSubscriptionsRequests": [
    {
      "email": "chris@iterable.com",             <-- (optional)

      "userId": "0192837821",                    <-- (optional)
      "unsubscribedChannelIds": [12345,23456],   <-- (optional)
      "unsubscribedMessageTypeIds": [65432],     <-- (optional)
      "campaignId": 34567,                       <-- (optional)
      "templateId": 456789                       <-- (optional)
    },
    {
      "email": "sherry@iterable.com",       <-- (optional)

      "userId": "2131238573",               <-- (optional)
      "unsubscribedChannelIds": [12345],    <-- (optional)
      "campaignId": 34567,                  <-- (optional)
      "templateId": 456789                  <-- (optional)
    }
  ]
}

Update a User's Email

Updates a user's email address. If the new email already exists in Iterable, an error will occur.

Sample JSON Body:

{
   "currentEmail": "sherrychao@iterable.com",     <-- (optional)

   "userId": "0192837821",                        <-- (optional)
   "newEmail": "sherry@iterable.com"
}

Notes: 

• All profile data and events will be migrated to the new email address.
• Either email or userId must be passed in to identify the user. If both are passed in, email takes precedence.

Bulk Update

Updates user profiles for one or more users.

Notes: 

• This endpoint is not recommended for time-sensitive user updates, as there may be a delay before the updates are completely processed due to the potentially high volume of these requests.
• There is also a limit of up to 4MB or roughly 1000 users per call.
• Changing emailListIds, unsubscribedChannelIds, messageTypeIds through this endpoint will NOT generate unsubscribe events.
• If any of the fields emailListIds, unsubscribedChannelIds and/or messageTypeIds are included for a given profile, then whatever is included in the array will be the preferences set for that profile, regardless of what the preferences were before that. If those fields are not included for a given profile, then no adjustments to preferences will be made for that profile.
• Either email or userId is required.

Sample JSON Body:

{
   "users": [{
   "email": "sherry@iterable.com",     <-- (optional)

   "userId": "0192837821",             <-- (optional)
   "dataFields": {
      "favoriteColor": "orange",
      "userId": "1"
   }
}, {
   "email": "jeremy@iterable.com",     <-- (optional)

   "userId": "9281928374",             <-- (optional)
   "dataFields": {
      "favoriteColor": "blue",
      "userId": "2"
   }
}]
}

Register Device Token

Registers a mobile device token to enable push notifications. Either email or userId must be passed in to identify the user. If both are passed in, email takes precedence. Learn more about push here.

Sample JSON Body:

{
   "email": "jeremy@iterable.com",         <-- (optional)
   "device": {
      "token": "sampleToken123",
      "platform": "APNS",
      "applicationName": "Pizza Tracker",
      "dataFields": {                      <-- (optional)
         "phoneType": "iPhone 6 plus"
      }
   },
   "userId": "2"                          <-- (optional)
}

Update User Subscriptions

Updates a user's subscription settings with new settings. 

Note: This endpoint will overwrite existing subscription preferences if fields are set and not null. Either email or userId is required. 

Sample JSON Body:

{
   "email": "sherry@iterable.com",        <-- (optional)

   "userId": "0192837821",                <-- (optional)
   "emailListIds": [5, 6, 7],             <-- (optional)
   "unsubscribedChannelIds": [100],       <-- (optional)
   "unsubscribedMessageTypeIds": [100],   <-- (optional)
   "campaignId": 123,                     <-- (optional)
   "templateId": 123                      <-- (optional)
}

Get User Fields

Gets just the fields on users’ profiles.

Sample:

https://api.iterable.com:443/api/users/getFields?api_key=[API_KEY]

Sample response:

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

Delete a User

Warning: This will completely wipe the user profile, including subscription settings and event history. If the user is re-added, the profile will be completely empty and will be subscribed to everything by default. Deleting a user will also remove them historic campaign metrics as well.

Sample:

https://api.iterable.com:443/api/users/jeremy%40iterable.com?api_key=[API_KEY]

Get a User

Gets user's data fields and info.

Sample:

https://api.iterable.com:443/api/users/jeremy%40iterable.com?api_key=[API_KEY]

Delete a User by userID

Delete a user using userId instead of email.

Warning: This will completely wipe the user profile, including subscription settings and event history. If the user is re-added, the profile will be completely empty and will be subscribed to everything by default.

Sample:

https://api.iterable.com:443/api/users/byUserId/[USER_ID]?api_key=[API_KEY]

Get a User by userId 

Gets user's data fields and info. Uses userId instead of the user's email.

Sample:

https://api.iterable.com:443/api/users/byUserId?userId=[USER_ID]&api_key=[API_KEY]

User Update

Updates a user profile with new data fields. Missing fields are not deleted and new data is merged. 

Notes

• Either email or userId is required
• mergeNestedObjects will merge top level object data instead of overwriting it if set to true (default: false)
  • If user profile has data {"mySettings":{"mobile":true}} and change contact field has data: {"mySettings":{"email":true}}, the resulting merged profile will be: {"mySettings":{"mobile":true,"email":true}}
  • If merge nested objects is set to false then the resulting profile will be overwritten and set to {"mySettings":{"email":true}}

Sample JSON body:

{
   "email": "sherry@iterable.com",  <-- (optional)
   "dataFields": {
      "catName": "Jimmy"
   },
   "userId": "1",                  <-- (optional)

   "mergeNestedObjects" : true     <-- (optional)
}

Create a User Profile for a userId

Creates a new user profile with an anonymous email for a userId if the userId does not yet exist. Sample:

https://api.iterable.com:443/api/createUserForUserId?userId=[USER_ID]?api_key=[API_KEY]

Get Sent Messages

Returns a list of sent messages to a user within a certain time period. Includes the messageId, campaignId, templateId, and createdAt data. Does not include the body of the message.

campaignId, excludeBlastCampaigns, startDateTime, and endDateTime are all optional

Sample:

https://api.iterable.com:443/api/users/getSentMessages?email=jeremy%40iterable.com&limit=2&campaignId=123&excludeBlastCampaigns=false&startDateTime=2016-10-01%2021%3A00%3A27%20%2B00%3A00&endDateTime=2016-10-29%2000%3A54%3A00%20%2B00%3A00&api_key=[API_KEY]

Sample response:

{
   "messages": [{
      "messageId": "9876example4321",
      "campaignId": 123,
      "templateId": 456,
      "createdAt": "2016-10-04 00:54:00 +00:00"
}, {
      "messageId": "1234example5678",
      "campaignId": 321,
      "templateId": 654,
      "createdAt": "2016-09-30 19:50:00 +00:00"
}]
}

Disable Device

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

If the token exists on multiple user profiles, including 'email' will disable the token for that one email address only. If 'email' is not included, the token will be disabled from all user profiles. The same is true for including or not including 'userId'.

Sample JSON body:

{
   "token": "sampleToken123",
   "email": "jeremy@iterable.com",           <-- (optional)
   "userId": "2"                        <-- (optional)
}

Push 

Target User

Sends a triggered push notification to a specific user. Request data fields will override existing user profile data fields. Campaign must be set up in Iterable beforehand. If 'sendAt' field is not included, message will be sent immediately.

Sample JSON body:

{
   "campaignId": 13770,
   "recipientEmail": "sherry@iterable.com",
   "dataFields": {                                <-- (optional)
     "newUser": "FALSE"
   },
   "sendAt": "2016-08-25 23:25:00 +00:00"         <-- (optional)
}

inApp

Get In-App Messages for User

Get in-app mobile messages that should be displayed to a user.

Sample JSON body:

https://api.iterable.com:443/api/inApp/getMessages?email=chris%40iterable.com&userId=1234&count=123&api_key=[API_KEY]

Target User

Sends In-App notification to a specific user. Request data fields will override existing user profile data fields. Campaign must be set up in Iterable beforehand. If 'sendAt' field is not included, message will be sent immediately.

Sample JSON body:

{
   "campaignId": 13770,
   "recipientEmail": "sherry@iterable.com",
   "dataFields": {                                <-- (optional)
      "newUser": "FALSE"
   },
   "sendAt": "2016-08-25 23:25:00 +00:00"         <-- (optional)
}

Experiments

Get Experiment Metrics

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

Sample:

https://api.iterable.com:443/api/experiments/metrics?experimentId=12345&campaignId=23456&startDateTime=2017-06-01&endDateTime=2017-07-01&api_key=[API_KEY]

SMS

Target User

Sends SMS to a specific user. Request data fields will override existing user profile data fields. Campaign must be set up in Iterable beforehand. If 'sendAt' field is not included, message will be sent immediately.

Sample JSON body:

{
   "campaignId": 13770,
   "recipientEmail": "sherry@iterable.com",
   "dataFields": {                                <-- (optional)
      "newUser": "FALSE"
   },
   "sendAt": "2016-08-25 23:25:00 +00:00"         <-- (optional)
}

Message Types

Get Message Types

Lists all message types for that project.

Sample response:

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

Channels

Get Channels

Lists all channels for that project.

Sample response:

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

Templates 

Update SMS Template

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

Sample JSON Body:

{
   "templateId": 123,
   "name": "My SMS Title",                    <-- (optional)
   "message": "I like animals.",              <-- (optional)
   "locale": "fr",                            <-- (optional)
   "messageTypeId": 531                       <-- (optional)
}

Get Templates in a Project

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

Note: Leaving templateType blank in the request will result in Base templates only being returned.

Sample:

https://api.iterable.com:443/api/templates?templateType=Base&messageMedium=Email&api_key=[API_KEY]

Sample response:

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

Update Push Template

Updates a specific Push template. Most fields are optional. Include the fields you wish to update.

Sample JSON Body:

{
   "templateId": 123,
   "message": "I like animals, do you?",
   "payload": {
      "fields": "List[scala.Tuple2 <java.lang.String, play.api.libs.json.JsValue>]",
      "value": "scala.collection.Map <java.lang.String, play.api.libs.json.JsValue>"
   }
}

Get an Email Template

Get an email template's information and html.

Sample response:

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

Upsert an SMS Template

Creates a new template if one does not exist, or updates all templates with the specified client template Id.

Sample JSON body:

{
   "clientTemplateId": 112233,
   "name": "SMS Test",              <-- (optional)
   "message": "Hello There!",       <-- (optional)
   "locale": "en",                  <-- (optional)
   "messageTypeId": "1234"
}

Get an SMS Template

Get an SMS template information and message string.

Sample response:

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


Get a Push Template

Get a push template information and message string.

Sample response:

{
   "templateId": 68785,
   "name": "3 months before wedding date",
   "message": "3 months until the big day! Congrats!",
   "payload": {
      "fields": "List[scala.Tuple2 <java.lang.String, play.api.libs.json.JsValue>]",
      "value": "scala.collection.Map <java.lang.String, play.api.libs.json.JsValue>"
   },
   "badge": "JM Photography",
   "messageTypeId": 3868,
   "sound": ""
}

Get an Email Template from a Client Template Id

Get an array of template Ids that match a client template Id. If the client has set a 'clientTemplateId' on email template(s), then this call will return those templates.

Update Email Template

Updates a specific email template. Only fields specified will be updated.

Template before update:

Sample JSON Body

{
   "templateId": 53081,
   "name": "Lots of Cats",         <-- (optional)
   "fromName": "Felicia the Cat",            <-- (optional)
   "fromEmail": "lindsey+replyto@iterable.com",        <-- (optional)
   "replyToEmail": "lindsey+replyto@iterable.com",       <-- (optional)
   "subject": "Rank These Cats",           <-- (optional)
   "preheaderText": "10 out of 10!",            <-- (optional)
   "html": "<html><body><p>So many cats!</p></body></html>"    <-- (optional)
}

Template after update:

Note: This call will not work on templates made with the Drag and Drop Editor

Upsert an Email Template

Creates a new template if one does not exist, or updates all templates with the specified client template Id.

Sample JSON body:

{
   "clientTemplateId": 112233,
   "name": "Lots of Cats",              <-- (optional)
   "fromName": "Felicia the Cat",           <-- (optional)
   "fromEmail": "Jeremy@iterable.com",         <-- (optional)
   "replyToEmail": "Jeremy+replyTo@iterable.com",         <-- (optional)
   "subject": "Rank These Cats",           <-- (optional)
   "preheaderText": "10 out of 10!",           <-- (optional)
   "html": "<html><body><p>So many cats!</p></body></html>"     <-- (optional)
}

Upsert an Push Template

Creates a new template if one does not exist, or updates all templates with the specified client template Id.

Sample JSON body:

{
   "clientTemplateId": 112233,
   "name": "Lots of Cats",              <-- (optional)
   "messages": "Rank These Cats",           <-- (optional)
}

Campaigns 

Create Campaign

Creates and schedules a blast campaign up to 2 weeks in advance. The campaign will have a new template with a new template ID. If 'sendAt' field is not included, message will be sent immediately.

Sample JSON Body:

{
  "name": "Sample API Blast Campaign",
  "listIds": [5925, 6094],       <-- (optional)
  "templateId": 28533,
  "suppressionListIds": [6095],       <-- (optional)
  "sendAt": "2015-09-15 00:00:00"       <-- (optional)
}

Get Campaigns

Gets info such as id, createdAt time, name, templateId, etc. from campaigns.

Sample response:

{
   "campaigns": [{
      "id": 59530,
      "createdAt": 1475452500507,
      "updatedAt": 1475452500591,
      "startAt": 1475535300000,
      "endedAt": 1475542440016,
      "name": "Recurring | 2016-10-02 | Pre-Make a campaign ahead of time",
      "templateId": 93661,
      "createdByUserId": "jeremy@iterable.com",
      "campaignState": "Finished",
      "listIds": [16182],
      "suppressionListIds": [],
      "sendSize": 3
   }, {
      "id": 59355,
      "createdAt": 1475265000217,
      "updatedAt": 1475265000276,
      "startAt": 1475265000274,
      "endedAt": 1475265000320,
      "name": "Recurring | 2016-09-30 | Recurring - Jeremy's List",
      "templateId": 93419,
      "createdByUserId": "jeremy@iterable.com",
      "campaignState": "Finished",
      "listIds": [14007],
      "suppressionListIds": [],
      "sendSize": 3
   }]
}

Get Child Campaigns

Get details for campaigns generated by a recurring campaign.

Sample:

https://api.iterable.com:443/api/campaigns/recurring/12345/childCampaigns&api_key=[API_KEY]

Campaign Metrics

Gets analytic info such as id, bounces, clicks, conversions, purchases, etc. from a campaign. A start and end date can be added to select the desired range of analytics.

Sample response:

id,bounces,clicks,conversions,opens,purchases,pushBounces,pushOpens,pushSent,pushUninstalls,revenue,sent,smsBounces,smsReceived,smsSent,spams,totalClicks,totalOpens,totalPushOpens,unsubs 59355,0,0,,0,0,,,,,0.0,3,,,,0,0,0,,0

Commerce

Update Cart

Updates shoppingCartItems field on the user profile. Fields in bold are required.

Note: We recommend casting the required price field as a double instead of a long. To do that, you will need to include a number with a decimal in the first call that you use to cast that field. Use a non-zero decimal value to cast the field as a double (example: 5.55). Otherwise, the field will be cast as a long.

Sample JSON Body:

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

Track Purchase

Tracks when a user makes a purchase. Also clears shoppingCartItems on the user profile. Adding in the campaignId will attribute the purchase to specific Iterable campaign. Fields in bold are required.

Note: As mentioned above, we recommend casting the required price and total fields as doubles instead of longs. To do that, you will need to include a number with a decimal in the first call that you use to cast that field.Use a non-zero decimal value to cast the field as a double (example: 5.55). Otherwise, the field will be cast as a long.

Sample JSON Body:

{
   "user": {
      "email": "sherry@iterable.com",
      "dataFields": {
         "totalPurchases": 5
      },
      "userId": "1"
   },
   "items": [{
      "id": "1",
      "sku": "1",
      "name": "Iterable Stickers",
      "description": "Put these stickers anywhere and everywhere!",
      "categories": ["stickers", "novelty"],
      "price": 5.50,
      "quantity": 2,
      "imageUrl": "http://static.iterable.com/iterable-demo-v1/15-03-04-Iterable_stickers.jpg",
      "url": "iterable.com"
   }],
   "campaignId": 14348,
   "templateId": 29592,
   "total": 11,
   "dataFields": {
      "shippingAddress1": "360 3rd Street",
      "shippingAddress2": "Suite 675",
      "city": "San Francisco",
      "state": "CA",
      "zip": 94107
   }
}

Email

Target User

Sends a triggered email campaign to specified email address. If 'sendAt' field is not included, message will be sent immediately.

Sample JSON body:

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

View In Browser

View a copy of a previously sent email. Must include both a user’s email address and the message Id of the sent email.

Sample:

https://api.iterable.com:443/api/email/viewInBrowser?email=jeremy%40iterable.com&messageId=340c333dea5e43cea6de24170d8a81c8&api_key=[API_KEY]

Export 

Export Data (CSV)

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

Export Data (JSON)

Exports different types of data (purchases, user created, email sends, email opens, etc) in json format.

Sample response:

{
   {
      "contentId": 243307,
      "recurringCampaignId": 41777,
      "email": "exampleEmail@iterable.com",
      "createdAt": "2016-07-08 19:50:00 +00:00",
      "campaignId": 43521,
      "templateId": 71213
   }
   {
      "contentId": 242909,
      "email": "exampleEmail@iterable.com",
      "createdAt": "2016-07-08 16:58:19 +00:00",
      "campaignId": 43444,
      "templateId": 71115
   }
   {
      "contentId": 243307,
      "recurringCampaignId": 41777,
      "email": "exampleEmail+1@iterable.com",
      "createdAt": "2016-07-08 19:50:00 +00:00",
      "campaignId": 43521,
      "templateId": 71213
   }
   {
      "contentId": 243307,
      "recurringCampaignId": 41777,
      "email": "exampleEmail@iterable.com",
      "createdAt": "2016-07-08 19:50:00 +00:00",
      "campaignId": 43521,
      "templateId": 71213
   }
}

Notes:

The range field will pull information based off of the profile update field

Workflows

Trigger Workflow

Triggers a workflow for a single user and/or all users on a list. Works for both standard and dynamic lists.

Sample JSON Body:

{
   "email": "jeremy@iterable.com",
   "workflowId": 2765,
   "listId": 6094,
   "dataFields": {
      "signupSource": "google",
      "optIn": true
   }
}