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.

# Table of contents

# Getting started

Before getting started with Iterable's API, note the following:

• To learn how to create API keys and use them to authenticate with Iterable's API, read API Keys.
• To learn more about Iterable's API and experiment with its endpoints, visit the API documentation.
• The base URI for Iterable's API is https://api.iterable.com.
• Iterable may occasionally add fields to API response bodies as needed. Be sure that any dependencies you have on these APIs will not break if and when these new fields are added.
• Iterable will not rename or remove existing, documented fields from an API response body without prior communication.

# TLS 1.2

All calls to Iterable's API should support TLS 1.2. Starting October 22, 2021, API calls that do not support TLS 1.2 will fail. For more information, see our release notes from September 22, 2021.

# List APIs

# Add subscribers to list

POST /api/lists/subscribe

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

Sample JSON request body:

{
    "listId": 123,
    "subscribers": [
        {
            "email": "docs@iterable.com",
            "dataFields": {
                "firstName": "Sherry",
                "hasCat": true
            },
            "userId": "1"
        }
    ]
} 

Optional fields: on each item in the subscribers array, optional fields include email or userId (but not both), dataFields, preferUserId and mergeNestedObjects.

# Delete static list

DELETE /api/lists/{listId}

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 request:

https://api.iterable.com:443/api/lists/21398?api_key=YOUR_API_KEY

# Remove users from list

POST /api/lists/unsubscribe

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

Sample JSON request body:

{
    "listId": 1,
    "subscribers": [
        {
            "email": "docs@iterable.com"
        },
        {
            "email": "docs+2@iterable.com"
        }
    ],
    "campaignId": 123,
    "channelUnsubscribe": false
}

Optional fields: campaignId, channelUnsubscribe. On each item in the subscribers array, optional fields include email or userId (but not both).

# Get users in list

GET /api/lists/getUsers

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

Sample:

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

# Get lists from project

GET /api/lists

This will return all the static lists in a project.

Sample:

https://api.iterable.com:443/api/lists?api_key=YOUR_API_KEY

# Create static list

POST /api/lists

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 request body:

{
    "name": "exampleListName"
}

# Subscription APIs

# Subscribe a user to a single channel, message type or list

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

• For subscriptionGroup, provide one of the following values:

  • messageChannel
  • messageType
  • emailList

• For subscriptionGroupId, provide the ID of the message channel, message type or email list to which you are subscribing the user.

• For userEmail, provide the email address of the user for which you'd like to create a subscription.

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

• For example, the following call subscribes user docs@iterable.com to message type 12345:

  PATCH https://api.iterable.com/api/subscriptions/messageType/12345/user/docs%40iterable.com&api_key=YOUR_API_KEY

# Unsubscribe a user from a single channel, message type or list

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

• For subscriptionGroup, provide one of the following values:

  • messageChannel
  • messageType
  • emailList

• For subscriptionGroupId, provide the ID of the message channel, message type or email list from which you are unsubscribing the user.

• For userEmail, provide the email address of the user from which you are unsubscribing the user.

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

• For example, the following call unsubscribes user docs@iterable.com to message type 12345:

  DELETE https://api.iterable.com/api/subscriptions/messageType/12345/user/docs%40iterable.com&api_key=YOUR_API_KEY

# Subscribe or unsubscribe multiple users to the same channel, message type or list

PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}?action=subscribe

• To subscribe multiple users to the same channel, message type or list, use action=subscribe (as shown in the above URL). To unsubscribe, use action=unsubscribe.

• For subscriptionGroup, provide one of the following values:

  • messageChannel
  • messageType
  • emailList

• For subscriptionGroupId, provide the ID of the message channel, message type or email list to which you are subscribing the users.

• For the JSON request body, provide a users array containing the email addresses of the users to subscribe.

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

• For example, the following request subscribes docs@iterable.com and support@iterable.com to message type 12345:

  PUT https://api.iterable.com/api/subscriptions/messageType/12345?action=subscribe&api_key=YOUR_API_KEY

  Request body:

  {
     "users": [ 
        "docs@iterable.com",
        "support@iterable.com"
     ]
  }
  

# Events APIs

# Get events associated with a user

GET /api/events/{email}

Use this to receive events associated with a user profile. This will include custom events and standard Iterable 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/docs%40iterable.com?api_key=YOUR_API_KEY

Sample JSON response:

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

# Track event

POST /api/events/track

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 tracking custom conversions 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. 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 request body:

{
    "email": "docs@iterable.com",
    "eventName": "startedMembership",
    "id": "12345",
    "dataFields": {
        "source": "facebook",
        "membershipType": "monthly"
    },
    "userId": "1",
    "campaignId": 123,
    "templateId": 123
}

Optional fields: email or userId (but not both), id, createdAt, dataFields, campaignId and templateId.

# Bulk track events

POST /api/events/trackBulk

Tracks multiple custom events. Either email or userId is required for each event. Empty event names are not allowed.

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

Limitations:

• Rate limit: 10 requests/second, per project.
• An Iterable project can contain up to 8,000 unique custom event field names. If the same field name is used on various custom events that have different eventName values, it counts multiple times against this limit.
• Types of data fields must match the types sent in previous requests, across all data fields in the project (for the same event name).
• Bulk events are processed separately from regular event track endpoint.
• There's a 4MB limit for the request's JSON body (about 1000 events).
• Fields per event are the same as for single event in regular track event endpoint.

Sample JSON request body:

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

Optional fields: On each object in the events array, optional fields include email or userId (but not both), id, createdAt, dataFields, campaignId, and templateId.

# Track push open

POST /api/events/trackPushOpen

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 sending push notifications with Iterable.

Sample JSON request body:

{
    "email": "docs@iterable.com",
    "userId": "2",
    "campaignId": 12345,
    "templateId": 67890,
    "messageId": "01234567890",
    "dataFields": {
        "openedMostRecentPush": true
    }
}

Optional fields: email or userId (but not both), campaignId, templateId, createdAt and dataFields.

# Track in-app message click

POST /api/events/trackInAppClick

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

You must provide either email or userId. If you provide both, email takes precedence.

Sample JSON request body:

{
    "email": "docs@iterable.com",
    "userId": "user123",
    "messageId": "Ddd8cae9adf61A48afab877a58c22Lfa7ab1",
    "clickedUrl": "https://www.iterable.com"
}

Optional fields: email or userId (but not both), clickedUrl, messageContext and deviceInfo. On messageContext, optional fields include saveToInbox, silentInbox and location. On deviceInfo, optional fields include deviceId, platform and appPackageName.

# Consume or delete an in-app message

Consumes or deletes an in-app message from the server.

Use this API if your app does not use one of Iterable's mobile SDKs, since they call it automatically. If an incoming in-app message is not configured to use the mobile inbox, use this API to "consume" it from the server queue after the user sees it. Otherwise, call this API when the user explicitly deletes an inbox-enabled message (by clicking a delete button in its content, swiping it in the inbox, etc.). If you pass a deleteAction value to this endpoint, Iterable generates an inAppDelete event; otherwise, it does not.

POST /api/events/inAppConsume

Sample JSON request body:

{
    "email": "docs@iterable.com",
    "userId": "user123",
    "messageId": "Ddd8cae9adf61A48afab877a58c22Lfa7ab1",
    "deleteAction": "inbox-swipe", 
    "messageContext": {
        "location": "inbox", 
        "saveToInbox" true, 
        "silentInbox": false 
    },
    "deviceInfo": {
        "deviceId": "E628DC81-52AB-4464-B337-C2624E3B293D", 
        "platform": "iOS", 
        "appPackageName": "com.iterable.testapp"
    }
}

Optional fields: email or userId (but not both), messageContext, deleteAction and deviceInfo. On messageContext, optional fields include saveToInbox, silentInbox and location. On deviceInfo, optional fields include deviceId, platform and appPackageName.

# Track in-app message open

POST /api/events/trackInAppOpen

Creates an inAppOpen event for the specified user and message. When not using one of Iterable's mobile SDKs, call this endpoint when a mobile app displays an in-app message to a user.

This endpoint also marks the specified in-app message as having been read.

Sample JSON request body:

{
    "email": "docs@iterable.com",
    "userId": "user123",
    "messageId": "Ddd8cae9adf61A48afab877a58c22Lfa7ab1"
}

Optional fields: email or userId (but not both), messageContext and deviceInfo. On messageContext, optional fields include saveToInbox, silentInbox and location. On deviceInfo, optional fields include deviceId, platform and appPackageName.

# Track in-app message close

POST /api/events/trackInAppClose

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

Sample JSON request body:

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

Optional fields: email or userId (but not both), clickedUrl, messageContext, closeAction and deviceInfo. On messageContext, optional fields include saveToInbox, silentInbox and location. On deviceInfo, optional fields include deviceId, platform and appPackageName.

# Track in-app message delivery

POST /api/events/trackInAppDelivery

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

Sample JSON request body:

{
    "email": "docs@iterable.com",
    "userId": "user123",
    "messageId": "Ddd8cae9adf61A48afab877a58c22Lfa7ab1",
    "messageContext": {
        "saveToInbox": true,
        "silentInbox": true
    },
    "deviceInfo": {
        "deviceId": "E628DC81-52AB-4464-B337-C2624E3B293D",
        "platform": "iOS",
        "appPackageName": "com.iterable.testapp" 
    }
}

Optional fields: email or userId (but not both), messageContext, deviceInfo. On messageContext, optional fields include saveToInbox and silentInbox. On deviceInfo, optional fields include deviceId, platform, and appPackageName.

# User APIs

# Bulk update subscriptions

POST /api/users/bulkUpdateSubscriptions

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

Sample JSON request body:

{
    "updateSubscriptionsRequests": [
        {
            "email": "docs@iterable.com",
            "userId": "0192837821",
            "unsubscribedChannelIds": [
                12345,
                23456
            ],
            "unsubscribedMessageTypeIds": [
                65432
            ],
            "campaignId": 34567,
            "templateId": 456789
        },
        {
            "email": "docs+2@iterable.com",
            "userId": "2131238573",
            "unsubscribedChannelIds": [
                12345
            ],
            "campaignId": 34567,
            "templateId": 456789
        }
    ]
}

Optional fields (for each object in the updateSubscriptionsRequest array): email or userId (but not both), emailListIds, unsubsubscribedChannelIds, unsubscribedMessageTypeIds, subscribedMessageTypeIds, campaignId, templateId

# Update a user's email

POST /api/users/updateEmail

Updates a user's email address. If the new email already exists in Iterable, or if the new email has been forgotten via a GDPR request, an error will occur.

Sample JSON request body:

{
    "currentEmail": "docs+old@iterable.com",
    "currentUserId": "0192837821",
    "newEmail": "docs+new@iterable.com"
}

Optional fields: currentEmail or currentUserId (but not both).

# Bulk update

POST /api/users/bulkUpdate

Updates user profiles for one or more users.

Sample JSON request body:

{
    "users": [
        {
            "email": "docs@iterable.com",
            "userId": "0192837821",
            "dataFields": {
                "favoriteColor": "orange"
            }
        },
        {
            "email": "docs+2@iterable.com",
            "userId": "9281928374",
            "dataFields": {
                "favoriteColor": "blue"
            }
        },
        {
            "userId": "2394029394",
            "preferUserId": true,
            "dataFields": {
                "favoriteColor": "red",
            }
        }

    ]
}

Optional fields (for each object in the users array): email or userId (but not both), dataFields, preferUserId, mergeNestedObjects

# Register device token

POST /api/users/registerDeviceToken

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 sending push notifications with Iterable.

applicationName should usually be the package name of your mobile app, as found in Settings > Mobile Apps.

Sample JSON request body:

{
    "email": "docs@iterable.com",
    "device": {
        "token": "sampleToken123",
        "platform": "APNS",
        "applicationName": "com.example.pizzatracker",
        "dataFields": {
            "phoneType": "iPhone 6 plus"
        }
    },
    "userId": "2"
}

Optional fields: email or userId (but not both), preferUserId. On device, dataFields is optional.

# Update user subscriptions

POST /api/users/updateSubscriptions

Updates a user's subscription settings with new settings.

Sample JSON request body:

{
    "email": "docs@iterable.com",
    "userId": "0192837821",
    "emailListIds": [
        5,
        6,
        7
    ],
    "unsubscribedChannelIds": [
        100
    ],
    "unsubscribedMessageTypeIds": [
        100
    ],
    "campaignId": 123,
    "templateId": 123
}

Optional fields: email or userId (but not both), emailListIds, unsubscribedChannelIds, unsubscribedMessageTypeIds, subscribedMessageTypeIds, campaignId and templateId.

# Get user fields

GET /api/users/getFields

Gets all user fields in a project.

Sample:

https://api.iterable.com:443/api/users/getFields?api_key=YOUR_API_KEY

Sample JSON response:

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

# Delete a user

DELETE /api/users/{email}

Sample:

https://api.iterable.com:443/api/users/docs%40iterable.com?api_key=YOUR_API_KEY

# Get a user

GET /api/users/{email}

Gets user's data fields and info.

Sample:

https://api.iterable.com:443/api/users/docs%40iterable.com?api_key=YOUR_API_KEY

# Delete a user by userID

DELETE /api/users/byUserId/{userId}

Delete a user using userId instead of email.

Sample:

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

# Get a user by userId

GET /api/users/byUserId/{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=YOUR_API_KEY

# User update

POST /api/users/update

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

Sample JSON request body:

{
    "email": "docs@iterable.com",
    "dataFields": {
        "catName": "Jimmy"
    },
    "userId": "1",
    "mergeNestedObjects": true
}

Optional fields: email or userId (but not both), dataFields, preferUserId, and mergeNestedObjects.

# Get sent messages

GET /api/users/getSentMessages

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

campaignId, excludeBlastCampaigns, startDateTime and endDateTime are all optional.

Sample:

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

Sample JSON response:

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

# Disable device

POST /api/users/disableDevice

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

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 request body:

{
    "token": "sampleToken123",
    "email": "docs@iterable.com",
    "userId": "2"
 }

Optional fields: email or userId (but not both).

# Push APIs

# Target user

POST /api/push/target

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 request body:

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

Optional fields: dataFields, sendAt, allowRepeatMarketingSends and metadata.

# In-app message APIs

# Get in-app messages for user

GET /api/inApp/getMessages

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

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

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

Sample request:

https://api.iterable.com:443/api/inApp/getMessages?email=docs%40iterable.com&userId=1234&count=123&api_key=YOUR_API_KEY

Sample JSON response:

{
 "inAppMessages": [
   {
     "messageId": "e0c25a24ff624c9e824e77253e7d9f77e0c25a24ff624",
     "campaignId": 1234567,
     "createdAt": 1611730824106,
     "expiresAt": 1619506824106,
     "content": {
       "html": "...",
       "payload": {},
       "inAppDisplaySettings": {...},
     "customPayload": {},
     "trigger": {
       "type": "immediate"
     },
     "saveToInbox": false,
     "priorityLevel": 400.5
   }
 ]
}

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

• Proof: 100.0
• Critical: 100.5
• High: 200.5
• Medium: 300.5
• Low: 400.5

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

# Cancel in-app message to user

POST /api/inApp/cancel

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

Sample JSON body:

{
    "email": "docs@iterable.com",
    "campaignId": 13770
}

# Send in-app message to user

GET /api/inApp/target

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

Sample JSON body:

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

Optional fields: dataFields, sendAt and allowRepeatMarketingSends.

# Experiment APIs

# Get experiment metrics

GET /api/experiments/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=YOUR_API_KEY

# SMS APIs

# Target user

POST /api/sms/target

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 request body:

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

Optional fields: dataFields, sendAt and allowRepeatMarketingSends.

# Message type APIs

# Get message types

GET /api/messageTypes

Lists all message types for that project.

Sample JSON response:

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

# Channel APIs

# Get channels

GET /api/channels

Lists all channels for that project.

Sample JSON response:

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

# Template APIs

# Update SMS template

POST /api/templates/sms/update

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

Sample JSON request body:

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

Optional fields: createdAt, updatedAt, name, message, locale, messageTypeId, imageUrl, clientTemplateId and campaignId.

# Get templates in a project

GET /api/templates

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

Sample:

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

Sample JSON response:

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

# Update push template

POST /api/templates/push/update

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

Sample JSON request body:

{
    "templateId": 0,
    "name": "string",
    "title": "string",
    "message": "string",
    "payload": {},
    "badge": "string",
    "locale": {
        "name": "string"
    },
    "messageTypeId": 0,
    "sound": "string",
    "deeplink": {
        "ios": "string",
        "android": "string"
    },
    "clientTemplateId": "string",
    "campaignId": 0
}

Optional fields: createdAt, updatedAt, name, title, message, payload, badge, locale, messageTypeId, sound, deeplink, clientTemplateId, and campaignId. On deeplink, optional fields include ios and android.

# Get an email template

GET /api/templates/email/get

Get an email template's information and HTML.

Sample JSON response:

{
    "templateId": 86596,
    "name": "My name of template",
    "fromName": "Customer Success",
    "fromEmail": "docs@iterable.com",
    "replyToEmail": "docs+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": "docs@iterable.com"
}

# Upsert an SMS template

POST /api/templates/sms/upsert

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

Sample JSON request body:

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

Optional fields: name, fromName, fromEmail, replyToEmail, subject, preheaderText, ccEmails, bccEmails, html, plainText, googleAnalyticsCampaignName, linkParams, dataFeedId, dataFeedIds, cacheDataFeed, mergeDataFeedContext, locale, messagetypeId, and creatorUserId.

# Get an SMS template

GET /api/templates/sms/get

Get an SMS template information and message string.

Sample JSON response:

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

# Get a push template

GET /api/templates/push/get

Get a push template information and message string.

Sample JSON response:

{
    "templateId": 0,
    "createdAt": "2019-02-07T07:30:56.741Z",
    "updatedAt": "2019-02-07T07:30:56.741Z",
    "name": "string",
    "title": "string",
    "message": "string",
    "payload": {},
    "badge": "string",
    "locale": {
        "name": "string"
    },
    "messageTypeId": 0,
    "sound": "string",
    "deeplink": {
        "ios": "string",
        "android": "string"
    },
    "clientTemplateId": "string",
    "campaignId": 0
}

# Get an email template from a client template id

GET /api/templates/getByClientTemplateId

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

# Update email template

POST /api/templates/email/update

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

Template before update:

Sample JSON request body:

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

Optional fields: metadata, name, fromName, fromEmail, replyToEmail, subject, preheaderText, ccEmails, bccEmails, html, plainText, googleAnalyticsCampaignName, linkParams, dataFeedId, dataFeedIds, cacheDataFeed, mergeDataFeedContext, clientTemplateId, locale, messageTypeId, creatorUserId. On metadata, optional fields include campaignId and clientTemplateId.

Template after update:

# Upsert an email template

POST /api/templates/email/upsert

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

Sample JSON request body:

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

Optional fields: name, fromName, fromEmail, replyToEmail, subject, preheaderText, ccEmails, bccEmails, html, plainText, googleAnalyticsCampaignName, linkParams, dataFeedId, dataFeedIds, cacheDataFeed, mergeDataFeedContext, clientTemplateId, locale, messageTypeId and creatorUserId.

# Create a push template

POST /api/templates/push/upsert

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

Sample JSON request body:

{
    "clientTemplateId": 112233,
    "name": "Lots of Cats",
    "messages": "Rank These Cats",
}

Optional fields: name, title, message, payload, badge, locale, messageTypeId, sound, deeplink and creatorUserId.

# Campaign APIs

# Create campaign

POST /api/campaigns/create

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

Sample JSON request body:

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

Optional fields: suppressionListIds, sendAt, sendMode, startTimeZone, defaultTimeZone and dataFields.

# Get campaigns

GET /api/campaigns

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

Sample JSON response:

{
    "campaigns": [
        {
            "id": 59530,
            "createdAt": 1475452500507,
            "updatedAt": 1475452500591,
            "startAt": 1475535300000,
            "endedAt": 1475542440016,
            "name": "Recurring | 2016-10-02 | Pre-Make a campaign ahead of time",
            "templateId": 93661,
            "createdByUserId": "docs@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": "docs@iterable.com",
            "campaignState": "Finished",
            "listIds": [
                14007
            ],
            "suppressionListIds": [],
            "sendSize": 3
        }
    ]
}

# Get child campaigns

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

Get details for campaigns generated by a recurring campaign.

Sample:

https://api.iterable.com:443/api/campaigns/recurring/12345/childCampaigns&api_key=YOUR_API_KEY

# Campaign metrics

GET /api/campaigns/metrics

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

Sample CSV response:

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

# Commerce APIs

# Update cart

POST /api/commerce/updateCart

Updates shoppingCartItems field on the user profile.

Sample JSON request body:

{
    "user": {
        "email": "docs@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": "https://static.iterable.com/iterable/15-10-03-iterableshirt.png",
            "url": "iterable.com"
        },
        {
            "id": "3",
            "sku": "5",
            "name": "Macadamia Nuts",
            "description": "Full of healthy fats! Made in Hawaii.",
            "categories": [
                "food"
            ],
            "price": 5.50,
            "quantity": 2,
            "imageUrl": "https://nuts.com/images/auto/510x340/assets/4d57de389a2f6d59.jpg",
            "url": "iterable.com"
        }
    ]
}

Optional fields: On the user object, optional fields include email or userId (but not both), dataFields, preferUserId and mergeNestedObjects. On each item in the items array, optional fields include sku, description, categories, imageUrl, url and dataFields.

# Track purchase

POST /api/commerce/trackPurchase

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.

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

Sample JSON request body:

{
    "user": {
        "email": "docs@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": "https://static.iterable.com/iterable-demo-v1/15-03-04-Iterable_stickers.jpg",
            "url": "iterable.com"
        }
    ],
    "campaignId": 14348,
    "templateId": 29592,
    "total": 11,
    "dataFields": {
        "shippingAddress1": "360 3rd Street",
        "shippingAddress2": "Suite 675",
        "city": "San Francisco",
        "state": "CA",
        "zip": 94107
    }
}

Optional fields: id, campaignId, templateId, createdAt and dataFields. On user, optional fields include email or userId (but not both), dataFields, preferUserId and mergeNestedObjects. On each item in the items array, optional fields include sku, description, categories, imageUrl, url and dataFields.

# Email APIs

# Target user

POST /api/email/target

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

Sample JSON request body:

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

Optional fields: dataFields, sendAt, allowRepeatMarketingSends and metadata.

# View in browser

GET /api/email/viewInBrowser

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

Sample:

https://api.iterable.com:443/api/email/viewInBrowser?email=docs%40iterable.com&messageId=340c333dea5e43cea6de24170d8a81c8&api_key=YOUR_API_KEY

# Export APIs

# Export data (CSV)

GET /api/export/data.csv

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

# Export data (JSON)

GET /api/export/data.json

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

Sample JSON response:

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

# Workflow APIs

# Trigger workflow

POST /api/workflows/triggerWorkflow

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

Sample request body (JSON):

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

Optional fields: email or listId (but not both), and dataFields.

# Catalog APIs

# Create a catalog

POST /api/catalogs/{catalogName}

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

Example:

POST https://api.iterable.com/api/catalogs/Trucks?api_key=YOUR_API_KEY

Sample JSON response body:

{
    "msg": "",
    "code": "Success",
    "params": {
        "id": 740,
        "name": "Trucks",
        "url": "/api/catalogs/Trucks?api_key=YOUR_API_KEY"
    }
}

On success, this API returns HTTP status code 201.

# Get catalog names

GET /api/catalogs

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

Example:

GET https://api.iterable.com/api/catalogs?api_key=YOUR_API_KEY

Paging:

• Use page and pageSize in the query string to specify a page number and page size. For example:

  GET https://api.iterable.com/api/catalogs?api_key=YOUR_API_KEY&page=3&pageSize=10

• When passing these parameters, the API will return previousPageUrl and nextPageUrl values (as applicable). Use these to load more data.

• If you specify a page and pageSize combination outside the range of available data, the API will return an empty list of catalog names.

Sample JSON response body:

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

On success, this API returns HTTP status code 200.

# Delete a catalog

DELETE /api/catalogs/{catalogName}

Deletes a catalog and all its items.

Example:

DELETE https://api.iterable.com/api/catalogs/Trucks?api_key=YOUR_API_KEY

Sample JSON response body:

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

On success, this API returns HTTP status code 200.

# Bulk create catalog items

POST /api/catalogs/{catalogName}/items

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

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

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

If the catalog already contains an item having the same ID as one provided in the request body, the existing item will be completely overwritten by the item specified in the request body Do not use the period character in catalog item field names.

Example:

POST https://api.iterable.com/api/catalogs/Trucks/items?api_key=YOUR_API_KEY

Request headers:

• Content-Type: application/json

Sample JSON request body:

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

Sample JSON response body:

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

On success, this API returns HTTP status code 202.

# Get the catalog items for a catalog

GET /api/catalogs/{catalogName}/items

Lists all catalog items in a catalog.

Example:

GET https://api.iterable.com/api/catalogs/Trucks/items?api_key=YOUR_API_KEY

Paging:

• Use page and pageSize in the query string to specify a page number and page size. For example:

  GET https://api.iterable.com/api/catalogs/Trucks/items?api_key=YOUR_API_KEY&page=3&pageSize=10

• When passing these parameters, the API will return previousPageUrl and nextPageUrl values (as applicable). Use these to load more data.

• If you specify a page and pageSize combination outside the range of available data, the API will return an empty list of catalog names.

Sample JSON response body:

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

On success, this API returns HTTP status code 200.

# Get a specific catalog item

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

Gets the details of a specific catalog item.

Example:

GET https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckA?api_key=YOUR_API_KEY

Sample JSON response body:

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

On success, this API returns HTTP status code 200.

# Create or replace a catalog item

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

Writes over (or creates) a catalog item with the values found in the request body. Any already-existing fields not included in the request body will be deleted. This is an asynchronous call; 202 response code indicates that the request has been received and will be processed.

If the item specified in the URL does not exist, it will be created.

A catalog item ID may contain letters, numbers, and dashes (no spaces, underscores or other special characters), must be unique, and can contain no more than 255 characters.

Example:

PUT https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckA?api_key=YOUR_API_KEY

Request headers:

• Content-Type: application/json

Sample JSON request body:

{
    "value": {
        "used": false
    }
}

Sample JSON response body:

{
    "msg": "",
    "code": "Success",
    "params": {
        "catalogName": "Trucks",
        "itemId": "PickupTruckA",
        "url": "/api/catalogs/Trucks/items/PickupTruckA?api_key=YOUR_API_KEY"
    }
}

On success, this API returns HTTP status code 202.

# Create or update a catalog item

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

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

Example:

PATCH https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckB?api_key=YOUR_API_KEY

Request headers:

• Content-Type: application/json

Sample JSON request body:

{
    "update": {
        "price": 45000
    }
}

• This request will update the `price field on the catalog item in question, but it will leave all other fields on that catalog item as is.
• Do not use the period character in catalog item field names.
• This request will overwrite every one of the fields on PickupTruckA, leaving nothing except the price field (set to 45000).

Sample JSON response body:

{
    "msg": "",
    "code": "Success",
    "params": {
        "catalogName": "Trucks",
        "itemId": "PickupTruckB",
        "url": "/api/catalogs/Trucks/items/PickupTruckB?api_key=YOUR_API_KEY"
    }
}

On success, this API returns HTTP status code 202.

# Delete a catalog item

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

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

Example:

DELETE https://api.iterable.com/api/catalogs/Trucks/items/PickupTruckA?api_key=YOUR_API_KEY

Sample JSON response body:

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

On success, this API returns HTTP status code 202.

# Bulk delete catalog items

DELETE /api/catalogs/{catalogName}/items

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

Example:

DELETE https://api.iterable.com/api/catalogs/Trucks/items?api_key=YOUR_API_KEY

Request headers:

• Content-Type: application/json

Sample JSON request body:

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

Sample JSON response body:

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

On success, this API returns HTTP status code 202.

# Get field mappings (data types) for a catalog

GET /api/catalogs/{catalogName}/fieldMappings

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

Example:

GET https://api.iterable.com/api/catalogs/Trucks/fieldMappings?api_key=YOUR_API_KEY

Sample JSON response body (no field types defined):

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

Sample JSON response body (many field types defined):

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

• Types include: boolean, date, geo_location, long, double, object and string
• previousOwner is an object containing a firstName field and a lastName field. All three fields come back in the definedMappings field if their data types have been assigned.

On success, this API returns HTTP status code 200.

# Set a catalog's field mappings (data types)

PUT /api/catalogs/{catalogName}/fieldMappings

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

Example:

PUT https://api.iterable.com/api/catalogs/Trucks/fieldMappings?api_key=YOUR_API_KEY

Request headers:

• Content-Type: application/json

Sample JSON request body:

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

Optional fields: On each item in the mappingsUpdates array, the children field is optional.

• previousOwner is an object containing a firstName field and a lastName field. The above request body specifies that previousOwner is an object while its children, firstName and lastName, are strings.
• It is not possible to define types for nested object fields.
• Allowed types include: boolean, date, geo_location, long, double, object and string
• For a catalog collection to search previously uploaded data containing the newly typed fields (using the API or the web interface), you must re-upload or re-create that data.

Sample JSON response body:

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

On success, this API returns HTTP status code 200.

# Further reading

• API Keys
• API documentation