General Information
In this article we will cover the following topics
- Base URI
- Session Authentication Token
- Data Types
- Input Parameters
- HTTP Methods and Response Formats
- Response Paging for Customer
- Empty Response
- Function Error Response Codes
- Understanding Dates in Optimove
- IP Allow List
- Glossary of Terms
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.
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.
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 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.
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.
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:
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:
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).
A successful function call will return a response code of 200 (success). An unsuccessful call will return one of the following response codes:
| Error Code | Description |
|---|---|
| 400 | If any of the inputs to a function are invalid or unrecognized, HTTP response code 400 (Bad Request) will be returned along with a detailed explanation of the specific error condition. |
| 401 | If an invalid session authorization token is supplied, HTTP response code 401 (Unauthorized) is returned. |
| 403 | If a function is called 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. |
| 405 | If an unrecognized function is called, HTTP response code 405 (Method Not Allowed) is returned. |
| 429 | If the Login function is called too many times while a valid authentication token exists, HTTP response code 429 (Too Many Requests or User Already Logged In) is returned. |
| 500 | If the credentials supplied to the Login function are invalid, HTTP response code 500 (Internal Server Error) is returned. |
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).
.
Updated 9 months ago