Overview
This document describes how to use the Optimove API to retrieve data from Optimove, to add information into the system and to instruct Optimove to execute actions. This Overview section presents a list of all available function calls. Before using the API, it is recommended to read the General Information section of this page and the accompanying Optimove API: Getting Started.
Refer to Optimove's API GitHub repository for code examples and use cases.
General Functions
Login
Returns the authentication token required for all other functions during a particular session
Authentication Using API Keys
API requests can be also authenticated using an API key, using the key as a property in the request header.
GetLastDataUpdate
Returns the date of the most recently available customer data
RegisterEventListener
Specifies the URL of a listener to which Optimove will report events of the specified type (e.g., "campaign scheduled")
UnregisterEventListener
Informs Optimove to stop reporting events of the specified type
GetRegisteredEventListeners
Retrieve a list of all currently registered event listeners
Model-related Functions
GetCustomerAttributeList
Returns an array containing all the available customer attribute names and a description of each
GetLifecycleStageList
Returns a list of all available lifecycle stages
GetMicrosegmentList
Returns an array containing the details of all microsegments.
GetMicrosegmentChangers
Returns an array of customer IDs, and their before and after micro-segment IDs, for customers whose micro-segment changed during the last day for which data is available
Action-related Functions
GetActionName
Returns the action name associated with a particular action ID
GetActionID
Returns the action ID associated with a particular action name
GetAllActions
Returns an array of all defined action IDs and names
GetActionsByTargetGroup
Returns the list of recipient group IDs and action IDs associated with a particular target group on a particular date
GetPromoCodes
Returns an array of target group IDs, recipient group IDs, action IDs and promo codes for a particular date
GetPromoCodesByCampaign
Returns an array of recipient group IDs, action IDs and promo codes associated with a given Campaign ID
GetPromoCodesByTargetGroup
Returns an array of recipient group IDs, action IDs and promo codes associated with a given target group on a given date
GetActionDetailsByTargetGroup
Returns an array of recipient group IDs, action IDs, action duration, lead time and the execution channels associated with a given target group on a particular date
GetExecutedCampaignDetails
Returns an array of all details of all campaigns executed on a particular date
GetCampaignDetails
Returns the details of a particular campaign
GetExecutionChannels
Returns the list of the available execution channel IDs and associated channel names
GetExecutedCampaignChannelDetails
Returns the details of a particular channel used in a particular executed campaign
GetExecutedCampaignsByChannel
Returns the list of campaigns executed for a particular channel on a particular date
Target Group-related Functions
GetTargetGroupName
Returns the target group name associated with a particular target group ID
GetTargetGroupID
Returns the target group ID associated with a particular target group name
GetTargetGroupsByDate
Returns the list of target group IDs for which an action was executed on a particular date
GetTargetGroupDetails
Returns an array of IDs, names, and priorities for all defined target groups
Customer-related Functions
AddCustomerAttribute
Adds new customer attributes
GetCustomersByAction
Returns the list of customer IDs associated with a particular recipient group and action on a particular date
GetCustomerActionsByTargetGroup
Returns an array of all customer IDs, action IDs and channel IDs associated with a particular target group ID and date
GetCustomerOneTimeActionsByDate
Returns a list of customers and the details of the marketing actions they received as part of one-time campaigns executed on a particular date
GetCustomerOneTimeActionsByCampaign
Returns a list of customers and the details associated with a particular one-time campaign
GetCustomerAttributeChangers
Returns an array of customer IDs, and their before and after attribute values, for customers whose selected attribute changed from the past period to the current one
GetCustomerFutureValues
Returns an array of customer IDs and the future value of each
GetCustomerLastActionExecuted
Returns the action ID, execution date, action duration, and target group ID for the last action run for a particular customer ID
GetCustomerActionDetailsByDate
Returns an array of customer IDs and associated recipient group IDs, action IDs and channel IDs for a particular date
GetCustomersActionEndedByDate
Returns an array of customer IDs and associated action IDs, channel IDs, execution dates, action durations, and target group IDs whose action durations ended on a particular date
GetCustomerSendDetailsByCampaign
Returns an array of all customer IDs, channel IDs, template IDs, send times and channel send IDs for a particular campaign ID
GetCustomerExecutionDetailsByCampaign
Returns an array of all customer IDs and the details associated with each customer for a particular campaign ID
GetCustomerSendDetailsByChannel
Returns an array of all customer IDs, template IDs, send times and customer attributes for a particular combination of channel ID and campaign ID
GetProcessedCampaignCustomers
Returns an array of all customer IDs and associated promotion codes for a particular campaign ID.
GetCurrentlyTargetedCustomers
Returns an array of all customer IDs currently included in one or more campaigns
GetCanceledCampaignCustomers
Returns an array of all customer IDs that had been included in a campaign that was canceled, along with their associated action IDs and promo codes
GetCustomerProductDetailsByCampaign
Returns an array of customer IDs and recommended Product IDs for each customer targeted by a particular product recommendation campaign
GetCustomerProductDetailsByDate
Returns an array of customer IDs and recommended Product IDs for each customer targeted by any product recommendation campaign on a particular date
GetCustomerProductRecommendations
Returns product recommendations (replenishment or recommendation) generated for customers by Optimove
GetCampaignInteractionCustomers
Returns an array of Customer IDs and associated details for each customer who performed a particular interaction (generated a particular event) via a particular channel on a particular date
GetCustomerChannelInteractions
Returns the details of a particular customer’s interactions with campaigns sent during a particular date range
GetCustomersActivityEventAttributes
Returns an array of all customer IDs that triggered a particular SDK event on a particular date, along with associated details
UpdateCustomerAttributes
Updates attribute values for particular customer IDs
RemoveCustomerPII
Causes Optimove to delete all personally identifiable information associated with specified customer IDs
Value Segment-related Functions
GetValueSegmentName
Returns the value segment name associated with a particular value segment ID
GetValueSegmentID
Returns the value segment ID associated with a particular value segment name
GetValueSegments
Returns an array of all defined value segment IDs and their associated names
GetCustomersByValueSegment
Returns the list of customer IDs associated with a particular value segment at the current time
GetValueSegmentChangers
Returns an array of customer IDs, and their before and after value segment IDs, for customers whose value segment changed
External System Integration Functions
AddPromotions
Adds promo codes and associated names that will be available for selection when running a campaign
GetPromotions
Returns an array of all defined promo codes and associated names
DeletePromotions
Removes previously added promo codes
UpdateCustomerPromotionStatus
Informs Optimove of the status of activated promotions for particular customer IDs for a particular campaign ID
AddChannelTemplates
Adds template IDs and associated names that will be associated with a specified channel ID
GetChannelTemplates
Returns an array of template IDs and associated names for a particular channel
GetChannelTemplateDetails
Returns the content and attributes of a specific template for a specific channel
DeleteChannelTemplates
Removes previously added channel templates
AddChannelApps
Adds app IDs and associated names that will be available for selection when running a campaign via the specified channel
DeleteChannelApps
Removes previously added apps
AddExternalRealtimeTriggers
Defines one or more realtime triggers handled by an external system so that they are selectable by users for realtime campaigns within the Optimove UI
GetExternalRealtimeTriggers
Returns an array of defined external realtime trigger IDs and associated names
GetActivityEventList
Returns all available custom SDK events with each event parameter's name and type
UpdateCampaignMetrics
Reports to Optimove post-execution metrics for campaigns executed by a third-party marketing execution system
UpdateCampaignInteractions
Reports to Optimove customer interactions with campaigns executed by a third-party marketing execution system
SetCustomerChannelPreference
Set communication mode for particular customer IDs for particular channels
Optimail Functions
GetEmailParameters
Returns all available parameters for use with Optimail templates for a particular brand
GetTemplateFolders
Returns the names and IDs of all Optimail template folders for a particular brand
AddTemplate
Creates a new Optimail template
UpdateTemplate
Updates an existing Optimail template
AddUnsubscribers
Adds one or more email addresses to a global unsubscribe list of a particular brand
DeleteUnsubscribers
Deletes one email addresses from the global unsubscribe list of a particular brand
GetUnsubscribers
Allows to retrieve email addresses that are a part of a global unsubscribe list of a particular brand
Transactional Mail Functions
SendTransactionalMail
Sends a specific transactional email template to a list of recipients
SendFinalizedTransactionalMail
Sends a transactional email template, containing your custom HTML content, to a list of recipients
GetTransactionalTemplateMetrics
Returns post-execution metrics for a specific transactional mail template over time
GetTransactionalUserMetrics
Returns post-execution transactional email metrics for a specific recipient
GetTemplateDetails
Returns an array of transactional template IDs and associated attributes
General Information
Base URI
Different Optimove customers are assigned different API servers, accessed using different base URIs. Optimove's Support Team informs each customer of the correct base URI for them to use. For this reason, the base URI used for calling the API is expressed, throughout this document, as https://apiX.optimove.net/, where the X represents a number.
For example, some Optimove customers are using https://api5.optimove.net/. If you don't know which base URI to use, contact your Optimove representative.
Session Authentication Token
Every call to the API requires the use of a per-session authentication token, conforms to the JWT token standard. The token is obtained by calling the Login function before calling any other function during a particular session. The returned token must be included in the header of every subsequent call to the API:
-
-
-
- Authorization-Token:
eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiaXNzIjoiaHR0cHM6Ly9vcHRpbW92ZS5hdXRoMC5jb20vIn0..9DuWvTdukFJbQXUS.x0qZfx5fxOCKGLuuU1kDV3hqstIBIdz4LtHMU6XeJJHOgTNcAbYvU8XUqDpwoMYMRpD8mHgeqjUJbHru27zKNnD2yV20AsfDRxuJ5mGl0s1xrKCfODZe60-rnA0cj81drDXkjHagdC6XQS1PXZok_IeFYpWC18DCVYtHh0ilshNUHdxO1BcVV_W2oK9oyR01kyceqwW0sKusntuDdYqfUilC_P8n1A-KjBxx0OghciKle3fuA5UFXyWL8tbkFePQM2LSTor8NvtKscatRB2htry69zkLnHxwrpFwB_uegcaqFmViZgVZ8n_SJMHBORvNBun_a-1LtXX_pqELwzzPxPb_BGTJ4npDkHnTDMZj6BQEMuWXzgZzhDtFK0WwariXCEP_pSbBg1pE-qlYptU4OQ6UqFpJD33OP4w.5RCF8a-ody1KkZYZrCb0qw
-
-
-
- Accept: application/json
-
- Content-Type: application/json
Important Notes:
- The received authentication token remains valid for 20 minutes from the last time any API function was called using it. The Login function should only be called if 20 minutes has elapsed since the last call to the API; otherwise, the authentication token received previously remains valid. As a best practice, the Login function should only be called in the event that any other function call returns an HTTP error 403, "Authorization-Token expired".
- Each client is limited to calling the API 2000 times per hour. Excluded from this limitation are calls to the SendTransactionalMail function.
Data Types
All data values passed to/from the API are of one of the following data types:
integer | A whole number greater than or equal to 0 |
double | A signed floating-point number |
string | A string of non-case-sensitive alphanumeric characters of any length, using any encoding |
StringArray | A JSON-formatted array of string values |
ObjectArray | A JSON-formatted array of objects |
date | Eight numerals delimited by dashes in the format YYYY-MM-DD |
DateTime | Eight numerals for the date delimited by dashes plus six numerals for the time delimited by colons in the format YYYY-MM-DD HH:MM:SS |
boolean | A string equal to either "true" or "false" |
RGID* | A single numeric digit indicating a Recipient Group ID. When a campaign is sent to a single group of recipients, the campaign's RGID will always be 1. When a campaign includes a control group, the control group's RGID will be 0. When a campaign is sent to multiple recipient groups, their RGIDs will be 1, 2, etc. (if present, the control group is always 0). In an A/B/n campaign, the A group recipients' RGID is 1, B is 2, etc. |
null | No data |
*RGID is not actually a data type – it is always a single numeric digit (integer). RGID is treated as a distinct data type in this documentation to indicate that it is an integer with a limited set of possible values, as described above.
Input Parameters
Input parameter names are not case sensitive. They are presented in this document with initial capitals (e.g., TargetGroupName) for the sake of clarity.
Users can set a data delimiter for all API calls that include Customer Attributes as an optional parameter, to define the character that will separate the attribute values.
The supported values are:
- Comma (, )
- Colon (: )
- Semicolon (;)
- Tab (\t)
By default, comma (,) is selected as the field delimiter.
For example, in order to separate Alias by semi-column, use the following:
https://apiX.optimove.net/current/customers/GetCustomerExecutionDetailsByCampaign?CampaignID=836&CustomerAttributes=Alias&CustomerAttributeDelimiter=;
Notes on Customer Attributes
-
- All functions can include customer attributes as optional parameters and will include up to 10 customer attributes.
- If supplied, CustomerAttributes must contain one or more valid attribute names (see GetCustomerAttributeList) separated by semicolons (;). The values are returned in the same order as the attribute names are specified in the request.
- The customer attribute values returned are the current (latest available) values, not the values on the specified date.
HTTP Methods and Response Formats
Functions must be called either via HTTP GET or HTTP POST, as indicated in the API documentation for each function.
The data returned from functions using the GET method can be formatted as either JSON or XML, by using one of these request headers (if no Accept header is specified, the default response format is JSON):
-
- "Accept:application/JSON"
-
- "Accept:application/XML"
The data returned from functions using the POST method are always formatted as JSON.
All examples in this document are shown using JSON.
Response Paging for Customer-related Functions
By default, all customer-related functions will return 10,000 records (the default page size) in any response (assuming there are at least 10,000 records to return). To request a smaller or larger page size, append the input parameter $top=n where n is the page size. The maximum supported page size is 200,000.
To request subsequent pages of results, repeat the request with the additional parameter $skip=n where n is the number of resulting records of the entire result set to skip over when returning the current page.
The $top and $skip parameters may be added to any customer-related function request.
Examples
The following request will return the first 10,000 records (assuming there are at least 10,000 records to return):
https://apiX.optimove.net/current/segments/GetCustomerOneTimeActionsByDate?Date=2018-03-01
The following request will return the next 10,000 records, i.e., the second page:
https://apiX.optimove.net/current/segments/GetCustomerOneTimeActionsByDate?Date=2018-03-01&$skip=10000
The following two requests will (a) return the first 100,000 records, and (b) return the second page consisting of an additional 100,000 records:
https://apiX.optimove.net/current/segments/GetCustomerOneTimeActionsByDate?Date=2018-03-01&$top=100000
https://apiX.optimove.net/current/segments/GetCustomerOneTimeActionsByDate?Date=2018-03-01&$top=100000&$skip=100000
Empty Response
An empty response from any function indicates that the inputs were recognized as valid, but that no data exists (e.g., no actions are scheduled for the particular target group and date supplied to the GetActionsByTargetGroup function).
Function Error Response Codes
A successful function call will return a response code of 200 (success). An unsuccessful call will return one of the following response codes:
400 | If any of the inputs to a function are invalid or unrecognized, HTTP response code 400 (Bad Request) will be returned along with a detailed explanation of the specific error condition. |
401 | If an invalid session authorization token is supplied, HTTP response code 401 (Unauthorized) is returned. |
403 | If a function is called with an expired authentication token OR some of the attributes used within in a call are not authorized for the user, HTTP response code 403 is returned. |
405 | If an unrecognized function is called, HTTP response code 405 (Method Not Allowed) is returned. |
429 | If the Login function is called too many times while a valid authentication token exists, HTTP response code 429 (Too Many Requests or User Already Logged In) is returned. |
500 | If the credentials supplied to the Login function are invalid, HTTP response code 500 (Internal Server Error) is returned. |
Understanding Dates in Optimove
Last Data Update and Campaign Execution Dates
It is advisable to query the GetLastDataUpdate function before running any processes using the API. Optimove updates the Last Data Update date only after all customer segmentation and campaign execution processes for that date have been completed.
This date will always be at least one day earlier than the current day (because the current day's data has not yet been received and processed).
API queries that retrieve details about campaigns, target groups, promotions, etc. for a particular date should specify the relevant campaign execution dates, and not the Last Data Update date.
Campaign Execution Dates and Lead Time
Functions that receive a date and return details of a campaign, target group, promotion, etc. ignore any lead time associated with the campaign. In other words, the relevant date is the one on which the campaign appears in the Marketing Plan (i.e., the date that the action is actually executed).
One exception is the GetExecutedCampaignDetails function, which returns details of campaigns scheduled for execution on date specified when calling the function, as well as campaigns with a specified lead time that points to the specified date (e.g., a campaign scheduled for execution on 5 June with a lead time of three days will be returned by this function when called by specifying the date of 2 June).
IP Whitelist/Allow List
EU IP addresses:
- 34.159.94.86
- 35.242.197.153
- 34.159.242.247
- 35.189.243.236
- 192.158.28.169
- 35.195.171.164
US IP addresses:
- 35.245.236.141
- 34.145.132.59
- 34.145.232.78
- 34.70.245.229
- 34.122.196.101
- 34.71.252.19
You can add these IP addresses to your infrastructure whitelist. Add all four IP addresses to the whitelist to ensure continuous access.
Glossary of Terms
- Action – A specific incentive/offer/reward sent to customers (e.g., 10% deposit bonus, free coins, free spins, free shipping). The Action ID is Optimove's unique ID for each action and is not connected with any ID number outside Optimove. An Action's duration is the number of days during which results for the campaign are measured and during which customers will generally not receive a second/different campaign.
- Campaign – An action sent to customers who are members of a particular Target Group on a particular date.
- Channel ID – The identifier of a particular campaign execution channel. A list of all available ChannelID values is available here.
- Customer ID – The identifier of a customer in your customer database.
- Execution channel – How an Action is sent to a customer. Possibilities include the name of an ESP (e.g., Silverpop, ExactTarget), a message board system, the emailing of a customer list for manual processing and others.
- Lifecycle stage – The highest level of customer segmentation in Optimove is the classification of customers into distinct lifecycle stages. Typical Lifecycle stages include New, Active, VIP, Churn, Back from Churn.
- Promotion – The reward/discount/incentive associated with a particular action, as it appears in your back office/financial system.
- Target group – A Target Group is the specification of which customers will be targeted with a particular action on a particular date. An Optimove user defines Target Groups by specifying one or more customer selection criteria. On a day that a campaign is sent to a Target Group, Optimove dynamically selects the members of the Target Group based on the defined selection criteria.
- Value segment – Value segmentation is the grouping of customers according to their expected future value, which is based on past behavior patterns. Value groups cut across lifecycle stages.
General Functions
All general functions are called by appending the function name to the URL prefix https://apiX.optimove.net/current/general/
Login
Returns the authentication token required for all other functions during a particular session.
URI | https://apiX.optimove.net/current/general/login |
HTTP Method | POST |
Request Structure | {
"UserName":"string", "Password":"string" } |
Response Structure | (string) |
Sample Request | {
"UserName":"someusername", "Password":"somepassword" } |
Sample Response | "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiaXNzIjoiaHR0cHM6Ly9vcHRpbW92ZS5hdXRoMC5jb20vIn0..9DuWvTdukFJbQXUS.x0qZfx5fxOCKGLuuU1kDV3hqstIBIdz4LtHMU6XeJJHOgTNcAbYvU8XUqDpwoMYMRpD8mHgeqjUJbHru27zKNnD2yV20AsfDRxuJ5mGl0s1xrKCfODZe60-rnA0cj81drDXkjHagdC6XQS1PXZok_IeFYpWC18DCVYtHh0ilshNUHdxO1BcVV_W2oK9oyR01kyceqwW0sKusntuDdYqfUilC_P8n1A-KjBxx0OghciKle3fuA5UFXyWL8tbkFePQM2LSTor8NvtKscatRB2htry69zkLnHxwrpFwB_uegcaqFmViZgVZ8n_SJMHBORvNBun_a-1LtXX_pqELwzzPxPb_BGTJ4npDkHnTDMZj6BQEMuWXzgZzhDtFK0WwariXCEP_pSbBg1pE-qlYptU4OQ6UqFpJD33OP4w.5RCF8a-ody1KkZYZrCb0qw" |
Notes
- Refer to this GitHub repository for diagrammic use cases of how the Login function should be used.
- Our token policy is following JWT access token standard. Please make sure you comply with the token policy as exampled it the “Sample Response” attached here.
- The response returned by this request will be the session authentication token (a string). If the supplied credentials are invalid, HTTP error code 401 (Unauthorized) is returned.
- The returned token must be included within the HTTP request header "Authorization-Token" of subsequent function calls (see Session Authentication Token).
- The received authentication token remains valid for 20 minutes from the last time any API function was called using it. The Login function should only be called if 20 minutes has elapsed since the last call to the API; otherwise, the authentication token received previously remains valid. As a best practice, the Login function should only be called in the event that any other function call returns an HTTP error 403, "Authorization-Token expired".
- An HTTP error code of 429 (Too many requests) is returned if the Login function is called too many times unnecessarily.
- Your Username and Password are provided to you by your Optimove representative.
Authentication Using API Keys
API requests can be also authenticated using an API key, using the key as a property in the request header.
Header | X-API-KEY |
Header Value | API Key as generated in Optimove’s UI. |
Sample Request | X-API-Key: cea8836073dddacd8064ac2d81248aab2728e5648kja7s78915e |
Notes
- This header should be added to each API request.
GetLastDataUpdate
Returns the date of the most recently available customer data.
URI | https://apiX.optimove.net/current/general/GetLastDataUpdate |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (none) |
Response Structure | {"Date":"date"} |
Sample Request | https://apiX.optimove.net/current/general/GetLastDataUpdate |
Sample Response | {"Date":"2018-07-13"} |
RegisterEventListener
Specifies the URL of a listener to which Optimove will report events of the specified type (e.g., "campaign scheduled").
URI | https://apiX.optimove.net/current/general/RegisterEventListener |
HTTP Method | POST |
Request Structure | {
"EventTypeID":integer, "ChannelID":integer (optional), "ListenerURL":"string" } |
Response Structure | (none) |
Sample Request | {
"EventTypeID":1, "ChannelID":505, "ListenerURL":"http%3A%2F%2Fwww.exampleurl.com%2Feventlistener6" } |
Sample Response | (none) |
Notes
- This function does not return a payload. A successful call will return a response code of 200 (success). Refer to an explanation of the other possible response codes at Function Error Response Codes.
- Valid values for EventTypeID are:
- 1 = A campaign has been processed for execution. Will be sent when the execution of at least one of the channels/templates was successful.
- 2 = All today's campaigns have been processed for execution (even if some failed).
- 3 = Today's entire daily process has been completed.
- 4 = A campaign that had been processed for execution was canceled.
- 5 = A campaign with conditional promo/bonus system activation has been processed for execution, but is on hold until the ClearanceRequiredBy date/time supplied to the listener at the time of event notification, and then will only be sent to customers for whom the promotion was activated in the promo/bonus system (learn more here).
Please Note: EventTypeID = 5 cannot be registered for a specific channel, rather it should be registered as a general listener (without specifying a specific channel ID). - 11 = A user has met a trigger criteria set-up for a realtime campaign (Note: This event type is only relevant for Optimove clients using Track & Trigger).
- 13 = A campaign has been executed via a particular channel (but not necessarily via any additional channels included in the same campaign). Will be sent when ALL templates for the specific channel sent successfully. Note: If a ChannelID is specified when registering this type of listener, a notification will be sent each time a campaign has been executed via the specified channel. If no ChannelID is specified, a notification will be sent when execution has completed for each channel for every campaign.
- ChannelID is optional for users with full permissions. Users with limited permissions (i.e. per specific channel) must include ChannelID for all types of events. Available ChannelID values can be seen here.
- The specified ListenerURL must be encoded using percent encoding, also known as URL encoding (learn more).
- Each EventTypeID needs to be registered separately (via a separate call), even if the listener URL is identical for more than one EventTypeID.
- Once a listener has been registered, Optimove will call the listener with an HTTP POST request in JSON format, and expects to receive a response of success (200). The structure of the request depends on the EventTypeID:
EventTypeID = 1:{
"EventTypeID":1,
"TimeStamp":"YYYY-MM-DD HH:MM:SS",
"CampaignID":x
}
EventTypeID = 2:
{
"EventTypeID":2,
"TimeStamp":"YYYY-MM-DD HH:MM:SS"
}
EventTypeID = 3:
{
"EventTypeID":3,
"TimeStamp":"YYYY-MM-DD HH:MM:SS",
"UpdateDate":"YYYY-MM-DD"
}
EventTypeID = 4:
{
"EventTypeID":4,
"TimeStamp":"YYYY-MM-DD HH:MM:SS",
"CampaignID":x
}
EventTypeID = 5:
{
"EventTypeID":5,
"TimeStamp":"YYYY-MM-DD HH:MM:SS",
"CampaignID":x,
"CampaignDuration":y,
"ClearanceRequiredBy":"YYYY-MM-DD HH:MM:SS"
}
Note: ClearanceRequiredBy is calculated by Optimove based on the campaign's selected execution channel(s).
EventTypeID = 11:
{
"customerID":"string",
"isVisitor":true/false,
"actionID":X,
"promoCode":[],
"channelID":X,
"campaignID":"string",
"templateName":"string",
"campaignSeriesID":"string",
"templateID":X,
"timestamp":"string",
"personalization":
{
"personalInfo":{tagName:'val'},
"eventName":{eventParam:'val'}
},
"actionName":"string",
"triggerName":"string",
"targetGroupName":"string",
"brandID":"string"}
Note:
- Personalization values will only be included if defined in the campaign: personalInfo may be one more personalization fields defined in the Optimove database (personalInfo is available for any channel using personalization tags); eventName may be one or more defined events that are part of the campaign's trigger.
- In order to receive this event for customers that are allocated to the campaign’s control group, ChannelID 100 must be included in the registration request.
- ExternalData will be supplied only for Optimove’s integration partners for whom it was considers as part of the integration scope
EventTypeID = 13:
{
"EventTypeID":13,
"TimeStamp":"YYYY-MM-DD HH:MM:SS",
"CampaignID":x,
"ChannelID":x
}
Note: TimeStamp values sent to the listener are in UTC.
The values for the header are in the following format: key1=value1;key2=value2;key3=value3.
For configuration, please contact your CSM.
UnregisterEventListener
Instructs Optimove to stop reporting events of the specified event type to a previously-registered listener.
URI | https://apiX.optimove.net/current/general/UnregisterEventListener |
HTTP Method | POST |
Request Structure | {
"EventTypeID":integer, "ChannelID":integer (optional), "ListenerURL":"string" (optional) } |
Response Structure | (none) |
Sample Request | {"EventTypeID":1} |
Sample Response | (none) |
Notes
- This function does not return a payload. A successful call will return a response code of 200 (success). Refer to an explanation of the other possible response codes at Function Error Response Codes.
- ChannelID is optional. Available values can be seen here.
GetRegisteredEventListeners
Retrieve a list of all currently registered event listeners.
URI | https://apiX.optimove.net/current/general/GetRegisteredEventListeners |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (integer) ChannelID |
Response Structure | [{
"EventTypeID":integer, "ChannelID":integer, "ListenerURL":""string" }] |
Sample Request | https://apiX.optimove.net/current/general/GetRegisteredEventListeners |
Sample Response | [
{"EventTypeID":1,"ChannelID":201,"ListenerURL":"https%3A%2F%2Fwww.exampleurl.com%2Feventlistener1"}, {"EventTypeID":2,"ChannelID":201,"ListenerURL":"https%3A%2F%2Fwww.exampleurl.com%2Feventlistener2"} ] |
Model-related Functions
All model-related functions are called by appending the function name to the URL prefix https://apiX.optimove.net/current/model/
GetCustomerAttributeList
Returns all the available customer attribute names (which can be passed to certain other functions as an input parameter) and a description of each.
URI | https://apiX.optimove.net/current/model/GetCustomerAttributeList |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (none) |
Response Structure | [{
"RealFieldName":"string", "Description":"string" }] |
Sample Request | https://apiX.optimove.net/current/model/GetCustomerAttributeList |
Sample Response | [
{"RealFieldName":"Affiliate","Description":"Acquisition affiliate"}, {"RealFieldName":"Age","Description":"Customer age"}, {"RealFieldName":"Country","Description":"Country of residence"} ] |
GetLifecycleStageList
Returns all available lifecycle stages (for use in other functions, e.g., GetCustomerFutureValues).
URI | https://apiX.optimove.net/current/model/GetLifecycleStageList |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (none) |
Response Structure | [{
"StageID":integer, "StageName":"string" }] |
Sample Request | https://apiX.optimove.net/current/model/GetLifecycleStageList |
Sample Response | [
{"StageID":1,"StageName":"New"}, {"StageID":2,"StageName":"Active"}, {"StageID":3,"StageName":"FromChurn"}, {"StageID":4,"StageName":"Churn"} ] |
GetMicrosegmentList
Returns an array containing the details of all microsegments.
URI | https://apiX.optimove.net/current/model/GetMicrosegmentList |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (none) |
Response Structure | [{
"MicrosegmentID":integer, "MicrosegmentName":"string", "LifecycleStageID":"string", "FutureValue":double, "ChurnRate":double "ReactivationRate":double "ConversionProbability":double }] |
Sample Request | https://apiX.optimove.net/current/model/GetMicrosegmentList |
Sample Response | [
{"MicrosegmentID":1,"MicrosegmentName":"DWag1-Europe-Winner","LifecycleStageID":"1","FutureValue":870.55,"ChurnRate":0.55,"ReactivationRate":0.04,"ConversionProbability":1}, {"MicrosegmentID":2,"MicrosegmentName":"DWag2-US-Loser","LifecycleStageID":"2","FutureValue":1065.10,"ChurnRate":0.52,"ReactivationRate":0.061,"ConversionProbability":1}, {"MicrosegmentID":3,"MicrosegmentName":"DWag3-ROW-Winner","LifecycleStageID":"2","FutureValue":1213.76,"ChurnRate":0.57,"ReactivationRate":0.033,"ConversionProbability":1} ] |
GetMicrosegmentChangers
Returns an array of customer IDs, and their before and after micro-segment IDs, for customers whose micro-segment changed during the last day for which data is available.
URI | https://apiX.optimove.net/current/model/GetMicrosegmentChangers |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (string) CustomerAttributes |
Response Structure | [{
"CustomerID":"string", "InitialMicrosegmentID":integer, "FinalMicrosegmentID":integer, "CustomerAttributes":[StringArray] }] |
Sample Request | https://apiX.optimove.net/current/model/GetMicrosegmentChangers?CustomerAttributes=Alias;Country |
Sample Response | [
{"CustomerID":"231342","InitialMicrosegmentID":4,"FinalMicrosegmentID":12,"CustomerAttributes":["BuddyZZ","UK"]}, {"CustomerID":"231342","InitialMicrosegmentID":3,"FinalMicrosegmentID":67,"CustomerAttributes":["Player99","US"]} ] |
Notes
- The customer IDs returned are those whose micro-segment changed during the last day for which data is available.
Action-related Functions
All action-related functions are called by appending the function name to the URL prefix https://apiX.optimove.net/current/actions/
GetActionName
Returns the action name associated with a particular action ID.
URI | https://apiX.optimove.net/current/actions/GetActionName |
HTTP Method | GET |
Required Parameters | (integer) ActionID |
Optional Parameters | (none) |
Response Structure | {
"ActionName":"string" } |
Sample Request | https://apiX.optimove.net/current/actions/GetActionName?ActionID=104 |
Sample Response | {"ActionName":"10% summer bonus"} |
GetActionID
Returns the action ID associated with a particular action name.
URI | https://apiX.optimove.net/current/actions/GetActionID |
HTTP Method | GET |
Required Parameters | (string) ActionName |
Optional Parameters | (none) |
Response Structure | {"ActionID":integer} |
Sample Request | https://apiX.optimove.net/current/actions/GetActionID?ActionName=Free%20Shipping |
Sample Response | {"ActionID":25} |
GetAllActions
Returns all defined action IDs and corresponding action names.
URI | https://apiX.optimove.net/current/actions/GetAllActions |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (none) |
Response Structure | [{
"ActionID":integer, "ActionName":"string" }] |
Sample Request | https://apiX.optimove.net/current/actions/GetAllActions |
Sample Response | [
{"ActionID":1,"ActionName":"10% Bonus"}, {"ActionID":2,"ActionName":"15% Bonus"}, {"ActionID":3,"ActionName":"20% Bonus"} ] |
GetActionsByTargetGroup
Returns all the recipient group IDs and action IDs associated with a particular target group on a particular date.
URI | https://apiX.optimove.net/current/actions/GetActionsByTargetGroup |
HTTP Method | GET |
Required Parameters | (integer) TargetGroupID
(date) Date |
Optional Parameters | (none) |
Response Structure | [{
"RecipientGroupID":RGID, "ActionID":integer }] |
Sample Request | https://apiX.optimove.net/current/actions/GetActionsByTargetGroup?TargetGroupID=7&Date=2018-06-23 |
Sample Response | [
{"RecipientGroupID":1,"ActionID":23}, {"RecipientGroupID":2,"ActionID":27} ] |
GetPromoCodes
Returns all target group IDs, action IDs and promo codes for a particular date.
URI | https://apiX.optimove.net/current/actions/GetPromoCodes |
HTTP Method | GET |
Required Parameters | (date) Date |
Optional Parameters | (none) |
Response Structure | [{
"TargetGroupID":integer "RecipientGroupID":RGID "ActionID":integer, "PromoCode":"string" }] |
Sample Request | https://apiX.optimove.net/current/actions/GetPromoCodes?Date=2018-02-20 |
Sample Response | [
{"TargetGroupID":9,"RecipientGroupID":1,"ActionID":24,"PromoCode":"HEP-FEB"}, {"TargetGroupID":9,"RecipientGroupID":2,"ActionID":25,"PromoCode":"HEP-FCC"}, {"TargetGroupID":9,"RecipientGroupID":1,"ActionID":24,"PromoCode":"HEP-FEB",“ENG-JAN”}, {"TargetGroupID":13,"RecipientGroupID":1,"ActionID":65,"PromoCode":"GDG-FAL"} ] |
GetPromoCodesByCampaign
Returns the recipient group IDs, action IDs and promo codes for a particular campaign ID.
URI | https://apiX.optimove.net/current/actions/GetPromoCodesByCampaign |
HTTP Method | GET |
Required Parameters | (integer) CampaignID |
Optional Parameters | (none) |
Response Structure | [{
"RecipientGroupID":RGID "ActionID":integer, "PromoCode":"string" }] |
Sample Request | https://apiX.optimove.net/current/actions/GetPromoCodesByCampaign?CampaignID=721 |
Sample Response | [
{"RecipientGroupID":1,"ActionID":24,"PromoCode":"HEP-75-FEB"}, {"RecipientGroupID":2,"ActionID":65,"PromoCode":"GDG-50-FRT"}, {"RecipientGroupID":2,"ActionID":65,"PromoCode":"GDG-50-FRT","HEP-75-FEB"} ] |
GetPromoCodesByTargetGroup
Returns all recipient group IDs, action IDs and promo codes associated with a given target group on a particular date.
URI | https://apiX.optimove.net/current/actions/GetPromoCodesByTargetGroup |
HTTP Method | GET |
Required Parameters | (integer) TargetGroupID
(date) Date |
Optional Parameters | (none) |
Response Structure | [{
"RecipientGroupID":RGID "ActionID":integer, "PromoCode":"string" }] |
Sample Request | https://apiX.optimove.net/current/actions/GetPromoCodesByTargetGroup?TargetGroupID=41&Date=2018-05-23 |
Sample Response | [
{"RecipientGroupID":1,"ActionID":24,"PromoCode":"HEP-FEB"}, {"RecipientGroupID":2,"ActionID":25,"PromoCode":"HEP-FCC"}, {"RecipientGroupID":1,"ActionID":65,"PromoCode":"GDG-FAL"} {"RecipientGroupID":1,"ActionID":65,"PromoCode":"GDG-FAL","HEP-FCC"} ] |
GetActionDetailsByTargetGroup
Returns the action IDs, action duration (in days), lead time (in days) and the execution channels associated with a given target group on a particular date.
URI | https://apiX.optimove.net/current/actions/GetActionDetailsByTargetGroup |
HTTP Method | GET |
Required Parameters | (integer) TargetGroupID
(date) Date |
Optional Parameters | (none) |
Response Structure | [{
"RecipientGroupID":RGID "ActionID":integer, "Duration":integer, "LeadTime":integer, "ChannelID":integer }] |
Sample Request | https://apiX.optimove.net/current/actions/GetActionDetailsByTargetGroup?TargetGroupID=9&Date=2018-07-11 |
Sample Response | [
{"RecipientGroupID":1,"ActionID":65,"Duration":7,"LeadTime":0,"ChannelID":504}, {"RecipientGroupID":1,"ActionID":78,"Duration":7,"LeadTime":0,"ChannelID":504} ] |
Note
Duration and lead time values are number of days.
GetExecutedCampaignDetails
Returns details of every campaign executed on a particular date.
URI | https://apiX.optimove.net/current/actions/GetExecutedCampaignDetails |
HTTP Method | GET |
Required Parameters | (date) Date |
Optional Parameters | (none) |
Response Structure | [{
"CampaignID":integer, "TargetGroupID":integer, "CampaignType":"string", "Duration":integer, "LeadTime":integer, "Notes":"string", "IsMultiChannel":boolean, "IsRecurrence":boolean, "Status":"string", "Error":"string" }] |
Sample Request | https://apiX.optimove.net/current/actions/GetExecutedCampaignDetails?Date=2018-05-19 |
Sample Response | [
{"CampaignID":221,"TargetGroupID":15,"CampaignType":"Test/Control","Duration":7,"LeadTime":3,"Notes":"","IsMultiChannel":false,"IsRecurrence":false,"Status":"Successful","Error":null}, {"CampaignID":81,"TargetGroupID":40,"CampaignType":"Test/Control","Duration":10,"LeadTime":0,"Notes":"","IsMultiChannel":true,"IsRecurrence":true,"Status":"Failed","Error":"ESP unavailable"} ] |
Notes
- Duration and lead time values are number of days.
- This function will return details of campaigns scheduled for execution on the specified date, as well as campaigns with a specified lead time that points to the specified date (e.g., a campaign scheduled for execution on 5 June with a lead time of three days will be returned by this function when called by specifying the date of 2 June).
- Possible results for CampaignType are:
- Test/Control
- A/B
- A/B/N
- Self-Optimizing
- No Control
- Possible results for Status are:
- Processed (means the campaign was processed for execution, but hasn’t finished yet)
- Successful
- Partially Run
- Failed campaigns will not be returned by this function.
GetCampaignDetails
Returns details of a particular campaign.
URI | https://apiX.optimove.net/current/actions/GetCampaignDetails |
HTTP Method | GET |
Required Parameters | (integer) CampaignID |
Optional Parameters | (none) |
Response Structure | {
"TargetGroupID":integer, "CampaignType":"string", "Duration":integer, "LeadTime":integer, "Notes":"string", "IsMultiChannel":boolean, "IsRecurrence":boolean, "Status":"string", "Error":"string", "Tags":[StringArray] } |
Sample Request | https://apiX.optimove.net/current/actions/GetCampaignDetails?CampaignID=21 |
Sample Response | {
"TargetGroupID":15, "CampaignType":"Test/Control", "Duration":7, "LeadTime":3, "Notes":"", "IsMultiChannel":false, "IsRecurrence":false, "Status":"Successful", "Error":"", "Tags":["Reactivated to Active","PromotionBoost"] } |
Notes
- Duration and lead time values are number of days.
- Possible results for CampaignType are:
- Test/Control
- A/B
- A/B/N
- Self-Optimizing
- No Control
- Possible results for Status are:
- Successful
- Not Run
- Partially Run
- Failed campaigns will not be returned by this function.
GetExecutionChannels
Returns all execution channels that were in use in a campaign.
URI | https://apiX.optimove.net/current/actions/GetExecutionChannels |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (none) |
Response Structure | [{
"ChannelID":integer, "ChannelName":"string" }] |
Sample Request | https://apiX.optimove.net/current/actions/GetExecutionChannels |
Sample Response | [
{"ChannelID":15,"ChannelName":"Optimail"}, {"ChannelID":29,"ChannelName":"Optipush"}, {"ChannelID":504,"ChannelName":"Email"}, {"ChannelID":505,"ChannelName":"SMS"} {"ChannelID":509,"ChannelName":"Other"} ] |
GetExecutedCampaignChannelDetails
Returns the details of a particular channel used in a particular executed campaign.
URI | https://apiX.optimove.net/current/actions/GetExecutedCampaignChannelDetails |
HTTP Method | GET |
Required Parameters | (integer) CampaignID
(integer) ChannelID |
Optional Parameters | (none) |
Response Structure | [{
"SendID":"string", "TemplateID":"string", "ScheduledTime":"DateTime" }] |
Sample Request | https://apiX.optimove.net/current/actions/GetExecutedCampaignChannelDetails?CampaignID=9214&ChannelID=15 |
Sample Response | [
{"SendID":"YTGF3C","TemplateID":"520","ScheduledTime":"2018-05-30 08:00:00"} ] |
Notes
- This function is generally used after the Event Listener receives notification that a campaign has been scheduled in order to verify with the delivery system (e.g., Silverpop) that the campaign was sent and then to set promotions for individual customers according to the time the campaign was sent.
- Available ChannelID values can be seen here.
- All times are returned in UTC.
GetExecutedCampaignsByChannel
Returns the list of campaigns executed for a particular channel on a particular date.
URI | https://apiX.optimove.net/current/actions/GetExecutedCampaignsByChannel |
HTTP Method | GET |
Required Parameters | (integer) ChannelID
(date) Date |
Optional Parameters | (none) |
Response Structure | [{
"CampaignID":"string" }] |
Sample Request | https://apiX.optimove.net/current/actions/GetExecutedCampaignsByChannel?ChannelID=15&Date=2018-02-20 |
Sample Response | [
{"CampaignID":"12"}, {"CampaignID":"16"}, {"CampaignID":"17"}, {"CampaignID":"19"} ] |
Target Group-related Functions
All target group-related functions are called by appending the function name to the URL prefix https://apiX.optimove.net/current/groups/
GetTargetGroupName
Returns the target group name associated with a particular target group ID.
URI | https://apiX.optimove.net/current/groups/GetTargetGroupName |
HTTP Method | GET |
Required Parameters | (integer) TargetGroupID |
Optional Parameters | (none) |
Response Structure | {"TargetGroupName":"string"} |
Sample Request | https://apiX.optimove.net/current/groups/GetTargetGroupName?TargetGroupID=42 |
Sample Response | {"TargetGroupName":"Ireland VIPs Played Last 30 Days"} |
GetTargetGroupID
Returns the target group ID associated with a particular target group name.
URI | https://apiX.optimove.net/current/groups/GetTargetGroupID |
HTTP Method | GET |
Required Parameters | (string) TargetGroupName |
Optional Parameters | (none) |
Response Structure | {"TargetGroupID":integer} |
Sample Request | https://apiX.optimove.net/current/groups/GetTargetGroupID?TargetGroupName=UK%20VIPs |
Sample Response | {"TargetGroupID":26} |
GetTargetGroupsByDate
Returns the list of target group IDs for which an action was executed on a particular date.
URI | https://apiX.optimove.net/current/groups/GetTargetGroupsByDate |
HTTP Method | GET |
Required Parameters | (date) Date |
Optional Parameters | (none) |
Response Structure | [{"TargetGroupID":integer}] |
Sample Request | https://apiX.optimove.net/current/groups/GetTargetGroupsByDate?Date=2018-05-31 |
Sample Response | ["TargetGroupID":9},{"TargetGroupID":24},{"TargetGroupID":31}] |
Note
Duration and lead time values are number of days.
GetTargetGroupDetails
Returns an array of IDs, names and priorities for all defined target groups.
URI | https://apiX.optimove.net/current/groups/GetTargetGroupDetails |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (none) |
Response Structure | [{
"TargetGroupID":integer, "TargetGroupName":"string", "TargetGroupPriority":integer }] |
Sample Request | https://apiX.optimove.net/current/groups/GetTargetGroupDetails |
Sample Response | [
{"TargetGroupID":1,"TargetGroupName":"New UK","TargetGroupPriority":1}, {"TargetGroupID":2,"TargetGroupName":"New DE","TargetGroupPriority":2} ] |
Customer-related Functions
All customer-related functions are called by appending the function name to the URL prefix https://apiX.optimove.net/current/customers/
Note that all customer-related functions return a maximum of 10,000 records and support paging parameters. See Response Paging for Customer-related Functions for details.
AddCustomerAttribute
Add a new customer attribute.
URI | https://apiX.optimove.net/current/customers/AddCustomerAttribute |
HTTP Method | POST |
Required Parameters | (string)Name
(string)Type (optional values: DECIMAL(19,4), 'INT', 'BIGINT', 'DATE' ,'VARCHAR(X)' or 'NVARCHAR(X)) |
Optional Parameters | (string)DefaultValue
(string)CallbackURL |
Request Structure | { "Name":"string", "Type":"string", "DefaultValue":"string" (optional) "CallbackURL":"string" (optional) } |
Response Structure | ''Request was processed. If Callback URL was defined, you will receive a notification with feedback. If Callback URL was not defined, use GetCustomerAttributeList function in 1 minute to verify attributes addition.' |
Sample Request | { "Name":"VIP Level", "Type":"VARCHAR(10)", "DefaultValue":"Bronze" (optional) "CallbackURL":"https://tenantname.requestcatcher.com/test" } |
Notes
- Limitation: up to 40 attributes can be added via API
- Attributes created via the AddCustomerAttribute function can only be updated using the UpdateCustomerAttributes function.
- If a Callback URL was defined you will receive the following response to the Webhook up to 1 minute after the call:
- Attribute Name
- IsSuccess: true or false
- Error ID and error message in case of failure. Possible values for Error in case of failure in the response:
- 1 = Attribute was not added, number of attributes added exceeds the 40 attributes limit
- 2 = Attribute was not added, specified RealFieldName already exists
- 3 = Attribute was not added, field_Type Input should be 'DECIMAL(19,4), 'INT', 'BIGINT', 'DATE' ,'VARCHAR(X)' or 'NVARCHAR(X)'
- 4 = Attribute was not added, 'CHAR' value (DefaultValue) cannot be inserted into a column with data type 'INT'
- 5 = Attribute was not added, general error occurred
Examples for reference:
{"attributeName":"LoDoTestNVarcharr11","isSuccess":false,"errorId":"3","errorMsg":"Attribute was not added, Type Input should be 'DECIMAL(19,4), 'INT', 'BIGINT', 'DATE' ,'VARCHAR(X)' or 'NVARCHAR(X)'."}
{"attributeName":"LoDoTestNVarcharr17","isSuccess":true}
{"attributeName":"LoDoTestNVarcharr17","isSuccess":false,"errorId":"2","errorMsg":"Attribute was not added, specified RealFieldName already exists."}
GetCustomersByAction
Returns the list of customer IDs associated with a particular recipient group and action on a particular date, plus an optional customer attribute.
URI | https://apiX.optimove.net/current/customers/GetCustomersByAction |
HTTP Method | GET |
Required Parameters | (RGID) RecipientGroupID
(integer) ActionID (date) Date |
Optional Parameters | (string) CustomerAttributes |
Response Structure | [{
"CustomerID":"string", "CustomerAttributes":[StringArray] }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomersByAction?RecipientGroupID=1&ActionID=2&Date=2018-05-24&CustomerAttributes=Alias;Country |
Sample Response | [
{"CustomerID":"231342","CustomerAttributes":["BuddyZZ","UK"]}, {"CustomerID":"943157","CustomerAttributes":["Pax65","DE"]} ] |
GetCustomerActionsByTargetGroup
Returns a list of customers and the details of the marketing actions they received, for a particular target group ID on a particular date.
URI | https://apiX.optimove.net/current/customers/GetCustomerActionsByTargetGroup |
HTTP Method | GET |
Required Parameters | (integer) TargetGroupID
(date) Date |
Optional Parameters | (integer) ChannelID
(boolean) IncludeControlGroup (boolean) IncludeRecipientGroupID (string) CustomerAttributes |
Response Structure | [{
"CustomerID":"string", "RecipientGroupID":RGID, "ActionID":integer, "ChannelID":integer, "CustomerAttributes":[StringArray] }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomerActionsByTargetGroup?TargetGroupID=2&Date=2018-02-24&IncludeControlGroup=True&IncludeRecipientGroupID=True&CustomerAttributes=Alias;Country |
Sample Response | [
{"CustomerID":"A1342","RecipientGroupID":1,"ActionID":49,"ChannelID":504,"CustomerAttributes":["BuddyZZ","UK"]}, {"CustomerID":"G4650","RecipientGroupID":1,"ActionID":49,"ChannelID":504,"CustomerAttributes":["Pax65","DE"]} ] |
Notes
- By specifying a ChannelID, you can limit the results returned to marketing actions sent via a particular channel. You can see the available ChannelID values here, and you can also retrieve the available execution channel IDs and associated channel names using the GetExecutionChannels function.
- The results may optionally include customer IDs of customers included in the control group (i.e., those who did not actually receive the campaign). To include these customers in the response, set IncludeControlGroup=1 (if omitted or set to 0, control group customer IDs will not be returned). If included, these customers are identified in the response by an ActionID of 1.
- This function does not return information about a one-time campaign; thus, an error results if -1 is passed as the target group ID. To retrieve information about one-time campaigns, use GetCustomerOneTimeActionsByDate or GetCustomerOneTimeActionsByCampaign.
GetCustomerOneTimeActionsByDate
Returns a list of customers and the details of the marketing actions they received as part of one-time campaigns executed on a particular date.
URI | https://apiX.optimove.net/current/customers/GetCustomerOneTimeActionsByDate |
HTTP Method | GET |
Required Parameters | (date) Date |
Optional Parameters | (boolean) IncludeControlGroup
(string) CustomerAttributes |
Response Structure | [{
"CustomerID":"string", "ActionID":integer, "ChannelID":integer, "CustomerAttributes":[StringArray], }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomerOneTimeActionsByDate?Date=2018-05-24&CustomerAttributes=Alias;Country |
Sample Response | [
{"CustomerID":"8D871","ActionID":19,"ChannelID":504,"CustomerAttributes":["Yo999","UA"]}, {"CustomerID":"8U76T","ActionID":19,"ChannelID":504,"CustomerAttributes":["Neto2","TR"]} ] |
Notes
- One-time actions are those marketing actions initiated on an ad hoc customer list via the Run Action command on various Optimove reports (as opposed to a pre-defined target group).
- The results may optionally include customer IDs of customers included in the control group (i.e., those who did not actually receive the campaign) – an ActionID value of 1 indicates a member of control group.
- ChannelID is optional. You can see the available ChannelID values here, and you can also retrieve the available execution channel IDs and associated channel names using the GetExecutionChannels function.
GetCustomerOneTimeActionsByCampaign
Returns a list of customers and the details associated with a particular one-time campaign.
URI | https://apiX.optimove.net/current/customers/GetCustomerOneTimeActionsByCampaign |
HTTP Method | GET |
Required Parameters | (integer) CampaignID |
Optional Parameters | (integer) ChannelID
(boolean) IncludeControlGroup (string) CustomerAttributes |
Response Structure | [{
"CustomerID":"string", "RecipientGroupID":RGID, "ActionID":integer, "ChannelID":integer, "CustomerAttributes":[StringArray] }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomerOneTimeActionsByCampaign?CampaignID=242&CustomerAttributes=Alias;Country |
Sample Response | [
{"CustomerID":"8D871","RecipientGroupID":1,"ActionID":19,"ChannelID":504,"CustomerAttributes":["Yo999","UA"]}, {"CustomerID":"8U76T","RecipientGroupID":1,"ActionID":19,"ChannelID":504,"CustomerAttributes":["Neto2","TR"]} ] |
Notes
- By specifying a ChannelID, you can limit the results returned to marketing actions sent via a particular channel. You can see the available ChannelID values here, and you can also retrieve the available execution channel IDs and associated channel names using the GetExecutionChannels function.
- One-time actions are those marketing actions initiated on an ad hoc customer list via the Run Action command on various Optimove reports (as opposed to a pre-defined target group).
- The results may optionally include customer IDs of customers included in the control group (i.e., those who did not actually receive the campaign) – an ActionID value of 1 indicates a member of control group.
GetCustomerAttributeChangers
Returns an array of customer IDs, and their before and after attribute values, for customers whose selected attribute changed from the past period to the current one.
URI | https://apiX.optimove.net/current/customers/GetCustomerAttributeChangers |
HTTP Method | GET |
Required Parameters | (string) ChangedCustomerAttribute |
Optional Parameters | (string) CustomerAttributes |
Response Structure | [{
"CustomerID":"string", "InitialCustomerAttribute":"string", "FinalCustomerAttribute":"string", "CustomerAttributes":[StringArray] }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomerAttributeChangers?ChangedCustomerAttribute=OptimailUnsubscribed&CustomerAttributes=Alias;Country |
Sample Response | [
{"CustomerID":"91342","InitialCustomerAttribute":null,"FinalCustomerAttribute":"SuperBrand","CustomerAttributes":["BuddyZZ","UK"]}, {"CustomerID":"91343","InitialCustomerAttribute":"SuperBrand","FinalCustomerAttribute":"Super Brand, Mega Brand","CustomerAttributes":["Pax65","DE"]} ] |
Notes
- With this request, we support most attributes, but not customer characteristics. For further information, don't hesitate to get in touch with support or your CSM.
- ChangedCustomerAttribute can contain only a single attribute per each call.
- For customers who only appeared in the database after the previous period, the InitialCustomerAttribute returned will be null (as in the sample response above).
- This function is processing-intensive and may not return results immediately.
GetCustomerFutureValues
Returns customer IDs and their current future values.
URI | https://apiX.optimove.net/current/customers/GetCustomerFutureValues |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (integer) LifecycleStageID
OR (string) LifecycleStageID OR (string) CustomerAttribute AND (string) CustomerAttributeValue |
Response Structure | [{
"CustomerID":"string", "FutureValue":double }] |
Sample Requests | https://apiX.optimove.net/current/customers/GetCustomerFutureValues?LifecycleStageID=3
OR https://apiX.optimove.net/current/customers/GetCustomerFutureValues?LifecycleStageID=1,2,3 OR https://apiX.optimove.net/current/customers/GetCustomerFutureValues?CustomerAttribute=Country&CustomerAttributeValue=Australia |
Sample Response | [
{"CustomerID":"631942","FutureValue":342.65}, {"CustomerID":"257938","FutureValue":102.33} ] |
Notes
- This function can be called specifying either LifecycleStageID or CustomerAttribute with CustomerAttributeValue.
- When using LifecycleStageID, a single integer lifecycle stage ID or a string containing multiple comma-separated integer values may be supplied (as shown in the above sample requests).
- The list of lifecycle stage IDs available for this function can be obtained with the GetLifecycleStageList function.
GetCustomerLastActionExecuted
Returns details of the last action executed for a particular customer ID.
URI | https://apiX.optimove.net/current/customers/GetCustomerLastActionExecuted |
HTTP Method | GET |
Required Parameters | (string) CustomerID |
Optional Parameters | (none) |
Response Structure | {
"ActionID":integer, "Date":"date", "Duration":integer, "TargetGroupID":integer } |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomerLastActionExecuted?CustomerID=2872732 |
Sample Response | {"ActionID":428,"Date":"2018-05-24","Duration":7,"TargetGroupID":15} |
GetCustomerActionDetailsByDate
Returns customer IDs and details of the campaigns sent to them on a particular date.
URI | https://apiX.optimove.net/current/customers/GetCustomerActionDetailsByDate |
HTTP Method | GET |
Required Parameters | (date) Date |
Optional Parameters | (none) |
Response Structure | [{
"CustomerID":"string", "RecipientGroupID":RGID, "ActionID":integer, "ChannelID":integer, }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomerActionDetailsByDate?Date=2018-05-10 |
Sample Response | [
{"CustomerID":"231342","RecipientGroupID":1,"ActionID":42,"ChannelID":504}, {"CustomerID":"940023","RecipientGroupID":2,"ActionID":42,"ChannelID":504} ] |
GetCustomersActionEndedByDate
Returns customer IDs and details of the campaigns they received, for action durations which ended on a particular date.
URI | https://apiX.optimove.net/current/customers/GetCustomersActionEndedByDate |
HTTP Method | GET |
Required Parameters | (date) Date |
Optional Parameters | (none) |
Response Structure | [{
"CustomerID":"string", "ActionID":integer, "ChannelID":integer, "Date":"date", "Duration":integer, "TargetGroupID":integer }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomersActionEndedByDate?Date=2018-05-10 |
Sample Response | [
{"CustomerID":"231342","ActionID":428,"ChannelID":504,"Date":"2018-05-03","Duration":7,"TargetGroupID":15}, {"CustomerID":"981002","ActionID":22,"ChannelID":504,"Date":"2018-05-05","Duration":5,"TargetGroupID":34} ] |
GetCustomerExecutionDetailsByCampaign
Returns an array of all customer IDs and the details associated with each customer for a particular campaign ID.
URI | https://apiX.optimove.net/current/customers/GetCustomerExecutionDetailsByCampaign |
HTTP Method | GET |
Required Parameters | (integer) CampaignID |
Optional Parameters | (integer) ChannelID
(string) CustomerAttributes (boolean) IncludeControlGroup |
Response Structure | [{
"CustomerID":"string", "ActionID":integer, "ChannelID":integer, "TemplateID":"string", "ScheduleTime":"DateTime", "PromoCode":"string" "CustomerAttributes":[StringArray] }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomerExecutionDetailsByCampaign?CampaignID=836&CustomerAttributes=Alias;Country&IncludeControlGroup=True |
Sample Response | [
{"CustomerID":"A1342","ActionID":14,"ChannelID":15,"TemplateID":"60","ScheduleTime":"2018-09-01 10:00:00","PromoCode":"FreeShip50","CustomerAttributes":["RhondaP","UK"]}, {"CustomerID":"A9258","ActionID":14,"ChannelID":15,"TemplateID":"60","ScheduleTime":"2018-09-01 10:00:00","PromoCode":"FreeShip50","CustomerAttributes":["JacquesR","FR"]}, {"CustomerID":"A6666","ActionID":1,"ChannelID":100,"TemplateID":"null","ScheduleTime":null,"PromoCode":null,"CustomerAttributes":["CoriR","IL"]} ] |
Notes
- If supplied, CustomerAttributes must contain one or more valid attribute names (see GetCustomerAttributeList) separated by semicolons (;). The values are returned in the same order as the attribute names are specified in the request.
- The customer attribute values returned are the current (latest available) values, not the values on the campaign date.
- If the optional request parameter IncludeControlGroup is set to True, the results returned will include the customer IDs of customers who were included in the campaign's control group (i.e., those customers included in the campaign's target group, but who did not actually receive the campaign). When included, these customers are identified in the response by an ActionID of 1 ChannelID of 100 and TemplateID of -1.
- All times are returned in UTC.
- Channel ID must be provided while calling this function upon receiving an event type 13 notification.
GetCustomerSendDetailsByCampaign
Returns an array of all customer IDs, channel IDs, send times and channel send IDs for a particular campaign ID.
URI | https://apiX.optimove.net/current/customers/GetCustomerSendDetailsByCampaign |
HTTP Method | GET |
Required Parameters | (integer) CampaignID |
Optional Parameters | (boolean) IncludeTemplateIDs |
Response Structure | [{
"CustomerID":"string", "ChannelID":integer, "ScheduledTime":"DateTime", "SendID":"string", "TemplateID":integer }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomerSendDetailsByCampaign?CampaignID =65874&IncludeTemplateIDs=True |
Sample Response | [
{"CustomerID":"231342","ChannelID":15, "ScheduledTime":"2018-05-30 10:30:00","SendID":"HG65D","TemplateID":12}, {"CustomerID":"917251","ChannelID":15, "ScheduledTime":"2018-05-30 11:45:00","SendID":"HG65E","TemplateID":7} ] |
Notes
- The response structure will be different for different channels.
- All times are returned in UTC.
GetCustomerSendDetailsByChannel
Returns an array of all customer IDs, template IDs, send times and customer attributes for a particular combination of channel ID and campaign ID.
URI | https://apiX.optimove.net/current/customers/GetCustomerSendDetailsByChannel |
HTTP Method | GET |
Required Parameters | (integer) ChannelID
(integer) CampaignID |
Optional Parameters | (string) CustomerAttributes |
Response Structure | [{
"CustomerID":"string", "TemplateID":integer, "ScheduledTime":"DateTime", "CustomerAttributes":[StringArray] }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomerSendDetailsByChannel?ChannelID=15&CampaignID=65874&CustomerAttributes=Email;Country |
Sample Response | [
{"CustomerID":"96134","TemplateID":14,"ScheduledTime":"2018-05-30 10:00:00","CustomerAttributes":["jdavis@aol.com","US"]}, {"CustomerID":"13482","TemplateID":14,"ScheduledTime":"2018-05-30 10:00:00","CustomerAttributes":["plsmits@gmail.com","UK"]} ] |
Notes
- Available ChannelID values can be seen here, and you can also retrieve the available execution channel IDs and associated channel names using the GetExecutionChannels function.
- All times are returned in UTC.
GetProcessedCampaignCustomers
Returns an array of all customer IDs and associated promotion codes for a particular campaign ID.
URI | https://apiX.optimove.net/current/customers/GetProcessedCampaignCustomers |
HTTP Method | GET |
Required Parameters | (integer) CampaignID |
Optional Parameters | (none) |
Response Structure | [{
"CustomerID":"string", "PromoCode":"string" }] |
Sample Request | https://apiX.optimove.net/current/customers/GetProcessedCampaignCustomers?CampaignID=6577 |
Sample Response | [
{"CustomerID":"531346","PromoCode":"P6234"}, {"CustomerID":"645612","PromoCode":"P6234"}, {"CustomerID":"645612","PromoCode":"P6234",“P6214”} ] |
GetCurrentlyTargetedCustomers
Returns an array of all customer IDs currently included in one or more campaigns.
URI | https://apiX.optimove.net/current/customers/GetCurrentlyTargetedCustomers |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (none) |
Response Structure | [{
"CustomerID":"string", "CampaignID":integer, "ActionID":integer, "StartDate":"date", "EndDate":"date", }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCurrentlyTargetedCustomers |
Sample Response | [
{"CustomerID":"231342","CampaignID":428,"ActionID":4,"StartDate":"2018-05-30","EndDate":"2018-01-02"}, {"CustomerID":"745611","CampaignID":370,"ActionID":18,"StartDate":"2018-05-30","EndDate":"2018-01-03"} ] |
GetCanceledCampaignCustomers
Returns an array of all customer IDs that had been included in a campaign that was canceled, along with their associated action IDs and promo codes.
URI | https://apiX.optimove.net/current/customers/GetCanceledCampaignCustomers |
HTTP Method | GET |
Required Parameters | (integer) CampaignID |
Optional Parameters | (none) |
Response Structure | [{
"CustomerID":"string", "ActionID":"string", "PromoCode":"string" }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCanceledCampaignCustomers?CampaignID=6574 |
Sample Response | [
{"CustomerID":"231342","ActionID":"4","PromoCode":"A7Bonus"}, {"CustomerID":"463516","ActionID":"4","PromoCode":"A7Bonus"}, {"CustomerID":"463516","ActionID":"4","PromoCode":"A7Bonus",“A9Bonus”} ] |
Note
The data for a cancelled campaign will be available for two hours from the time that the cancellation notification is sent to an event listener registered to receive notice of cancelled campaigns (refer to EventTypeID 4 in RegisterEventListener).
GetCustomerProductDetailsByCampaign
Returns an array of customer IDs and recommended Product IDs for each customer targeted by a particular product recommendation campaign.
URI | https://apiX.optimove.net/current/customers/GetCustomerProductDetailsByCampaign |
HTTP Method | GET |
Required Parameters | (integer) CampaignID |
Optional Parameters | (string) ProductAttributes |
Response Structure | [{
"CustomerID":"string", "ProductID":"string", "ProductAttributes":[StringArray] }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomerProductDetailsByCampaign?CampaignID=271&ProductAttributes="color,style" |
Sample Response | [
{"CustomerID":"231342","ProductID":"jeans12","ProductAttributes":["blue","skinny"]}, {"CustomerID":"624542","ProductID":"jeans12","ProductAttributes":["grey","relaxed"]} ] |
GetCustomerProductDetailsByDate
Returns an array of customer IDs and recommended Product IDs for each customer targeted by any product recommendation campaign on a particular date.
URI | https://apiX.optimove.net/current/customers/GetCustomerProductDetailsByDate |
HTTP Method | GET |
Required Parameters | (date) Date |
Optional Parameters | (string) ProductAttributes |
Response Structure | [{
"CustomerID":"string", "ProductID":"string", "ProductAttributes":[StringArray] }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomerProductDetailsByDate?Date=2018-05-15&ProductAttributes="color,style" |
Sample Response | [
{"CustomerID":"231342","ProductID":"jeans12","ProductAttributes":["blue","skinny"]}, {"CustomerID":"624542","ProductID":"jeans12","ProductAttributes":["grey","relaxed"]} ] |
GetCustomerProductRecommendations
Returns product recommendations (replenishment or recommendation) generated for customers by Optimove.
URI | https://apiX.optimove.net/current/customers/GetCustomerProductRecommendations |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (integer) RecommendationType
(boolean) SuggestedInCampaign (date) StartDate (date) EndDate (string) CustomerID (string) ProductAttributes |
Response Structure | [{
"CustomerID":"string", "ProductID":"string", "RecommendationType":integer, "ProductAttributes":[StringArray] }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomerProductRecommendations?ProductAttributes="color,style" |
Sample Response | [
{"CustomerID":"231342","ProductID":"jeans12","RecommendationType":1,"ProductAttributes":["blue","skinny"]}, {"CustomerID":"624542","ProductID":"jeans12","RecommendationType":1,"ProductAttributes":["grey","relaxed"]} ] |
Notes
- This function returns a maximum of 10 product recommendations, in priority order.
- Valid values for RecommendationType are:
- 1 = Replenishment Reminder
- 2 = Product Recommendation
- Additional custom types can be supported – contact your CSM for details.
- Regarding SuggestedInCampaign:
- If this parameter is set to False or omitted, all product recommendations calculated by Optimove are returned (any supplied StartDate and EndDate values are ignored).
- If this parameter is set to True, only products recommended to customers in Optimove campaigns during the specified date range are returned.
- If this parameter is set to True and date parameters were omitted, products recommended to customers targeted with any Optimove campaign during the past month are returned.
- If CustomerID is specified, then only product recommendations for the individual customer are returned.
GetCampaignInteractionCustomers
Returns an array of Customer IDs and associated details for each customer who performed a particular interaction (generated a particular event) via a particular channel on a particular date.
URI | https://apiX.optimove.net/current/customers/GetCampaignInteractionCustomers |
HTTP Method | GET |
Required Parameters | (date) Date
(integer) ChannelID (integer) EventID |
Optional Parameters | (none) |
Response Structure | [{
"CustomerID":"string", "CampaignID":integer, "TemplateID":integer }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCampaignInteractionCustomers?Date=2018-05-15&ChannelID=15&EventID=2 |
Sample Response | [
{"CustomerID":"231342","CampaignID":1213,"TemplateID":42}, {"CustomerID":"637733","CampaignID":1213,"TemplateID":42} ] |
Notes
- Valid values for EventID are:
- 2 = Opened
- 3 = Clicked
- 4 = Unsubscribed
- 5 = Dropped
- 6 = SpamReport
- 9 = Bounced
- This function is available only for channels that include customer-level metrics. This includes all Optimail and Optipush campaigns (by default), as well as campaigns that were updated using the UpdateCampaignInteractions function.
GetCustomerChannelInteractions
Returns the details of a particular customer’s interactions with campaigns sent during a particular date range.
URI | https://apiX.optimove.net/current/customers/GetCustomerChannelInteractions |
HTTP Method | GET |
Required Parameters | (string) CustomerID
(date) StartDate (date) EndDate |
Optional Parameters | (integer) ChannelID |
Response Structure | [{
"Date":date, "CampaignID":integer, "RecipientGroupID":RGID, "ActionID":integer, "ChannelID":integer, "TemplateID":integer, "EventID":integer }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomerChannelInteractions?CustomerID=841231&StartDate=2018-08-19&EndDate=2018-09-19 |
Sample Response | [
{"Date":"2018-08-20","CampaignID":422,"RecipientGroupID":1,"ActionID":26,"ChannelID":7,"TemplateID":13,"EventID":2}, {"Date":"2018-08-27","CampaignID":428,"RecipientGroupID":1,"ActionID":28,"ChannelID":7,"TemplateID":54,"EventID":2} ] |
Notes
- Valid values for EventID are:
- 2 = Opened
- 3 = Clicked
- 4 = Unsubscribed
- 5 = Dropped
- 6 = SpamReport
- 7 = Bounced
- ChannelID is optional. Available values can be seen here.
GetCustomersActivityEventAttributes
Returns an array of all customer IDs that triggered a particular SDK event on a particular date, along with associated details.
URI | https://apiX.optimove.net/current/customers/GetCustomersActivityEventAttributes |
HTTP Method | GET |
Required Parameters | (date) Date
(integer) EventID |
Optional Parameters | (string) EventParamIDs |
Response Structure | [{
"CustomerID":"string", "Events":[ObjectArray] }] |
Sample Request | https://apiX.optimove.net/current/customers/GetCustomersActivityEventAttributes?Date=2018-11-03&EventID=1104&EventParamIDs=1;2 |
Sample Response | [{
"CustomerID":"231342", "Events": { "id":1104, "name":"deposit", "deposit_status":"Approved", "amount":100 } }] |
Notes
- This function is only relevant for Optimove clients using the Track & Trigger add-on product.
- Date refers to the date of actual customer data and must thus always be earlier than the current date.
- If the optional EventParamIDs is not specified, all event parameters are returned.
- When specified, EventParamIDs must contain one or more valid parameter IDs separated by semicolons (;). Valid values are those returned by calling GetActivityEventList. The values are returned in the same order as the attribute names are specified in the request.
- The event parameter values returned are the latest available values for the specified date (relevant when the same event occurred more than once on the same date).
UpdateCustomerAttributes
Updates attribute values for particular customer IDs.
URI | https://apiX.optimove.net/current/customers/UpdateCustomerAttributes |
HTTP Method | POST |
Request Structure | {
"CustomerNewAttributesValuesList": [{ "CustomerID":"string", "Attributes":[{ "RealFieldName":"string", "Value":"string" }] }],
"CallbackURL":"string" (optional) } |
Response Structure | 'Request was processed. if Callback URL was defined, you will receive a notification with feedback. If Callback URL was not defined, verify updates through the Optimove platform' |
Sample Request | {
"CustomerNewAttributesValuesList": [{ "CustomerID":"0192837821", "Attributes":[{ "RealFieldName":"FavoriteColor", "Value":"Orange" }, "RealFieldName":"Rank", "Value":"Gold" }] }]
"CallbackURL":"https://tenantname.requestcatcher.com/test" } |
Notes
- Attributes are identified by their RealFieldName values. You can retrieve all available customer attribute names and a description of each using the GetCustomerAttributeList function, or by accessing the Customer Attributes list in Optimove’s interface and export the list.
- Attribute values supplied in this call overwrite any previous values in the database.
- Each call may include up to 1,000 customer IDs, with a maximum of 10 attributes per customer ID.
- In order to avoid high volumes of these requests, which may result in delays, it is recommended to only use this call for specific customer attributes, based on your use cases.
- If a Callback URL was defined you will receive the following response to the Webhook up to 1 minute after the call:
- IsSuccess: true or false
- Request ID
- Error in case of failure. Error will consist of error details, customer id and real field name. Possible values for Error in the response:
- 1:“INVALID_CUSTOMER” = Specified CustomerID does not exist
- 2:“INVALID_FIELD” = Specified RealFieldName does not exist
- 3:“INVALID_VALUE” = Specified value is invalid
- 4:“UPDATE_FIELD_TEMPORARY_UNAVIALABLE” = Update for is temporarily unavailable. In case of receiving this error message, please contact Optimove’s support team in order to enable this.
- Please note that using this API call was previously accessed by a different request and responded differently, with a different logic. Starting on June 2023, this API call will support only the documented way.
Examples for reference:
{"isSuccess":false,"errors":[{"error":"UPDATE_FIELD_TEMPORARY_UNAVAILABLE","customerId":"1289049",
"realFieldName":"DaysSinceFirstAbsGameDate"}],"requestId":"77e34963-8142-4fde-a403-ebe03feec41e"}
{"isSuccess":true,"requestId":"0386932e-db94-4567-9d38-76d98ce50e4a"}
RemoveCustomerPII
Causes Optimove to delete all personally identifiable information associated with specified customer IDs.
URI | https://apiX.optimove.net/current/customers/RemoveCustomerPII |
HTTP Method | POST |
Request Structure | {"CustomerIDs":[StringArray]} |
Response Structure | {"FailedCustomerIDs":[StringArray]} |
Sample Request | {"CustomerIDs":["A8272","A916537","A13521","A286571","A792414"]} |
Sample Response | {"FailedCustomerIDs":["A8272","A792414"]} |
Notes
- A maximum of 50,000 customer IDs may be included in one call.
- Response will be an empty array unless there was a failure in erasing the PII of one or more specified customer IDs, in which case the ones that failed will be returned in this array. The most common reason for failure is that the customer ID was not found in Optimove’s database.
- Response will only return failed customer IDs that Optimove has never received previously. Customer IDs that were previously deleted from Optimove and sent again for removal will not be returned.
Value Segment-related Functions
All value segment-related functions are called by appending the function name to the URL prefix https://apiX.optimove.net/current/segments/
GetValueSegmentName
Returns the value segment name associated with a particular value segment ID.
URI | https://apiX.optimove.net/current/segments/GetValueSegmentName |
HTTP Method | GET |
Required Parameters | (integer) ValueSegmentID |
Optional Parameters | (none) |
Response Structure | {"ValueSegmentName":"string"} |
Sample Request | https://apiX.optimove.net/current/segments/GetValueSegmentName?ValueSegmentID=1 |
Sample Response | {"ValueSegmentName":"Diamond"} |
GetValueSegmentID
Returns the value segment ID associated with a particular value segment name.
URI | https://apiX.optimove.net/current/segments/GetValueSegmentID |
HTTP Method | GET |
Required Parameters | (string) ValueSegmentName |
Optional Parameters | (none) |
Response Structure | {"ValueSegmentID":integer} |
Sample Request | https://apiX.optimove.net/current/segments/GetValueSegmentID?ValueSegmentName=Diamond |
Sample Response | {"ValueSegmentID":1} |
GetValueSegments
Returns all defined value segment names and IDs.
URI | https://apiX.optimove.net/current/segments/GetValueSegments |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (none) |
Response Structure | [{
"ValueSegmentName":"string", "ValueSegmentID":integer }] |
Sample Request | https://apiX.optimove.net/current/segments/GetValueSegments |
Sample Response | [
{"ValueSegmentName":"Diamond","ValueSegmentID":1}, {"ValueSegmentName":"Gold","ValueSegmentID":2}, {"ValueSegmentName":"Silver","ValueSegmentID":3}, {"ValueSegmentName":"Bronze","ValueSegmentID":4} ] |
GetCustomersByValueSegment
Returns the list of customer IDs associated with a particular value segment at the current time.
URI | https://apiX.optimove.net/current/segments/GetCustomersByValueSegment |
HTTP Method | GET |
Required Parameters | (integer) ValueSegmentID |
Optional Parameters | (string) CustomerAttributes |
Response Structure | [{
"CustomerID":"string", "CustomerAttributes":[StringArray] }] |
Sample Request | https://apiX.optimove.net/current/segments/GetCustomersByValueSegment?ValueSegmentID=3&CustomerAttributes=Alias;Country |
Sample Response | [
{"CustomerID":"AC7615","CustomerAttributes":["Robin777","ES"]}, {"CustomerID":"FP8721","CustomerAttributes":["JollyPop","UK"]} ] |
GetValueSegmentChangers
Returns all customer IDs in the database which changed value segments, along with their before and after value segment IDs.
URI | https://apiX.optimove.net/current/segments/GetValueSegmentChangers |
HTTP Method | GET |
Required Parameters | (date) StartDate
(date) EndDate |
Optional Parameters | (string) CustomerAttributes |
Response Structure | [{
"CustomerID":"string", "InitialValueSegmentID":integer, "FinalValueSegmentID":integer, "CustomerAttributes":[StringArray] }] |
Sample Request | https://apiX.optimove.net/current/segments/GetValueSegmentChangers?CustomerAttributes=Alias;Country |
Sample Response | [
{"CustomerID":"231342","InitialValueSegmentID":2,"FinalValueSegmentID":3,"CustomerAttributes":["BuddyZZ","UK"]}, {"CustomerID":"931342","InitialValueSegmentID":1,"FinalValueSegmentID":2,"CustomerAttributes":["Pax65","DE"]} ] |
Notes
- The customer IDs returned are those whose value segment changed during the last day for which data is available.
External System Integration Functions
All external system integration-related functions are called by appending the function name to the URL prefix https://apiX.optimove.net/current/integrations/
AddPromotions
Adds promo codes and associated names that will be available for selection when running a campaign.
URI | https://apiX.optimove.net/current/integrations/AddPromotions |
HTTP Method | POST |
Request Structure | [{
"PromoCode":"string", "PromotionName":"string" }] |
Response Structure | (none) |
Sample Request | [
{"PromoCode":"WB23","PromotionName":"Welcome back Promo"}, {"PromoCode":"NV10","PromotionName":"New VIP 10% Discount"} ] |
Sample Response | (none) |
Notes
- If a PromoCode being added already exists, it will be replaced with the PromotionName specified in the call.
- A maximum of 100 promotions may be added with one call.
- Once added, a promotion can be deleted by calling the DeletePromotions function.
- This function does not return a payload. A successful call will return a response code of 200 (success). Refer to an explanation of the other possible response codes at Function Error Response Codes.
GetPromotions
Returns an array of all defined promo codes and associated names.
URI | https://apiX.optimove.net/current/integrations/GetPromotions |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (none) |
Response Structure | [{
"PromoCode":"string", "PromotionName":"string" }] |
Sample Request | https://apiX.optimove.net/current/integrations/GetPromotions |
Sample Response | [
{"PromoCode":"WB23","PromotionName":"Welcome back Promo"}, {"PromoCode":"NV10","PromotionName":"New VIP 10% Discount"} ] |
DeletePromotions
Removes previously added promo codes.
URI | https://apiX.optimove.net/current/integrations/DeletePromotions |
HTTP Method | POST |
Request Structure | [{"PromoCode":"string"}] |
Response Structure | (none) |
Sample Request | [
{"PromoCode":"WB23"}, {"PromoCode":"NV10"} ] |
Sample Response | (none) |
Notes
- A maximum of 100 templates may be deleted with one call.
- This function does not return a payload. A successful call will return a response code of 200 (success). Refer to an explanation of the other possible response codes at Function Error Response Codes.
UpdateCustomerPromotionStatus
Informs Optimove of the status of activated promotions for particular customer IDs for a particular campaign ID.
URI | https://apiX.optimove.net/current/integrations/UpdateCustomerPromotionStatus |
HTTP Method | POST |
Request Structure | {
"TimeStamp":DateTime, "CampaignID":integer, "PromosUpdated":[{ "CustomerID":"string", "Status":boolean }] } |
Response Structure | (none) |
Sample Request | {
"TimeStamp":"2018-10-27 09:33:00", "CampaignID":1359, "PromosUpdated":[ {"CustomerID":"C234638","Status":true}, {"CustomerID":"C984571","Status":true} ] } |
Sample Response | (none) |
Notes
- A maximum of 10,000 customer IDs may be included in one call.
- This function may called as many times as required.
- The campaign will only be sent to customer IDs with Status set to true; if a customer ID is never received by this function, it is the same as if it was sent with Status set to false.
- Once the campaign's specified ClearanceRequiredBy time arrives, Optimove will schedule the campaign for execution only to those customer IDs for which PromosUpdated was specified as true using this API call by that time. For more information about this process, click here.
AddChannelTemplates
Adds template IDs and associated names that will be associated with a specified channel ID.
URI | https://apiX.optimove.net/current/integrations/AddChannelTemplates |
HTTP Method | POST |
Required Parameters | (integer) ChannelID |
Request Structure | [
{ "TemplateID":integer, "TemplateName":"string", "AppID":"string (optional)" } ] |
Response Structure | (none) |
Sample Request | https://apiX.optimove.net/current/integrations/AddChannelTemplates?ChannelID=3 |
Sample Request | [
{"TemplateID":1,"TemplateName":"Welcome Back English"}, {"TemplateID":2,"TemplateName":"Welcome Back Spanish","AppID":"app123"} ] |
Sample Response | (none) |
Notes
- Available ChannelID values can be seen here, and you can also retrieve the available execution channel IDs and associated channel names using the GetExecutionChannels function.
- AppID is optional.
- If a TemplateID being added already exists, it will be replaced with the TemplateName specified in the call.
- A maximum of 100 templates may be added with one call.
- Once added, a template can be deleted by calling the DeleteChannelTemplates function.
- This function does not return a payload. A successful call will return a response code of 200 (success). Refer to an explanation of the other possible response codes at Function Error Response Codes.
GetChannelTemplates
Returns an array of template IDs and associated names for a particular channel.
URI | https://apiX.optimove.net/current/integrations/GetChannelTemplates |
HTTP Method | GET |
Required Parameters | (integer) ChannelID |
Optional Parameters | (none) |
Response Structure | [{
"TemplateID":integer, "TemplateName":"string" }] |
Sample Request | https://apiX.optimove.net/current/integrations/GetChannelTemplates?ChannelID=3 |
Sample Response | [
{"TemplateID":1,"TemplateName":"Welcome Back English"}, {"TemplateID":2,"TemplateName":"Welcome Back Spanish"} ] |
GetChannelTemplateDetails
Returns the content and attributes of a specific template for a specific channel.
URI | https://apiX.optimove.net/current/integrations/GetChannelTemplateDetails |
HTTP Method | GET |
Required Parameters | (integer) TemplateID
(integer) ChannelID |
Optional Parameters | (none) |
Response Structure | [{
"TemplateContent":"string" "TemplateAttributes":[StringArray] }] |
Sample Request | https://apiX.optimove.net/current/integrations/GetChannelTemplateDetails?TemplateID=51&ChannelID=15 |
Sample Response | [
{"TemplateContent":"Hi [%FIRST_NAME%], welcome back!","TemplateAttributes":["From":"John H.","Reply-to":"email@domain.com","Subject":"Welcome back!"]} ] |
DeleteChannelTemplates
Removes previously added channel templates.
URI | https://apiX.optimove.net/current/integrations/DeleteChannelTemplates |
HTTP Method | POST |
Request Structure | [{
"ChannelID":integer, "TemplateID":integer }] |
Response Structure | (none) |
Sample Request | [
{"ChannelID":7,"TemplateID":15}, {"ChannelID":7,"TemplateID":26} ] |
Sample Response | (none) |
Notes
- A maximum of 100 templates may be deleted with one call.
- Available ChannelID values can be seen here, and you can also retrieve the available execution channel IDs and associated channel names using the GetExecutionChannels function.
- This function does not return a payload. A successful call will return a response code of 200 (success). Refer to an explanation of the other possible response codes at Function Error Response Codes.
AddChannelApps
Adds app IDs and associated names that will be available for selection when running a campaign via the specified channel (typically required when using push notification channels).
URI | https://apiX.optimove.net/current/integrations/AddChannelApps |
HTTP Method | POST |
Required Parameters | (integer) ChannelID |
Request Structure | [
{ "AppID":"string", "AppName":"string" } ] |
Response Structure | (none) |
Sample Request | https://apiX.optimove.net/current/integrations/AddChannelApps?ChannelID=3
[ {"AppID":"9c5f496c-392a-45a4-8414-12d42bf1fc8e","AppName":"Bingo Mania"}, {"AppID":"9c5f496c-392a-45a4-8414-2bf1f12d4c3d","AppName":"Super Slots"} ] |
Sample Response | (none) |
Notes
- If an AppID being added already exists, it will be replaced with the AppName specified in the call.
- A maximum of 100 apps may be added with one call.
- Once added, an app can be deleted by calling the DeleteChannelApps function.
- Available ChannelID values can be seen here, and you can also retrieve the available execution channel IDs and associated channel names using the GetExecutionChannels function.
- This function does not return a payload. A successful call will return a response code of 200 (success). Refer to an explanation of the other possible response codes at Function Error Response Codes.
DeleteChannelApps
Removes previously added apps.
URI | https://apiX.optimove.net/current/integrations/DeleteChannelApps |
HTTP Method | POST |
Request Structure | [{
"ChannelID":integer, "AppID":"string" }] |
Response Structure | (none) |
Sample Request | [
{"ChannelID":506,"AppID":"9c5f496c-392a-45a4-8414-12d42bf1fc8e"}, {"ChannelID":506,"AppID":"9c5f496c-392a-45a4-8414-2bf1f12d4c3d"} ] |
Sample Response | (none) |
Notes
- A maximum of 100 apps may be deleted with one call.
- Available ChannelID values can be seen here, and you can also retrieve the available execution channel IDs and associated channel names using the GetExecutionChannels function.
- This function does not return a payload. A successful call will return a response code of 200 (success). Refer to an explanation of the other possible response codes at Function Error Response Codes.
AddExternalRealtimeTriggers
Defines one or more realtime triggers handled by an external system so that they are selectable by users for realtime campaigns within the Optimove UI.
URI | https://apiX.optimove.net/current/integrations/AddExternalRealtimeTriggers |
HTTP Method | POST |
Request Structure | [{
"TriggerID":"string" "TriggerName":"string" }] |
Response Structure | (none) |
Sample Request | [
{"TriggerID":"R20","TriggerName":"Rolled Box Cars"}, {"TriggerID":"R21","TriggerName":"Rolled Snake Eyes"} ] |
Sample Response | (none) |
Notes
- A maximum of 100 triggers may be added with one call.
- This function does not return a payload. A successful call will return a response code of 200 (success). Refer to an explanation of the other possible response codes at Function Error Response Codes.
GetExternalRealtimeTriggers
Returns an array of defined external realtime trigger IDs and associated names.
URI | https://apiX.optimove.net/current/integrations/GetExternalRealtimeTriggers |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (none) |
Response Structure | [{
"TriggerID":"string", "TriggerName":"string" }] |
Sample Request | https://apiX.optimove.net/current/integrations/GetExternalRealtimeTriggers |
Sample Response | [
{"TriggerID":"R20","TriggerName":"Rolled Box Cars"}, {"TriggerID":"R21","TriggerName":"Rolled Snake Eyes"} ] |
GetActivityEventList
Returns all available custom SDK events with each event parameter's name and type.
URI | https://apiX.optimove.net/current/integrations/GetActivityEventList |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (none) |
Response Structure | [{
"ID":integer, "Name":"string", "Event_Parameters":"[ObjectArray]" }] |
Sample Request | https://apiX.optimove.net/current/integrations/GetActivityEventsList |
Sample Response | [{
"ID":1001, "Name":"Set user ID Predefined event", "Event_Parameters":[ { "id":1, "name":"Original Visitor ID", "type":"String" }, { "id":2, "name":"UserID", "type":"String" } ] }] |
UpdateCampaignMetrics
Reports to Optimove post-execution metrics for campaigns executed by a third-party marketing execution system.
URI | https://apiX.optimove.net/current/integrations/UpdateCampaignMetrics |
HTTP Method | POST |
Request Structure | [{
"ChannelID":integer, "CampaignID":integer, "TemplateID":integer, "MetricID":integer, "MetricValue":integer, "RecipientGroupID":RGID (optional) }] |
Response Structure | (none) |
Sample Request | [
{"ChannelID":15,"CampaignID":42,"TemplateID":8,"MetricID":0,"MetricValue":925}, {"ChannelID":15,"CampaignID":42,"TemplateID":8,"MetricID":1,"MetricValue":809}, {"ChannelID":15,"CampaignID":42,"TemplateID":8,"MetricID":2,"MetricValue":250}, {"ChannelID":15,"CampaignID":42,"TemplateID":8,"MetricID":3,"MetricValue":122}, {"ChannelID":15,"CampaignID":42,"TemplateID":8,"MetricID":4,"MetricValue":11} ] |
Sample Response | (none) |
Notes
- Valid values for MetricID are:
- 0 = Number sent
- 1 = Number delivered
- 2 = Number opened
- 3 = Number clicked
- 4 = Number unsubscribed
- 5 = Number dropped
- 6 = Number of spam reports
- 9 = Number bounced
- Reported metrics are stored by campaign execution date.
- When not supplied, RecipientGroupID defaults to 1, which is the test group in case of a test/control campaign or the A group in the case of an A/B campaign.
- Available ChannelID values can be seen here, and you can also retrieve the available execution channel IDs and associated channel names using the GetExecutionChannels function.
- This function can be called as often as is desired; the most up-to-date values received for the campaign’s individual metrics will be displayed in the campaign analysis report.
- This function does not return a payload. A successful call will return a response code of 200 (success). Refer to an explanation of the other possible response codes at Function Error Response Codes.
UpdateCampaignInteractions
Reports to Optimove customer interactions with campaigns executed by a third-party marketing execution system.
URI | https://apiX.optimove.net/current/integrations/UpdateCampaignInteractions |
HTTP Method | POST |
Request Structure | {
"CampaignID":integer, "ChannelID":integer, "InteractionDate":"date", "TemplateID":integer, "EventID":integer, "CustomerIDs":[StringArray], "RecipientGroupID":RGID (optional), "AppID":"string (optional)" } |
Response Structure | (none) |
Sample Request |
{"CampaignID":324,"ChannelID":15,"InteractionDate":"2018-06-26","TemplateID":8,"EventID":2,"RecipientGroupID":2,"CustomerIDs":["A8272","A916537","A13521","A286571","A792414"],"AppID":"app123"} |
Sample Response | (none) |
Notes
- Valid values for EventID are:
- 2 = Opened
- 3 = Clicked
- 4 = Unsubscribed
- 5 = Dropped
- 6 = Spam report
- 9 = Bounced
- When not supplied, RecipientGroupID defaults to 1, which is the test group in case of a test/control campaign or the A group in the case of an A/B campaign.
- The CustomerIDs array may contain a maximum of 10,000 rows (customers) each time this function is called.
- Available ChannelID values can be seen here, and you can also retrieve the available execution channel IDs and associated channel names using the GetExecutionChannels function.
- This function should be called upon each new campaign interaction. Upon multiple calls with the same parameters, Optimove will aggregate the number of interactions based on the provided data. This will allow users to have the campaign analysis channel metrics as clickable numbers. Once clicked, the list of interacted customer will be displayed in Optimove’s customer explorer.
- This function does not return a payload. A successful call will return a response code of 200 (success). Refer to an explanation of the other possible response codes at Function Error Response Codes.
SetCustomerChannelPreference
Set communication mode for particular customer IDs for particular channels.
URI | https://apiX.optimove.net/current/integrations/SetCustomerChannelPreference |
HTTP Method | POST |
Request Structure | {
"ChannelID":integer, "CustomerIDs":[StringArray], "CommunicationMode":integer, "AppID":"string (optional)" } |
Response Structure | (none) |
Sample Request | {"ChannelID":15,"CustomerIDs":["A8272","A916537","A13521","A286571","A792414"],"CommunicationMode":2,"AppID":"app123"} |
Sample Response | (none) |
Notes
- Valid values for CommunicationMode are:
- 1 = Allowed
- 2 = Not allowed / Unsubscribed
- The CustomerIDs array may contain a maximum of 50,000 rows (customers) each time this function is called.
- Available ChannelID values can be seen here, and you can also retrieve the available execution channel IDs and associated channel names using the GetExecutionChannels function.
- This function does not return a payload. A successful call will return a response code of 200 (success). Refer to an explanation of the other possible response codes at Function Error Response Codes.
- Preference data will not be visible in your Optimove instance by default.
In order to add it, please contact your CSM.
Optimail Functions
All Optimail mail functions are called by appending the function name to the URL prefix https://apiX.optimove.net/current/optimail/
GetEmailParameters
Returns all available parameters for use with Optimail templates for a particular brand.
URI | https://apiX.optimove.net/current/optimail/GetEmailParameters |
HTTP Method | GET |
Required Parameters | (integer) BrandID |
Optional Parameters | (none) |
Response Structure | {
"BrandID":integer, "PersonalizationTags":[string array], "FromEmailAddresses":[{ "id":integer, "email":"string" }], "ReplyToAddresses":[{ "id":integer, "email":"string" }], "PreferenceGroups":[{ "id":integer, "name":"string", "description":"string" }] } |
Sample Request | https://apiX.optimove.net/current/optimail/GetEmailParameters?BrandID=4 |
Sample Response | {
"BrandID":4, "PersonalizationTags":[ "[%EMAIL%]", "[%FIRST_NAME%]", "[%LAST_NAME%]", "[%PROMO%]", "[%LOWER:YOUR_TAG1%]", "[%UPPER:YOUR_TAG2%]", "[%CURRENT_TIME:TIME_FORMAT%]", "[%CURRENT_DATE:DATE_FORMAT%]" ], "FromEmailAddresses":[ {"id":1, "email":"sales@thisshop.com"}, {"id":2, "email":"service@thisshop.com"} ], "ReplyToAddresses":[ {"id":1, "email":"qateam@thisshop.com"} ], "PreferenceGroups":[ {"id":128009, "name":"Newsletter", "description":"Keep updated about all our latest news and special offers."} ] } |
GetTemplateFolders
Returns the names and IDs of all Optimail template folders for a particular brand.
URI | https://apiX.optimove.net/current/optimail/GetTemplateFolders |
HTTP Method | GET |
Required Parameters | (integer) BrandID |
Optional Parameters | (integer) ParentFolderID |
Response Structure | {
"BrandID":integer, "Folders":[{ "ID":integer, "Name":"string", "ParentFolderID":integer }] } |
Sample Request | https://apiX.optimove.net/current/optimail/GetTemplateFolders?BrandID=4&ParentfolderID=3321 |
Sample Response | {
"BrandID":4, "Folders":[ {"ID":100004,"Name":"Test 1","ParentFolderID": 3321}, {"ID":100046,"Name":"Test 2","ParentFolderID": 3321} ] } |
Note
If ParentFolderID is included in the request, the response will include only Optimail template folders located in the specified parent folder, and not templates located in any subfolders of the specified folder.
AddTemplate
Creates a new Optimail template.
URI | https://apiX.optimove.net/current/optimail/AddTemplate |
HTTP Method | POST |
Request Structure | {
"TemplateName":"string", "Subject":"string", "HTML":"string", "PlainText":"string (optional)", "FromName":"string", "ReplyToAddressID":integer, "FromEmailAddressID":integer, "FolderID":integer, "PreferenceGroupID":integer (optional) } |
Response Structure | {
"TemplateID":integer } |
Sample Request | {
"TemplateName":"GIF Lovers", "Subject":"Hello GIF Lovers", "Html":"<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>GIF with a hard G</title> </head> <body style=\"min-height:325px;\"><img src=\"https://d31v04zd2.cloudfront.net/blog/wp-content/uploads/2014/03/loft-unwrap-animation-repeat.gif\" width=\"100\" height=\"100\" alt=\"GIF with a hard G\" border=\"0\" class=\"fr-dii fr-draggable\" style=\"float:none;\"></body> </html>", "PlainText":"GIF with a hard G", "FromName":"GIF World", "ReplyToAddressID":2, "FromEmailAddressID":3, "FolderID":104176, "PreferenceGroupID":128009 } |
Sample Response | {
"TemplateID":9481 } |
UpdateTemplate
Updates an existing Optimail template.
URI | https://apiX.optimove.net/current/optimail/UpdateTemplate |
HTTP Method | POST |
Request Structure | {
"TemplateID":integer, "TemplateName":"string (optional)", "Subject":"string (optional)", "HTML":"string (optional)", "PlainText":"string (optional)", "FromName":"string (optional)", "FromEmailAddressID":integer (optional), "ReplyToAddressID":integer (optional), "FolderID":integer (optional), "PreferenceGroupID":integer (optional) } |
Response Structure | (none) |
Sample Request | {
"TemplateID":9481, "TemplateName":"GIF Lover's Paradise", "Subject":"GIF Lover's Paradise", "PreferenceGroupID":128009 } |
Sample Response | (none) |
Notes
Any optional fields not specified when calling this function will remain unchanged in the template.
AddUnsubscribers
Adds one or more email addresses to a global unsubscribe list of a particular brand.
URI | https://apiX.optimove.net/current/optimail/AddUnsubscribers |
HTTP Method | POST |
Request Structure | {
"BrandId": integer, "EmailAddresses": ["String"] } |
Response Structure | {
"Error": "String" } |
Sample Request | {
"BrandId": 4, "EmailAddresses": ["adam@somedomain.com" ,"ben@somedomain.com" ,"suzanne@somedomain.com" ,"michael@somedomain.com" ,"ron@somedomain.com"] } |
Sample Response | {"Error":null}
{"Error":"Invalid email"} |
Notes
- BrandID – The ID of your Optimail account (if you don't have this ID, contact your CSM).
- Error – A description of the error. When the send succeeds, null is returned.
- Each call may include a maximum of 200 email.
- This function supports a maximum of 10 calls in parallel.
- This API call supports a maximum of 600 requests/min
DeleteUnsubscribers
Deletes one email addresses from the global unsubscribe list of a particular brand.
URI | https://apiX.optimove.net/current/optimail/DeleteUnsubscribers |
HTTP Method | POST |
Request Structure | {
"BrandId": integer, "EmailAddress": "String" } |
Response Structure | {
"Error": "String" } |
Sample Request | {
"BrandId": 4, "EmailAddress": "michael@somedomain.com" } |
Sample Response | {"Error":null}
{"Error":"Invalid email"} |
Notes
- BrandID – The ID of your Optimail account (if you don't have this ID, contact your CSM).
- Error – A description of the error. When the send succeeds, null is returned.
- This function supports a maximum of 10 calls in parallel
- This API call supports a maximum of 600 requests/min
GetUnsubscribers
Allows to retrieve email addresses that are a part of a global unsubscribe list of a particular brand.
URI | https://apiX.optimove.net/current/optimail/GetUnsubscribers |
HTTP Method | GET |
Required Parameters | (integer) BrandID |
Optional Parameters | (date) StartDate (date) EndDate |
Response Structure | [{
"Email":"String" }] |
Sample Request | https://apiX.optimove.net/current/optimail/GetUnsubscribers?BrandID=4&StartDate=2020-03-16&EndDate=2020-03-17 |
Sample Response | [
{"Email":"michael@somedomain.com", "UnsubscribedTime":2020-03-16 08:00:00}, ] |
Notes
- BrandID – The ID of your Optimail account (if you don't have this ID, contact your CSM)
- This function supports a maximum of 10 calls in parallel
- A maximum page size of 10 thousand (10,000) results is allowed. To request subsequent pages of results, repeat the request with the additional parameter $skip=n where n is the number of resulting records of the entire result set to skip over when returning the current page.
- StartDate and EndDate refers to the date range when an unsubscribe email was created (inclusive)
- If StartDate and EndDate are not provided the response will include the entire list
- StartDate and EndDate parameters must be formatted exactly as depicted above
- All times are returned in UTC
Transactional Mail Functions
All transactional mail functions are called by appending the function name to the URL prefix https://apiX.optimove.net/current/transactionalmail/
SendTransactionalMail
Sends a specific transactional email template to a list of recipients.
URI | https://apiX.optimove.net/current/transactionalmail/SendTransactionalMail |
HTTP Method | POST |
Request Structure | {
"TemplateID":integer, "ScheduleTime":"DateTime", "Recipients":[{ "Email":"string", "Personalizations":[{ "Tag":"string", "Value":"string" }] }], "Bcc" (optional):[{ "Email":"string", "Name":"string" }], "Attachments" (optional):[{ "Content":"string", "Type":"string", "FileName":"string" }], "UniqueMessageID" (optional):"string" } |
Response Structure | {
"IsSuccess":boolean, "SendID":integer, "Error":"string" } |
Sample Request | {
"TemplateID":127, "ScheduleTime":"2019-12-14 09:31:00", "Recipients":[ {"Email":"vivi@somedomain.com", "Personalizations":[ {"Tag":"[%TRANS:FIRST_NAME%]","Value":"Vivienne"}, {"Tag":"[%TRANS:FAVORITE_GAME%]","Value":"Bingo Mania"} ] }, {"Email":"tommy@somedomain.com", "Personalizations":[ {"Tag":"[%TRANS:FIRST_NAME%]","Value":"Tommy"}, {"Tag":"[%TRANS:FAVORITE_GAME%]","Value":"Lucky Slots"} ] } ], "Bcc":[{ "Email":"adam@somedomain.com", "Name":"Adam" }], "Attachments":[{ "Content":"/*Base64 Encoded Content*/", "Type":"application/pdf", "FileName":"receipt.pdf" }], "UniqueMessageID" (optional):"87ba42c0-9431-4266-b808-01cf05867006" } |
Sample Response | {"IsSuccess":true,"SendID":235311,"Error":null}
{"IsSuccess":false,"SendID":null,"Error":"Invalid template"} |
Notes
- TemplateID is the transactional template identifier, defined by Optimove (this ID can be found in the Optimove UI, when viewing the template in the Manage Templates page).
- ScheduleTime is optional, and must be specified in UTC. If not provided, the email will be sent immediately.
- The Personalizations array is optional. Multiple personalization tags may be provided for each recipient. Each Personalizations block is limited to 10,000 bytes.
- In the case that personalization tags were not sent as part of the Personalizations array, but are located within the template, the missing tags will populate with an empty value within the email body and the transactional email will be successfully sent. For example, if you have a template which includes “Hi [%TRANS:FIRST_NAME%],” and this tag is not received in the API call then the email will go out simply as “Hi.” In such cases, the response code received will be 206 (partial content) success status. Also, an error message will be received noting the missing tags. To avoid incorrect content from being sent to your customers, within the email body, conditional language can be used to validate whether a given tag has been populated with an empty value or not and dynamically change the content accordingly on a given mail send.
- Type specifies the MIME type of the attachment (e.g., "text/plain", "text/html", "application/pdf")
- UniqueMessageID enforces idempotency. This is limited to 254 characters.
- IsSuccess – true is returned if the send was successful. Otherwise, false.
- SendID – If the send failed, null is returned.
- Error – A description of the error. When the send succeeds, null is returned. If the specified template is invalid, Error contains "Invalid template". If idempotency is enforced a 409 error code shows with the following message "Request for this UniqueMessageID has succeeded before".
- Each call may include a maximum of 200 email recipients.
- This function supports a maximum of 10 calls per second.
SendFinalizedTransactionalMail
Sends a transactional email template, containing your custom HTML content, to a list of recipients.
URI | https://apiX.optimove.net/current/transactionalmail/SendFinalizedTransactionalMail |
HTTP Method | POST |
Request Structure | {
"BrandID":integer, "FromEmail":"string", "FromName":"string", "ReplyTo":"string", "Subject":"string", "Html":"string", "PlainText":"string", "Recipients":[{ "Email":"string" }], "Attachments" (optional):[{ "Content":"string", "Type":"string", "FileName":"string" }], "UniqueMessageID" (optional):"string" } |
Response Structure | {
"IsSuccess":boolean, "SendID":integer, "Error":"string" } |
Sample Request | {
"BrandID":99, "FromEmail":"news@lovley.com", "FromName":"Lovely.com", "ReplyTo":"news@lovley.com", "Subject":"Check out today's hot deals!", "Html":"html content goes here", "PlainText":"plain text content goes here", "Recipients":[ {"Email":"vivi@somedomain.com"}, {"Email":"tommy@somedomain.com"} ], "Attachments":[{ "Content":"/*Base64 Encoded Content*/", "Type":"application/pdf", "FileName":"hotdealcoupons.pdf" }], "UniqueMessageID" (optional):"87ba42c0-9431-4266-b808-01cf05867006" } |
Sample Response | {"IsSuccess":true,"SendID":235311,"Error":null}
{"IsSuccess":false,"SendID":null,"Error":"Invalid template"} |
Notes
- BrandID – The ID of your transactional account (if you don't have this ID, contact your CSM).
- Type – The MIME type of the attachment (e.g., "text/plain", "text/html", "application/pdf").
- UniqueMessageID enforces idempotency. This is limited to 254 characters.
- IsSuccess – true is returned if the send was successful. Otherwise, false.
- SendID – If the send failed, null is returned.
- Error – A description of the error. When the send succeeds, null is returned. If the specified template is invalid, Error contains "Invalid template". If idempotency is enforced a 409 error code shows with the following message "Request for this UniqueMessageID has succeeded before".
- Each call may include a maximum of 200 email recipients.
- This function supports a maximum of 10 calls in parallel.
GetTransactionalTemplateMetrics
Returns post-execution metrics for a specific transactional mail template over time.
URI | https://apiX.optimove.net/current/transactionalmail/GetTransactionalTemplateMetrics |
HTTP Method | GET |
Required Parameters | (integer) TemplateID |
Optional Parameters | (integer) LastNumberOfDays |
Response Structure | {
"TemplateID":integer, "Sent":integer, "Delivered":integer, "Opened":integer, "Clicked":integer } |
Sample Request | https://apiX.optimove.net/current/transactionalmail/GetTransactionalTemplateMetrics?TemplateID=271&LastNumberOfDays=30 |
Sample Response | {"TemplateID":127,"Sent":2000, "Delivered":1988,"Opened":265,"Clicked":142} |
Notes
- The optional LastNumberOfDays parameter specifies for how many days back in time results are provided. Acceptable values are 1-60. If omitted, the default value of 7 is used.
- TemplateID is the transactional template identifier, defined by Optimove (this ID can be found in the Optimove UI, when viewing the template in the Manage Templates page).
- Sent, delivered, opened and clicked are the unique number of times the specific template was sent, delivered, opened and clicked, respectively, by each individual recipient.
GetTransactionalUserMetrics
Returns post-execution transactional email metrics for a specific recipient.
URI | https://apiX.optimove.net/current/transactionalmail/GetTransactionalUserMetrics |
HTTP Method | GET |
Required Parameters | (string) Email |
Optional Parameters | (integer) LastNumberOfDays |
Response Structure | {
"MetricsList":[{ "TemplateID":integer, "Sent":integer, "Delivered":integer, "Opened":integer, "Clicked":integer }] } |
Sample Request | https://apiX.optimove.net/current/transactionalmail/GetTransactionalUserMetrics?Email=opalp@somedomain.com&LastNumberOfDays=30 |
Sample Response | {"MetricsList":[
{"TemplateID":127,"Sent":18,"Delivered":18,"Opened":15,"Clicked":4}, {"TemplateID":129,"Sent":4,"Delivered":4,"Opened":1,"Clicked":0} ]} |
Notes
- The optional LastNumberOfDays parameter specifies for how many days back in time results are provided. Acceptable values are 1-60. If omitted, the default value of 7 is used.
- TemplateID is the transactional template identifier, defined by Optimove (this ID can be found in the Optimove UI, when viewing the template in the Manage Templates page).
GetTemplateDetails
Returns an array of transactional template IDs and associated attributes.
URI | https://apiX.optimove.net/current/transactionalmail/GetTemplateDetails |
HTTP Method | GET |
Required Parameters | (none) |
Optional Parameters | (none) |
Response Structure | [{
"TemplateID":integer, "TemplateName":"string", "TemplateContent":"string", "TemplateAttributes":[StringArray] }] |
Sample Request | https://apiX.optimove.net/current/transactionalmail/GetTemplateDetails |
Sample Response | [
{ "TemplateID":1, "TemplateName":"Welcome Back English", "TemplateContent":"Hi [%FIRST_NAME%], welcome back!", "TemplateAttributes":[ "Lovely","marketing@lovely.com","Welcome back!" ], }, { "TemplateID":2, "TemplateName":"Welcome Back Spanish", "TemplateContent":"¡Hola [%FIRST_NAME%], bienvenido de nuevo!", "TemplateAttributes":[ "Lovely","marketing@lovely.com","Bienvenido de nuevo!" ] } ] |
Notes
- This function returns the details of all defined Optimail email templates.
- TemplateAttributes returns a StringArray containing the following three strings, in the following order:
- From name
- Reply-to
- Subject