Optimove API Usage Guide

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

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

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

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

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

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.

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.

  • For all event types (except event type 11) we offer authentication method using Authorization Header

    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"}

    ]

    All model-related functions are called by appending the function name to the URL prefix https://apiX.optimove.net/current/model/

    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"}

    ]

    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"}

    ]

    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}

    ]

    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.

    All action-related functions are called by appending the function name to the URL prefix https://apiX.optimove.net/current/actions/

    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"}

    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}

    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"}

    ]

    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}

    ]

    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"}

    ]

    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"}

    ]

    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"}

    ]

    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.

    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.

    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.

    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"}

    ]

    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.

    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"}

    ]

    All target group-related functions are called by appending the function name to the URL prefix https://apiX.optimove.net/current/groups/

    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"}

    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}

    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.

    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}

    ]

    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.

    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."}

    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"]}

    ]

    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.

    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.

    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.

    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.

    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.

    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}

    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}

    ]

    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}

    ]

    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.

    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.

    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.

    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”}

    ]

    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"}

    ]

    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).

    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"]}

    ]

    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"]}

    ]

    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.

    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.

    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.

    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).

    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"}

    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.

    All value segment-related functions are called by appending the function name to the URL prefix https://apiX.optimove.net/current/segments/

    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"}

    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}

    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}

    ]

    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"]}

    ]

    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":"&lt!DOCTYPE html&gt<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"
    "UnsubscribedTime":"DateTime"

    }]
    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},
    {"Email":"suzanne@somedomain.com", "UnsubscribedTime":2020-03-17 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