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
- List APIs
- Subscription APIs
- Events APIs
- User APIs
- Push APIs
- In-app message APIs
- Experiment APIs
- SMS APIs
- Message type APIs
- Channel APIs
- Template APIs
- Campaign APIs
- Commerce APIs
- Email APIs
- Export APIs
- Workflow APIs
-
Catalog APIs
- Create a catalog
- Get catalog names
- Delete a catalog
- Bulk create catalog items
- Get the catalog items for a catalog
- Get a specific catalog item
- Create or replace a catalog item
- Create or update a catalog item
- Delete a catalog item
- Bulk delete catalog items
- Get field mappings (data types) for a catalog
- Set a catalog's field mappings (data types)
- Further reading
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.
List APIs
Add subscribers to list
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
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
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
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
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
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 type12345:
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 type12345
: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, useaction=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
andsupport@iterable.com
to message type12345
: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
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
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.
NOTE
An id
value must:
- Contain only alphanumeric characters and hyphens.
- Be no longer than 512 bytes in length.
- Be unique across all custom events in the project.
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
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.
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.
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.
NOTE
This endpoint will overwrite existing subscription preferences if fields are set and not null.
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
Updates a user's email address. If the new email already exists in Iterable, 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).
NOTES
- All profile data and events will be migrated to the new email address.
- Either
email
oruserId
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
- Do not use this endpoint for time-sensitive user updates, as there may be a delay before the updates are completely processed (because of high request volume).
- A single request must contain less than 4MB of data (roughly 1000 users).
- You can use this API to update a user's
emailListIds
,unsubscribedChannelIds
andsubscribedMessageTypeIds
arrays only if your project or account does not yet have the opt-in message types feature enabled. Assuming that's the case, using this API to update any of these arrays:- Does not generate unsubscribe events.
- Completely overwrites the value for that array (Iterable treats the array provided in the request body as the completely representation of that array). Iterable will not modify any array not included in the request.
- You must provide either
email
oruserId
(but not both). - To create a new user based on
userId
instead of email, provide auserId
and setpreferUserId
totrue
.
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.
NOTE
This endpoint will overwrite existing subscription preferences if fields are
set and not null. Either email
or userId
is required.
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
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
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 their historic campaign metrics as well.
Sample:
https://api.iterable.com:443/api/users/docs%40iterable.com?api_key=YOUR_API_KEY
Get a user
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
.
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=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
Updates a user profile with new data fields. Missing fields are not deleted and new data is merged.
NOTES
- You must include either
email
oruserId
- If you set
mergeNestedObjects
totrue
, the API will merge top-level object data instead of overwriting it (defaults tofalse
).- For example, given a user profile with data
{"mySettings":{"mobile":true}}
and an API request with data{"mySettings":{"email":true}}
, settingmergeNestedObjects
totrue
would result in a user profile with data{"mySettings":{"mobile":true,"email":true}}
. - Setting
mergeNstedObjects
tofalse
for the same user profile and request would result in a user profile with data{"mySettings":{"email":true}}
.
- For example, given a user profile with data
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
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
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
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. Since a message's read status is local to a mobile device, there is not currently a way to differentiate between the two.
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
Cancel in-app message to user
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
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 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
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
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
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
IMPORTANT
Iterable's various template APIs allow you to read and update base templates, campaign templates and workflow templates. These APIs are not restricted to base templates—they can also be used to read and update templates associated with blast campaigns, triggered campaigns and workflow campaigns (changing their content for future sends). For descriptions of these APIs, read the API documentation.
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
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=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 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 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 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:
NOTE
This call will not work on templates made with the Drag-and-Drop Editor.
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
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
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
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
Updates shoppingCartItems
field on the user profile.
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 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": "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" } ] }
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.
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.
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.
NOTE
An id
value must:
- Contain only alphanumeric characters and hyphens.
- Be no longer than 512 bytes in length.
- Be unique across all purchase events in the project.
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": "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 } }
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
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
.
NOTE
This is an asynchronous call; a 200 response means that the request has been received, not that the email has been sent.
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
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)
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 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 } }
NOTE
The range field will pull information based off of the profile update field.
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
NOTE
Contact your Iterable CSM to discuss adding Catalog to your plan.
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
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
andpageSize
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
andnextPageUrl
values (as applicable). Use these to load more data.If you specify a
page
andpageSize
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
andpageSize
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
andnextPageUrl
values (as applicable). Use these to load more data.If you specify a
page
andpageSize
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 theprice
field (set to45000
).
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
andstring
-
previousOwner
is an object containing afirstName
field and alastName
field. All three fields come back in thedefinedMappings
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 afirstName
field and alastName
field. The above request body specifies thatpreviousOwner
is an object while its children,firstName
andlastName
, are strings. - It is not possible to define types for nested object fields.
- Allowed types include:
boolean
,date
,geo_location
,long
,double
,object
andstring
- 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.
Comments
0 comments
Please sign in to leave a comment.