Optimove API Usage Guide PREVIOUS

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.

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

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 a particular date range

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 during a particular date range.
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
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 the list of product recommendations (replenishment or recommendation) for a selected date range (past or future)
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

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 on a particular date
GetValueSegmentChangers
Returns an array of customer IDs, and their before and after value segment IDs, for customers whose value segment changed during a particular date range

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

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: some-token-like-2e70b1e4-29fa-4a22-9f31-b69e3
    Accept: application/json
    Content-Type: application/json

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

string array

A JSON-formatted array of string values

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=2017-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=2017-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=2017-03-01&$top=100000

https://apiX.optimove.net/current/segments/GetCustomerOneTimeActionsByDate?Date=2017-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.

405

If an unrecognized function is called, HTTP response code 405 (Method Not Allowed) 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. For the generic channels included with Optimove, this value will be 504 (for email), 505 (for SMS) or 506 (for push notification). For vendor-specific channels integrated with Optimove, you can get the appropriate ChannelID from Optimove.
  • 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

"bf186b0a-ff34-44b2-9f62-496aa0d5e2c7"

Notes

  • 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).
  • If no calls are made to the API within a 20-minute time frame, the session authentication token expires.
  • 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":"2017-10-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,

"ListenerURL":"string"

}

Response Structure

(none)

Sample Request

{

"EventTypeID":1,

"ListenerURL":"http%3A%2F%2Fwww.exampleurl.com%2Feventlistener6"

}

Sample Response

(none)

Notes

  • 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 daily data update has been completed
    • 4 = A campaign that had been processed for execution was canceled

  • The specified URL 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

    }

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

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

}

Response Structure

(none)

Sample Request

{"EventTypeID":1}

Sample Response

(none)

Note

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.

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 a particular date range.

URI

https://apiX.optimove.net/current/model/GetMicrosegmentChangers

HTTP Method

GET

Required Parameters

(date) StartDate

(date) EndDate

Optional Parameters

(string) CustomerAttributes

Response Structure

 [{

"CustomerID":"string",

"InitialMicrosegmentID":integer,

"FinalMicrosegmentID":integer,

"CustomerAttributes":[string array]

}]

Sample Request

https://apiX.optimove.net/current/model/GetMicrosegmentChangers?StartDate=2017-01-01&EndDate=2017-01-31&CustomerAttributes=Alias;Country

Sample Response

 [

{"CustomerID":"231342","InitialMicrosegmentID":4,"FinalMicrosegmentID":12,"CustomerAttributes":["BuddyZZ","UK"]},

{"CustomerID":"231342","InitialMicrosegmentID":3,"FinalMicrosegmentID":67,"CustomerAttributes":["Player99","US"]},

]

Notes

  • Both supplied dates must be within the prior two days in order to receive results.
  • The specified dates indicate the dates of the actual customer data. Because the latest customer data available on any particular day is never newer than that of the previous day, the EndDate must be earlier than the current date.
  • For customers who only appeared in the database after the start date, the InitialMicrosegmentID returned will be -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.

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=2016-10-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=2017-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=2017-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=2016-11-11

Sample Response

 [

{"RecipientGroupID":1,"ActionID":65,"Duration":7,"LeadTime":0,"ChannelID":1},

{"RecipientGroupID":1,"ActionID":78,"Duration":7,"LeadTime":0,"ChannelID":3}

]

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

"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","Error":null}

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":1,"ChannelName":"Silverpop"},

{"ChannelID":2,"ChannelName":"ExactTarget"},

{"ChannelID":3,"ChannelName":"Lobby Banner"},

{"ChannelID":4,"ChannelName":"Call Center"}

]

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

Sample Response

 [

{"SendID":"YTGF3C","TemplateID":520,"ScheduledTime":"2016-12-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.
  • 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=35&Date=2017-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=2017-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":integer,

"CustomerAttributes":[string array]

}]

Sample Request

https://apiX.optimove.net/current/customers/GetCustomersByAction?RecipientGroupID=1&ActionID=2&Date=2017-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":[string array]

}]

Sample Request

https://apiX.optimove.net/current/customers/GetCustomerActionsByTargetGroup?TargetGroupID=2&Date=2017-02-24&IncludeControlGroup=True&IncludeRecipientGroupID=True&CustomerAttributes=Alias;Country

Sample Response

 [

{"CustomerID":"A1342","RecipientGroupID":1,"ActionID":49,"ChannelID":6,"CustomerAttributes":["BuddyZZ","UK"]},

{"CustomerID":"G4650","RecipientGroupID":1,"ActionID":49,"ChannelID":6,"CustomerAttributes":["Pax65","DE"]}

]

Notes

  • By specifying a ChannelID, you can limit the results returned to marketing actions sent via a particular channel. You can 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":[string array],

}]

Sample Request

https://apiX.optimove.net/current/customers/GetCustomerOneTimeActionsByDate?Date=2017-05-24&CustomerAttributes=Alias;Country

Sample Response

 [

{"CustomerID":"8D871","ActionID":19,"ChannelID":3,"CustomerAttributes":["Yo999","UA"]},

{"CustomerID":"8U76T","ActionID":19,"ChannelID":3,"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.
  • 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":[string array]

}]

Sample Request

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

Sample Response

 [

{"CustomerID":"8D871","RecipientGroupID":1,"ActionID":19,"ChannelID":3,"CustomerAttributes":["Yo999","UA"]},

{"CustomerID":"8U76T","RecipientGroupID":1,"ActionID":19,"ChannelID":3,"CustomerAttributes":["Neto2","TR"]}

]

Notes

  • By specifying a ChannelID, you can limit the results returned to marketing actions sent via a particular channel. You can 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 during a particular date range.

URI

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

HTTP Method

GET

Required Parameters

(date) StartDate

(date) EndDate

(string) ChangedCustomerAttribute

Optional Parameters

(string) CustomerAttributes

Response Structure

 [{

"CustomerID":"string",

"InitialCustomerAttribute":"string",

"FinalCustomerAttribute":"string",

"CustomerAttributes":[string array]

}]

Sample Request

https://apiX.optimove.net/current/customers/GetCustomerAttributeChangers?StartDate=2017-01-30&EndDate=2017-01-31&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).
  • Both supplied dates must be within the prior two days in order to receive results.
  • The specified dates indicate the dates of the actual customer data. Because the latest customer data available on any particular day is never newer than that of the previous day, the EndDate must be earlier than the current date.
  • For customers who only appeared in the database after the start date, 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":"2016-12-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=2016-12-10

Sample Response

 [

{"CustomerID":"231342","RecipientGroupID":1,"ActionID":42,"ChannelID":10},

{"CustomerID":"940023","RecipientGroupID":2,"ActionID":42,"ChannelID":10}

]

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=2016-12-10

Sample Response

 [

{"CustomerID":"231342","ActionID":428,"ChannelID":4,"Date":"2016-12-03","Duration":7,"TargetGroupID":15},

{"CustomerID":"981002","ActionID":22,"ChannelID":9,"Date":"2016-12-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,

"ScheduledTime":"DateTime",

"PromoCode":"string"

"CustomerAttributes":[string array]

}]

Sample Request

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

Sample Response

 [

{"CustomerID":"A1342","ActionID":14,"ChannelID":49,"TemplateID":60,"ScheduledTime":"2017-09-01 10:00:00","PromoCode":"FreeShip50","CustomerAttributes":["RhondaP","UK"]},

{"CustomerID":"A9258","ActionID":14,"ChannelID":49,"TemplateID":60,"ScheduledTime":"2017-09-01 10:00:00","PromoCode":"FreeShip50","CustomerAttributes":["JacquesR","FR"]}

]

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":4, "ScheduledTime":"2016-12-30 10:30:00","SendID":"HG65D","TemplateID":12},

{"CustomerID":"917251","ChannelID":4, "ScheduledTime":"2016-12-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":[string array]

}]

Sample Request

https://apiX.optimove.net/current/customers/GetCustomerSendDetailsByChannel?ChannelID=5&CampaignID=65874&CustomerAttributes=Email;Country

Sample Response

 [

{"CustomerID":"96134","TemplateID":14,"ScheduledTime":"2017-05-30 10:00:00","CustomerAttributes":["jdavis@aol.com","US"]},

{"CustomerID":"13482","TemplateID":14,"ScheduledTime":"2017-05-30 10:00:00","CustomerAttributes":["plsmits@gmail.com","UK"]}

]

Note

All times are returned in UTC (the GMT time zone).

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":"2016-12-30","EndDate":"2017-01-02"},

{"CustomerID":"745611","CampaignID":370,"ActionID":18,"StartDate":"2016-12-30","EndDate":"2017-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":[string array]

}]

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":[string array]

}]

Sample Request

https://apiX.optimove.net/current/customers/GetCustomerProductDetailsByDate?Date="2016-12-15"&ProductAttributes="color,style"

Sample Response

 [

{"CustomerID":"231342","ProductID":"jeans12","ProductAttributes":["blue","skinny"]},

{"CustomerID":"624542","ProductID":"jeans12","ProductAttributes":["grey","relaxed"]}

]

Returns the list of product recommendations (replenishment or recommendation) for a selected date range (past or future).

URI

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

HTTP Method

GET

Required Parameters

(date) StartDate

(date) EndDate

Optional Parameters

(integer) RecommendationType

(boolean) SuggestedInCampaign

(string) CustomerID

(string) ProductAttributes

Response Structure

 [{

"CustomerID":"string",

"ProductID":"string",

"RecommendationType":"integer",

"ProductAttributes":[string array]

}]

Sample Request

https://apiX.optimove.net/current/customers/GetCustomerProductRecommendations?StartDate=2017-08-20&EndDate=2017-09-20&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.
  • When SuggestedInCampaign is False or omitted, all product recommendations calculated by Optimove are returned. When set to True, only products recommended to customers in Optimove campaigns are returned.
  • Valid values for RecommendationType are:
    • 1 = Replenishment Reminder
    • 2 = Product Recommendation

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="2016-12-15"&ChannelID=15&EventID=2

Sample Response

 [

{"CustomerID":"231342","CampaignID":1213,"TemplateID":42},

{"CustomerID":"637733","CampaignID":1213,"TemplateID":42}

]

Note

Valid values for EventID are:

  • 2 = Opened
  • 3 = Clicked
  • 4 = Unsubscribed

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/actions/GetCustomerChannelInteractions?CustomerID=841231&StartDate=2017-08-19&EndDate=2017-09-19

Sample Response

 [

{"Date":"2017-08-20","CampaignID":422,"RecipientGroupID":1,"ActionID":26,"ChannelID":7,"TemplateID":13,"EventID":2},

{"Date":"2017-08-27","CampaignID":428,"RecipientGroupID":1,"ActionID":28,"ChannelID":7,"TemplateID":54,"EventID":2}

]

Note

Valid values for EventID are:

  • 2 = Opened
  • 3 = Clicked
  • 4 = Unsubscribed

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 on a particular date.

URI

https://apiX.optimove.net/current/segments/GetCustomersByValueSegment

HTTP Method

GET

Required Parameters

(integer) ValueSegmentID

(date) Date

Optional Parameters

(string) CustomerAttributes

Response Structure

 [{

"CustomerID":"string",

"CustomerAttributes":[string array]

}]

Sample Request

https://apiX.optimove.net/current/segments/GetCustomersByValueSegment?ValueSegmentID=3&Date=2017-05-10&CustomerAttributes=Alias;Country

Sample Response

 [

{"CustomerID":"AC7615","CustomerAttributes":["Robin777","ES"]},

{"CustomerID":"FP8721","CustomerAttributes":["JollyPop","UK"]}

]

Notes

  • The supplied date must be within the prior two days in order to receive results.
  • 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 during a particular date range, along with their before and after value segment IDs.

URI

https://apiX.optimove.net/current/segments/GetValueSegmentChangers

HTTP Method

GET

Required Parameters

(date) StartDate

(date) EndDate

Optional Parameters

(string) CustomerAttributes

Response Structure

 [{

"CustomerID":"string",

"InitialValueSegmentID":integer,

"FinalValueSegmentID":integer,

"CustomerAttributes":[string array]

}]

Sample Request

https://apiX.optimove.net/current/segments/GetValueSegmentChangers?StartDate=2017-03-01&EndDate=2017-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

  • The supplied date 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.

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

Request Structure

"ChannelID":integer,

[{

"TemplateID":integer,

"TemplateName":"string",

"AppID":string

}]

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

  • 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":[string array]

}]

Sample Request

https://apiX.optimove.net/current/integrations/GetChannelTemplateDetails?TemplateID=51&ChannelID=3

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":3,"TemplateID":15},

{"ChannelID":4,"TemplateID":26}

]

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.

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

Request Structure

{

"ChannelID":integer,

"Apps":[{

"AppID":"string",

"AppName":"string"

}]

}

Response Structure

(none)

Sample Request

{

"ChannelID":12,

"Apps":[

{"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.
  • 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":3,"AppID":"9c5f496c-392a-45a4-8414-12d42bf1fc8e"},

{"ChannelID":3,"AppID":"9c5f496c-392a-45a4-8414-2bf1f12d4c3d"}

]

Sample Response

(none)

Notes

  • A maximum of 100 apps 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.

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":3,"CampaignID":42,"TemplateID":8,"MetricID":0,"MetricValue":925},

{"ChannelID":3,"CampaignID":42,"TemplateID":8,"MetricID":1,"MetricValue":809},

{"ChannelID":3,"CampaignID":42,"TemplateID":8,"MetricID":2,"MetricValue":250},

{"ChannelID":3,"CampaignID":42,"TemplateID":8,"MetricID":3,"MetricValue":122},

{"ChannelID":3,"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.
  • This function can be called as often as is desired; the latest received metrics 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.

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":[string array]

"RecipientGroupID":RGID (optional)

"AppID":integer (optional)

}]

Response Structure

(none)

Sample Request

[

{"CampaignID":324,"ChannelID":2,"InteractionDate":"2017-06-26","TemplateID":8,"EventID":2,"RecipientGroupID":2,"CustomerIDs":["A8272","A916537","A13521","A286571","A792414"]}

]

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

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

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.
  • Personalizations are optional. Multiple personalization tags may be provided for each recipient.
  • 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.

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