Base URL

Different Optimove customers are assigned different API servers and accessed using different base URIs. Optimove's Support Team informs each customer of the correct base URI. 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

❗️
Please Note
On February 1st, 2024 Optimove will no longer support login using username and password. From this date on, Optimove API will only support authentication using API keys, as explained here

Every call to the API requires a per-session authentication token, which conforms to the JWT token standard. The token is obtained by calling the Login function before calling any other function during a particular session. The returned token must be included in the header of every subsequent call to the API:

Authorization-Token

eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiaXNzIjoiaHR0cHM6Ly9vcHRpbW92ZS5hdXRoMC5jb20vIn0..9DuWvTdukFJbQXUS.x0qZfx5fxOCKGLuuU1kDV3hqstIBIdz4LtHMU6XeJJHOgTNcAbYvU8XUqDpwoMYMRpD8mHgeqjUJbHru27zKNnD2yV20AsfDRxuJ5mGl0s1xrKCfODZe60-rnA0cj81drDXkjHagdC6XQS1PXZok_IeFYpWC18DCVYtHh0ilshNUHdxO1BcVV_W2oK9oyR01kyceqwW0sKusntuDdYqfUilC_P8n1A-KjBxx0OghciKle3fuA5UFXyWL8tbkFePQM2LSTor8NvtKscatRB2htry69zkLnHxwrpFwB_uegcaqFmViZgVZ8n_SJMHBORvNBun_a-1LtXX_pqELwzzPxPb_BGTJ4npDkHnTDMZj6BQEMuWXzgZzhDtFK0WwariXCEP_pSbBg1pE-qlYptU4OQ6UqFpJD33OP4w.5RCF8a-ody1KkZYZrCb0qw

Accept: application/json

Content-Type: application/json

Important Notes

The received authentication token remains valid for 20 minutes from the last time any API function was called. The Login function should only be called if 20 minutes have 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:

Type	Description
integer	A whole number greater than or equal to 0
double	A signed floating-point number
string	A string of non-case-sensitive alphanumeric characters of any length, using any encoding
StringArray	A JSON-formatted array of string values
ObjectArray	A JSON-formatted array of objects
date	Eight numerals delimited by dashes in the format YYYY-MM-DD
DateTime	Eight numerals for the date delimited by dashes plus six numerals for the time delimited by colons in the format YYYY-MM-DD HH:MM:SS
boolean	A string equal to either "true" or "false"
RGID*	A single numeric digit indicating a Recipient Group ID. When a campaign is sent to a single group of recipients, the campaign's RGID will always be 1. When a campaign includes a control group, the control group's RGID will be 0. When a campaign is sent to multiple recipient groups, their RGIDs will be 1, 2, etc. (if present, the control group is always 0). In an A/B/n campaign, the A group recipients' RGID is 1, B is 2, etc.
null	No data

*RGID is not actually a data type – it is always a single numeric digit (integer). RGID is treated as a distinct data type in this documentation to indicate that it is an integer with a limited set of possible values, as described above.

Input Parameters

Input parameter names are not case-sensitive. They are presented in this document with initial capitals (e.g., TargetGroupName) for the sake of clarity.

Users can set a data delimiter for all API calls that include Customer Attributes as an optional parameter to define the character that will separate the attribute values.

Some examples for a delimiter:

Comma ( , )
Colon ( : )
Semicolon ( ; )
Pipe ( | )

By default, Semicolon ( ; ) is selected as the field delimiter.

For example, in order to separate Alias by comma, use the following:

https://apiX.optimove.net/current/customers/GetCustomerExecutionDetailsByCampaign?CampaignID=836&CustomerAttributes=Alias,Email&CustomerAttributeDelimiter=,

Notes on Customer Attributes

All functions can include customer attributes as optional parameters and will include up to 10 customer attributes.
If supplied, CustomerAttributes must contain one or more valid attribute names (see GetCustomerAttributeList) separated by semicolons (;). The values are returned in the same order as the attribute names specified in the request.
The customer attribute values returned are the current (latest available) values, not the values on the specified date.

HTTP Methods and Response Formats

Functions must be called via HTTP GET or HTTP POST, as indicated in the API documentation for each function.

The data returned from functions using the GET method can be formatted as either JSON or XML, by using one of these request headers (if no Accept header is specified, the default response format is JSON):

"Accept:application/JSON"
"Accept:application/XML"

The data returned from functions using the POST method are always formatted as JSON.

All examples in this document are shown using JSON.

Response Paging for Customer-Related Functions

By default, all customer-related functions will return 10,000 records (the default page size) in any response (assuming there are at least 10,000 records to return). To request a smaller or larger page size, append the input parameter $top=n, where n is the page size. The maximum supported page size is 200,000.

To request subsequent pages of results, repeat the request with the additional parameter $skip=n where n is the number of resulting records of the entire result set to skip over when returning to 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

For information on the response codes returned by our functions, please refer to the standard HTTP status codes documentation available here.

Our functions adhere to these standard error codes for successful and unsuccessful calls.

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

.