General Information

In this article we will cover the following topics

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, where the X represents a number.

For example, some Optimove customers are using 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:



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:

integerA whole number greater than or equal to 0
doubleA signed floating-point number
stringA string of non-case-sensitive alphanumeric characters of any length, using any encoding
StringArrayA JSON-formatted array of string values
ObjectArrayA JSON-formatted array of objects
dateEight numerals delimited by dashes in the format YYYY-MM-DD
DateTimeEight 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
booleanA 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.
nullNo data

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

Input Parameters

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

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

The supported values are:

  • Comma (, )
  • Colon (: )
  • Semicolon (;)
  • Tab (\t)

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

For example, in order to separate Alias by semi-column, use the following:;

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.

The following request will return the first 10,000 records (assuming there are at least 10,000 records to return):

The following request will return the next 10,000 records, i.e., the second page:$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:$top=100000$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:

Error CodeDescription
400If 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.
401If an invalid session authorization token is supplied, HTTP response code 401 (Unauthorized) is returned.
403If a function is called with an expired authentication token OR some of the attributes used within in a call are not authorized for the user, HTTP response code 403 is returned.
405If an unrecognized function is called, HTTP response code 405 (Method Not Allowed) is returned.
429If 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.
500If 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 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).