How Can We Help?

Behavioral API

The Behavioral API provides a scalable framework for sending event data to Cortex’s servers in real-time. Events are the required building blocks for any Machine Learning Pipeline in Cortex, and the Behavioral API allows you to stream these events to Cortex as they occur. The more data submitted to the Behavioral API, the wider the set of predictions you can make and the more accurate your predictions will be.

The following sections will describe how to POST event data to the Behavioral API.

Event Parameters

The following table outlines the parameters to send alongside each event. Note that this table assumes a Cortex account that is configured to make predictions about users. If your account is set to predict for any other type of object, you should substitute the appropriate ID (e.g. item_id) for the “user_id” field.

Param Required? Value Description
user_id Yes string An ID which uniquely identifies the user that completed the event
type Yes string The type of event performed by the user (e.g. “click”, “purchase”, etc.).
timestamp No integer The default timestamp for an event is the time an event is submitted.
However, you may specify a different timestamp for when the event actually occured.
The timestamp should be expressed in seconds since epoch (January 1, 1970 at 00:00:00 UTC).
<custom_param> No boolean
Optionally, include any other parameters containing information about the events that you’re sending. These fields could describe the user completing the event (e.g. gender=female), the item/page on which the event was recorded (e.g. item_id=XYZ), or conditions of the event itself (e.g. device=mobile).

Note that if you’d like to generate personalized item recommendations for each user, or if you are sending Items data into Cortex, your events must also contain an item ID indicating which item the user interacted with. For recommendations, you should also be sure to send impression events (i.e. “shown”) to indicate when a user is exposed to an item.

When sending ‘shown’ events (i.e. impressions), Cortex recommends adhering to the following best practices, which are based on guidelines from the Interactive Advertising Bureau.

  • A ‘shown’ event should only be sent if at least 50% of the item is visible for at least 1 second.
  • A ‘shown’ event should only be sent once per item per page load.

Sending Behavioral Events

The process of sending a behavioral event is summarized by the following steps:

Step 1: Build an array of event objects.

This array can contain one or multiple events. Create a hash with the required and optional parameters for each event, similar to the following example:

events = {   
    data: [{     
      user_id: "123",     
      item_id: "ABC",     
      type: "purchase",
      device: "mobile",
      sale_price: 49.99

Step 2: Serialize the events array with JSON.

Convert your events array into a JSON string, like the following example:

serialized_events = '{"data":[{"user_id":"123","item_id":"ABC","type":"purchase","device":"mobile","sale_price":49.99}]}'

Step 3: Generate a signature, if necessary.

Signatures may be disabled for the Behavioral API. However, if the Behavioral API is configured to require a signature with each POST, follow Steps 1-5 in the Generating a Signature section. Note that signatures are validated during processing rather than in real-time.

Step 4: POST the data to Cortex’s servers.

Send the POST with your serialized data to HTTPS is also supported.

The POST body should include a JSON-serialized string containing a key-value pair with the string ‘data’ and your events. Depending on whether a signature is included in your request, the final POST request might look like one of the following:

Example POST without Signature


Content-Type: application/json

Example POST with Signature


Content-Type: application/json

Note that sending behavioral events to Cortex’s servers will always return a 200 HTML response code, indicating a successful POST. To verify that the correct data has been posted to Cortex’s severs in the correct format, or for any additional questions or information, please contact

Related Links

Still have questions? Reach out to for more info!

Table of Contents