Skip to main content
Important: User interaction records have dependencies on students. The system validates the student_id against existing records in the database. You should upload student data before uploading user interaction records to ensure proper data validation. The item_id field must reference the correct item type as specified by item_type.

​
Authentication Required

This endpoint may require API key authentication via Bearer token in the Authorization header. 
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

​
About the Endpoint

This endpoint allows you to record and retrieve user interactions with items (TAG, OFFER, SHOP, KEYWORD).

​
Source Field for Recommendation Feedback

The source field is crucial for tracking recommendation API effectiveness:
  • null: Normal user browsing interactions (not from recommendations)
  • "COBI": Interactions that originated from recommendation API responses
This enables the recommendation system to:
  • Track which recommendations led to user engagement
  • Measure recommendation algorithm effectiveness
  • Improve future recommendations based on user behavior patterns

​
Request Body

​
interaction_type
string
required
Type of interaction. One of: FILTER_CLICK, SHARE, PAGE_VIEW, DISCOUNT_CODE
​
user_id
string
Psuedo ID of the user
​
student_id
string (UUID)
UUID of the student
​
item_type
string
required
One of: TAG, OFFER, SHOP
​
item_id
string (UUID)
required
UUID of the item (TAG, OFFER, KEYWORD, or SHOP) as determined by item_type
​
city
string
City where the interaction occurred
​
country
string
Country where the interaction occurred
​
platform
string
One of: ANDROID, IOS, WEB, OTHER
​
event_timestamp
int or ISO string
required
Event timestamp (positive integer or ISO datetime string)
​
source
string
Source of interaction. Set to ‘COBI’ when from recommendation API, null otherwise

​
Response

The API returns a JSON response with the created interaction object on success.
  • 201 Created on success
  • 400 Bad Request if validation fails

​
Error Codes

Status CodeDescription
201Interaction created successfully
400Validation error
401Unauthorized - Invalid API key
500Internal server error

​
Example

curl -X POST https://api.hellocobi.com/user-interactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "interaction_type": "FILTER_CLICK",
    "user_id": "75962b04e5caa7e582e2bc2949587ed9",
    "student_id": "b1a2c3d4-e5f6-7890-abcd-1234567890ef",
    "item_type": "TAG",
    "item_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
    "city": "Berlin",
    "country": "Germany",
    "platform": "WEB",
    "event_timestamp": 1718035200,
    "source": "COBI"
  }'