Users Ratings & Behaviors

In addition to the table and catalog of products, the most important table to upload and update is the dataset of interactions and ratings.

First and foremost, you will need to upload, either manually or through your integrated platform, a historical dump of your users' interactions. This could be as straightforward as uploading the list of purchases or as granular and precise as uploading an exhaustive list of all the interactions and implicit feedback that may have been captured on the website (clicks, scrolls, add-to-cart, bookmark, etc.).

Raw Interactions

User interactions are vital to successfully training recommendation engines, providing invaluable context and feedback on how users engage with various items. The richness of this data allows our machine-learning algorithms to infer user preferences and generate tailored recommendations in real time.

To submit user interaction data to our Recommendation API, you can use multiple endpoints that facilitate creating and listing interactions for individual or multiple users, either one at a time or in bulk.

You can upload individual user interactions using the endpoint POST users/<str:user_id>/interactions/<str:item_id>/. The interaction should contain the 'interaction_type', an optional timestamp (defaulting to current time), and additional data related to the interaction encapsulated within the 'properties' object.

For uploading multiple interactions for one user or multiple users at once, you can use the POST users/<str:user_id>/interactions-bulk/ and POST interactions-bulk/ endpoints, respectively. The interactions should be provided in an array, each containing an 'item_id', 'interaction_type', timestamp, 'properties', and in the case of multiple users, 'user_id'.

All user interactions carry essential metadata such as the type of interaction (e.g., 'productView', 'addToCart'), time of interaction, and additional properties that could include specific details like the revenue generated or the webpage the interaction occurred on.

Please note that creating or updating inferred ratings for all tuples (user_id, item_id) is carried out automatically as interactions are processed. This helps to update the user's taste profile in real time, offering a dynamic learning framework for the recommendation engines.

In essence, providing comprehensive and accurate user interactions is a key aspect of improving the personalization and relevance of our recommendations, directly contributing to user satisfaction and engagement.

Interaction Type

Interaction types are fundamental to tailoring recommendation engines to specific business needs. Each business will have unique interaction types based on the nature of their services and user engagement patterns. That being said, a few common types are typically utilized across various sectors.

For eCommerce businesses, examples of interaction types could include 'ProductView', where a user views a product; 'addToCart', when a user adds an item to their shopping cart; 'purchase', marking a completed transaction; 'wishlistAdd', if a user adds a product to their wishlist; or 'productReview', where a user leaves a review or rating for a product. These interactions provide insight into user preferences, browsing and purchasing behavior.

For streaming services, interaction types could include 'content playz', when a user starts playing a video or song; 'contentPause', when a user pauses the playback; 'contentFinish', marking when a user finishes viewing or listening to content; 'contentLike', if a user likes a piece of content; 'contentDislike', when a user dislikes a piece of content; or 'contentSkip', when a user decides to skip the content. These interactions help understand user viewing or listening habits, genre preferences, and overall engagement with the platform's content.

However, it's crucial to remember that these are just examples, and the interaction types should be designed to effectively capture the unique user behaviors pertinent to your specific business domain. This allows the recommendation engine to generate the most accurate and beneficial suggestions to enhance the user experience.

Note: If you're integrating user interactions from a Customer Data Platform (CDP) or eCommerce platform with our recommendation engine, interaction types will follow the definitions in those platforms.


You'll need to map these platform-specific interactions to meaningful labels for your business. This ensures an accurate representation of user behavior, and seamless data flow, and ultimately leads to more effective and personalized recommendations. Consistency across all platforms is crucial when defining or mapping these user interaction types.


Our Recommendation API plays a significant role in translating various user interactions into a standardized format - a rating scale between 0 and 10. This process adds a layer of personalization to the mix, acknowledging that not all interactions are created equal.

For instance, a single click might have a different significance for different users, depending on their usual browsing and interaction patterns. The system takes into account these personal user behaviors when converting interactions into ratings. Thus, these ratings effectively express a user's level of interest in a specific item, paving the way for enhanced and personalized recommendations. This method allows Beam to harness the full potential of each user's unique interaction data, leading to a tailored user experience and increased user engagement.

Get started with Crossing Minds recommendation API

Crossing Minds Recommendation API is the easiest way to integrate personalized recommendation to your website & mobile apps

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
On this page
We use cookies (and other similar technologies) to collect data in order to improve our site. You have the option to opt-in or opt-out of certain cookie tracking technologies.To do so, click here.


API Documentation Center,
please wait a bit...