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

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 the Campaign ID and Template ID for each customer who performed a particular interaction with a campaign that was delivered on a particular date via a particular channel
GetCustomerChannelInteractions
Returns the details of a particular customer’s interactions with campaigns sent during a particular date range
GetExternalRealtimeCampaignCustomers
Returns an array of all customer IDs scheduled to receive a realtime campaign by an external system on a particular date, along with associated details
GetCustomerActivityEventAttributes
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

Transactional Mail Functions

SendTransactionalMail
Sends a specific transactional email template 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

 

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. 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: W-tZNPVf0e0V_JlDSeNNl_t28Q6cPYX4
    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.

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 witn an expired authentication token, HTTP response code 403 (Authorization-Token Expired) 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).

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

"W-tZNPVf0e0V_JlDSeNNl_t28Q6cPYX4"

Notes

  • Refer to this GitHub repository for diagrammic use cases of how the Login function should be used.
  • 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.

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
    • 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)
    • 11 = A triggered campaign has been executed via an API channel (Note: This event type is only relevant for Optimove clients using Track & Trigger)
  • ChannelID is optional. Available 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,

    "channelID":x,

    "promoCode":x,

    "templateID":x,

    "TimeStamp":"YYYY-MM-DD HH:MM:SS",

    "personalization":{

    personalInfo:{tagName:'val'},

    eventName:{eventParam:'val'}

    }

    }

    Note: Personalization values will only be included if defined in the campaign:

    personalInfo – may be one more personalization fields defined in the Optimove database

    eventName – may be one or more defined events that are part of the campaign's trigger

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":integer,

"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.
  • The results may optionally include one or more (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.

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

]

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

]

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:
    • Successful
    • Not Run
    • 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",

"Tags":[StringArray],

"Error":"string"

}

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

"Tags":["Reactivated to Active","PromotionBoost"],

"Error":""

}

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 available execution channels.

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":integer,

"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 (the GMT time zone).

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":integer

}]

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.

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

]

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 specified date.

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.
  • The results may also optionally include one or more (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.
  • 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.
  • The results may also optionally include one or more (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.

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.
  • The results may also optionally include one or more (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.

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

  • This function will only support three changed customer attribute fields (user selectable – contact your CSM).
  • For customers who only appeared in the database after the previous period, the InitialCustomerAttribute returned will be null (as in the sample response above).
  • The results may also optionally include one or more (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.
  • 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

Response Structure

 [{

"CustomerID":"string",

"ActionID":integer,

"ChannelID":integer,

"TemplateID":integer,

"ScheduleTime":"DateTime",

"PromoCode":"string"

"CustomerAttributes":[StringArray]

}]

Sample Request

https://apiX.optimove.net/current/customers/GetCustomerExecutionDetailsByCampaign?CampaignID=836&CustomerAttributes=Alias;Country

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

]

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.
  • All times are returned in UTC (the GMT time zone).

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 (the GMT time zone).

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 (the GMT time zone).

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

]

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":integer,

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

]

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
  • 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 the Campaign ID and Template ID for each customer who performed a particular interaction with a campaign that was delivered on a particular date via a particular channel.

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
  • 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
  • ChannelID is optional. Available values can be seen here.

Returns an array of all customer IDs scheduled to receive a realtime campaign by an external system on a particular date, along with associated details.

URI

https://apiX.optimove.net/current/customers/GetExternalRealtimeCampaignCustomers

HTTP Method

GET

Required Parameters

(date) ExecutionDate

(integer) CampaignID

Optional Parameters

(string) CustomerAttributes

Response Structure

 [{

"CustomerID":"string",

"CampaignID":integer,

"TriggerID":integer,

"ActionID":integer,

"TargetGroupID":integer,

"RecipientGroupID":RGID,

"PromoCode":"string",

"CustomerAttributes":[StringArray]

}]

Sample Request

https://apiX.optimove.net/current/customers/GetExternalRealtimeCampaignCustomers?ExecutionDate=2018-07-24&CampaignID=22653&CustomerAttributes=Alias;Country

Sample Response

 [

{"CustomerID":"231342","CampaignID":22653,"TriggerID":4,"ActionID":44,"RecipientGroupID":12,"PromoCode":"508","CustomerAttributes":["BuddyZZ","UK"]},

{"CustomerID":"927333","CampaignID":22653,"TriggerID":4,"ActionID":44,"RecipientGroupID":12,"PromoCode":"508","CustomerAttributes":["Pax65","DE"]}

]

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 specified date.

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/GetCustomerActivityEventAttributes

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/GetCustomerActivityEventAttributes?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

 [

{

"CustomerID":"string",

"Attributes":[{

"RealFieldName":"string",

"Value":"string"

}]

}

]

Response Structure

{

"Errors":[{

"CustomerID":"string",

"RealFieldName":"string",

"Value":"string",

"Error":integer

}]

}

Sample Request

 [

{

"CustomerID":"0192837821",

"Attributes":[

{"RealFieldName":"favoriteColor","Value":"orange"},

{"RealFieldName":"rank","Value":"3"}

]

},

{

"CustomerID":"9281928374",

"Attributes":[

{"RealFieldName":"favoriteColor","Value":"blue"},

{"RealFieldName":"rank","Value":"2"}

]

}

]

Sample Response

{

"Errors":[{

"CustomerID":"opt__0368787878",

"RealFieldName":"rank",

"Value":"1",

"Error":1

}]

}

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.
  • 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.
  • It is not recommended to use this call for time-sensitive user updates, as there may be a delay before the updates are fully processed, due to occasionally high volumes of these requests.
  • Possible values for Error in the response:
    • 1 = Specified CustomerID does not exist
    • 2 = Specified RealFieldName does not exist
    • 3 = Specified value is invalid

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.

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?ValueSegmentID=Diamond

Sample Response

{"ValueSegmentName":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"]}

]

Notes

  • The results may also optionally include one or more (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.

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

(none)

Optional Parameters

(date) StartDate

(date) EndDate

(string) CustomerAttributes

Response Structure

 [{

"CustomerID":"string",

"InitialValueSegmentID":integer,

"FinalValueSegmentID":integer,

"CustomerAttributes":[StringArray]

}]

Sample Request

https://apiX.optimove.net/current/segments/GetValueSegmentChangers?StartDate=2018-03-01&EndDate=2018-05-30&CustomerAttributes=Alias;Country

Sample Response

 [

{"CustomerID":"231342","InitialValueSegmentID":2,"FinalValueSegmentID":3,"CustomerAttributes":["BuddyZZ","UK"]},

{"CustomerID":"931342","InitialValueSegmentID":1,"FinalValueSegmentID":2,"CustomerAttributes":["Pax65","DE"]}

]

Notes

  • If dates are supplied, the range must be within the prior two days in order to receive results.
  • The InitialValueSegmentID returned will be -1 for any customer that wasn't a customer on the specified StartDate.
  • The results may also optionally include one or more (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.

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 50,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.
  • When 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
  • 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; an up-to-date aggregation of all received metrics for the campaign 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
  • 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 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 can be called as often as is desired; the latest received interactions will be displayed in the Optimove's 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.

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.

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"

}]

}

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

]

}

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

(none)

Response Structure

{

"BrandID":integer,

"Folders":[{

"id":integer,

"name":"string"

}]

}

Sample Request

https://apiX.optimove.net/current/optimail/GetTemplateFolders?BrandID=4

Sample Response

{

"BrandID":4,

"Folders":[

{"id":100004, "name":"Test 1"},

{"id":100046, "name":"Test 2"}

]

}

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

}

Response Structure

{

"TemplateID":integer

}

Sample Request

{

"TemplateName":"GIF Lovers",

"Subject":"Hello GIF Lovers",

"Html":"<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>GIF with a hard G</title>

</head>

<body style=\"min-height:325px;\"><img src=\"https://d31v04zd2.cloudfront.net/blog/wp-content/uploads/2014/03/loft-unwrap-animation-repeat.gif\" width=\"100\" height=\"100\" alt=\"GIF with a hard G\" border=\"0\" class=\"fr-dii fr-draggable\" style=\"float:none;\"></body>

</html>",

"PlainText":"GIF with a hard G",

"FromName":"GIF World",

"ReplyToAddressID":2,

"FromEmailAddressID":3,

"FolderID":104176

}

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)

}

Response Structure

(none)

Sample Request

{

"TemplateID":9481,

"TemplateName":"GIF Lover's Paradise",

"Subject":"GIF Lover's Paradise"

}

Sample Response

(none)

Notes

Any optional fields not specified when calling this function will remain unchanged in the template.

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 transactional email 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"

}]

}]

}

Response Structure

{

"IsSuccess":boolean,

"SendID":integer,

"Error":"string"

}

Sample Request

{

"TemplateID":127,

"ScheduleTime":"2018-02-14 09:31:00",

"Recipients":[

{"Email":"vivi@somedomain.com",

"Personalizations":[

{"Tag":"[%FIRST_NAME%]","Value":"Vivienne"},

{"Tag":"[%FAVORITE_GAME%]","Value":"Bingo Mania"}

]

},

{"Email":"tommy@somedomain.com",

"Personalizations":[

{"Tag":"[%FIRST_NAME%]","Value":"Tommy"},

{"Tag":"[%FAVORITE_GAME%]","Value":"Lucky Slots"}

]

}

]

}

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