Event API Requests
The Personalization Event API uses standard HTTP methods and returns JSON-formatted responses to requests generated by the Sitemap and other Personalization event sources. The following sections describe the various Event API endpoints that enable you to interact with the Personalization platform.
Send event data to the Personalization dataset specified in the request.
Method and Endpoint
POST /api2/event/<dataset>
Request URL
https://<accountName>.<instance>.evergage.com/api2/event/<dataset>
URL Parameters
| URL Parameter | Required? | Description |
|---|---|---|
accountName | Yes | Your Personalization account name. You can retrieve it by accessing Gears from the Personalization UI and reviewing the URL. For example, if your Gears URL is https://demo.us-1.evergage.com/, then your account name is demo. |
instance | Yes | Your Personalization instance identifier. You can retrieve it by accessing Gears from the Personalization UI and reviewing the URL. For example, if your Gears URL is https://demo.us-1.evergage.com/, then your instance identifier is us-1. |
dataset | Yes | The name/identifier of the Personalization dataset you are sending data to. |
Supported Content Types
application/jsonapplication/x-www-form-urlencoded
Examples
Consider the following as sample event data that you would like to send to Personalization.
You can send this event data to Personalization as a JSON payload by minifying the event data to remove whitespaces, including it in the body of your API request, and setting the Content-Type to application/json, as shown in the following example request.
Do not make POST requests with Content-Type: application/json from an environment that checks for Cross-Origin Resource Sharing (CORS), such as a web browser.
When using Content-Type: application/x-www-form-urlencoded, the event data must be minified and then base64-encoded. Minifying the preceding example event data JSON gives you the following single-line JSON string.
Base64-encoding the above JSON string gives you the value eyJhY3Rpb24iOiJoZWxsbyB3b3JsZCIsInVzZXIiOnsiaWQiOiJ0ZXN0dXNlciJ9fQ==. You can then pass this value via the event key, as shown in the following example request.
Send event data to the Personalization dataset specified in the request.
Method and Endpoint
GET /api2/event/<dataset>
The event data you send in GET requests must be minified, base64-encoded, and passed via the event query parameter in the request URL.
Request URL
https://<accountName>.<instance>.evergage.com/api2/event/<dataset>?event=<base64-encoded-minified-event>
URL Parameters
| URL Parameter | Required? | Description |
|---|---|---|
accountName | Yes | Your Personalization account name. You can retrieve it by accessing Gears from the Personalization UI and reviewing the URL. For example, if your Gears URL is demo.us-1.evergage.com, then your account name is demo. |
instance | Yes | Your Personalization instance identifier. You can retrieve it by accessing Gears from the Personalization UI and reviewing the URL. For example, if your Gears URL is demo.us-1.evergage.com, then your instance identifier is us-1. |
dataset | Yes | The name/identifier of the Personalization dataset you are sending data to. |
base64-encoded-minified-event | Yes | The minified and base64-encoded event data string |
Example
Consider the following as sample event data that you would like to send to Personalization.
You can send this event by minifying the event JSON data and base64-encoding the resulting JSON string in the event parameter in the request URL and send the GET request, as shown in the following example.
You can also send the GET request via a web browser by accessing the request URL directly in your browser.
You can use GET requests as an alternative to using POST requests for sending event data to your Personalization datasets, if necessary.
The Personalization Event API provides a dedicated endpoint sending events that use trusted Server channels. The API call must be authenticated with a valid API token that is permitted to send events. The API token must be provided via the Authorization header according to the HTTP basic authentication scheme. For more information about creating and configuring an API token in Personalization, see Personalization API Tokens.
- For datasets created after January 28, 2021, the campaign targeting rule is set to
channel: Serverby default. To return server-side campaigns using the Event API, events must be sent via a trusted server channel. For more information on the implications of using or removing thechannel: Serverrule, refer to the Server-Side Templates documentation. - To add authentication to server-side campaigns for datasets created before January 28, 2021, please Create a Support Case.
Supported Content Types
application/json
Method and Endpoint
POST /api2/authevent/<dataset>
Request URL
https://<accountName>.<instance>.evergage.com/api2/authevent/<dataset>
URL Parameters
| URL Parameter | Required? | Description |
|---|---|---|
accountName | Yes | Your Personalization account name. You can retrieve it by accessing Gears from the Personalization UI and reviewing the URL. For example, if your Gears URL is demo.us-1.evergage.com, then your account name is demo. |
instance | Yes | Your Personalization instance identifier. You can retrieve it by accessing Gears from the Personalization UI and reviewing the URL. For example, if your Gears URL is demo.us-1.evergage.com, then your instance identifier is us-1. |
dataset | Yes | The name/identifier of the Personalization dataset you are sending data to. |
Supported Content Types
application/json
Authorization
Authorization: Basic <base64-encoded-API-token>
The Event API uses API tokens to authenticate requests. Your API token must be a strict Base64 encoding of your API Key ID and its API Secret Key, separated by a colon. You can use an existing API token if it has the required permissions or ask an account administrator to generate a new one from the Personalization UI by navigating to Security > API Tokens > Create Token. For more information about API tokens, see Personalization API Tokens.
Alternatively, if you use cURL to interact with the API, you can send your API Key ID and its API Key Secret using the -u "apiKeyId:apiKeySecret" command-line option. cURL automatically converts the apiKeyId:apiKeySecret pair into a Base64-encoded string and adds Authorization: Basic <base64-encoded-API-token> to the request header.
Example
Consider the following as sample event data that you would like to send to Personalization.
You can send this event data via the trusted channel via a POST request to the dedicated endpoint, as shown in the following example request. Ensure that you minify the event JSON data into a single line by removing all whitespaces before sending it via the POST request.