This document accompanies the Optimove API Usage Guide and introduces the concepts and workflows necessary to integrate Optimove with external marketing, promotion and financial systems.
All the API calls mentioned throughout this document can be found in the accompanying document, Optimove API Usage Guide.
Optimove Entities and their Relationships
Before delving into how to use the API, it is important to understand the various entities that Optimove manages. The Optimove API exposes these entities for the purposes of external integrations.
- Campaign – An action sent to customers, who are members of a particular Target Group, on a particular date, via one or more Channels. Each Campaign has a “duration,” which 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.
- 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.
- Target Group – A Target Group is the specification of which customers will be targeted by a particular Campaign. Target Groups are defined within the Optimove UI by specifying one or more customer selection criteria (e.g., lifecycle stage, activity history, future value). Soon before a campaign is sent to a Target Group, Optimove dynamically selects the members of the Target Group based on the defined selection criteria.
- Channel – How a Campaign’s Actions are sent to customers. Possibilities include a particular ESP (e.g., Silverpop, ExactTarget), a message board system, Facebook Custom Audiences, mobile push notification, third-party systems (via custom integration), and emailing of a customer list to the marketer for manual processing.
- Promotion – The reward/discount/incentive associated with a particular action, as it appears in your back office/financial system.
Additional Terms Explained
- Customer ID – The identifier of a customer in your customer database.
- 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.
- Lead Time – In situations where an external incentive/marketing system needs to be set up some time before the campaign execution actually commences, the marketer will specify a lead time (in days) when scheduling the campaign. In this case, the campaign’s target group will be selected that number of days prior to the campaign’s actual execution. For example, if the marketer wants to execute a campaign on 20 December 2016 and the marketing system setup will take five days, then the marketer will create a campaign in Optimove with the desired data and a lead time of five days. The API will retrieve the campaign details on 15 December, which is the number of days of lead time before the intended execution, and the marketing system will actually deliver the campaign on 20 December.
- 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.
Uses of the API
The Optimove API is typically used for integrating with two types of systems:
- Marketing campaign execution systems – Optimove segments the customers and specifies the campaign parameters, and the marketing execution system executes the campaign.
- Financial/incentives/promotions systems – Optimove updates these systems with the incentive or promotion codes in effect for each customer.
Additionally, it is important to understand that there are two different types of campaigns within Optimove, each of which requires a different API workflow:
- Pre-scheduled campaigns – These are campaigns scheduled by a marketer to run automatically on future days. These are either recurring campaigns that run on a predefined schedule, or one-off campaigns set up by the marketer before the day on which they will run. Pre-scheduled campaigns are the most common type of campaign within Optimove.
Integration using the Optimove API for pre-scheduled campaigns involves developing a process that retrieves all the required information for the external system to be able to execute the campaign (or perform another desired action). This process needs to run only once a day, after Optimove’s daily data update has been completed.
- Immediate or same-day campaigns – These are campaigns scheduled by the marketer to run immediately (using Optimove’s Run Now option), or at a later time on the same day that they are defined.
Integration using the Optimove API for immediate or same-day campaigns involves two elements: (1) a listener which will be available at a particular URL so that Optimove can inform it anytime a new campaign is ready for execution, and (2) a process that retrieves all the required information for the external system to be able to execute the campaign (or perform another desired action).
Note that the listener will also receive notice of pre-scheduled campaigns, meaning that there is no need for both a listener and a daily process. Alternatively, if the marketer is provided with the ability to run the daily process on demand any time an immediate or same-day campaign is scheduled, then there is actually no need to develop a listener. Both approaches are perfectly acceptable.