Skip to main content
Important: User interaction records have dependencies 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.

​
Schema

{
  "type": "object",
  "required": [
    "interaction_type",
    "student_id",
    "item_type",
    "event_timestamp"
  ],
  "properties": {
    "interaction_type": {
      "type": "string",
      "description": "Type of interaction. One of: FILTER_CLICK, SHARE, PAGE_VIEW, DISCOUNT_CODE"
    },
    "user_id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the student"
    },
    "student_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "UUID of the student"
    },
    "item_type": {
      "type": "string",
      "description": "One of: TAG, OFFER, SHOP, KEYWORD"
    },
    "item_id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the item (TAG, OFFER, KEYWORD or SHOP) as determined by item_type"
    },
    "city": {
      "type": "string",
      "description": "City where the interaction occurred"
    },
    "country": {
      "type": "string",
      "description": "Country where the interaction occurred"
    },
    "platform": {
      "type": "string",
      "description": "One of: ANDROID, IOS, WEB, OTHER"
    },
    "event_timestamp": {
      "type": ["integer", "string"],
      "description": "Event timestamp (positive integer or ISO datetime string)"
    }
    "source": {
      "type": "string",
      "nullable": true,
      "description": "Source of interaction. Set to 'COBI' when the interaction is from a recommendation API response, null otherwise"
    },
  }
}

​
Field Descriptions

​
Required Fields

FieldTypeDescription
interaction_typestringType of interaction. One of: FILTER_CLICK, SHARE, PAGE_VIEW, DISCOUNT_CODE
item_typestringOne of: TAG, OFFER, SHOP
item_idstring (UUID)UUID of the item (TAG, OFFER, KEYWORD or SHOP) as determined by item_type
event_timestampint/ISO stringEvent timestamp (positive integer or ISO datetime string)

​
Optional Fields

FieldTypeDescription
user_idstringPsuedo Id of the student
student_idstring (UUID)UUID of the student
citystringCity where the interaction occurred
countrystringCountry where the interaction occurred
platformstringOne of: ANDROID, IOS, WEB, OTHER
sourcestringSource of interaction. Set to ‘COBI’ when from recommendation API, null otherwise

​
Example

{
  "interaction_type": "FILTER_CLICK",
  "user_id": "75962b04e5caa7e582e2bc2949587ed9"
  "student_id": null,
  "item_type": "TAG",
  "item_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "city": "Berlin",
  "country": "Germany",
  "platform": "WEB",
  "event_timestamp": 1718035200,
  "source": "COBI"
}

​
Source Field for Recommendation Feedback

The source field is used to track whether user interactions originated from recommendation API responses:
  • null: The interaction occurred through normal user browsing (not from a recommendation)
  • "COBI": The interaction occurred when a user clicked on or interacted with an item that was recommended by the Cobi recommendation API
This field is crucial for:
  • Feedback Loop: Helps the recommendation system understand which recommendations led to user engagement
  • Analytics: Track the effectiveness of recommendation algorithms
  • Model Training: Improve future recommendations based on user interaction patterns

​
Example Usage

When a user receives recommendations from the API and clicks on a recommended offer: 
{
  "interaction_type": "PAGE_VIEW",
  "student_id": "00000000-9779-438e-ae0d-b52099f6be51",
  "item_type": "OFFER",
  "item_id": "00000000-aaca-4844-9cb0-54af8f897322",
  "event_timestamp": 1718035200,
  "source": "COBI"
}

​
Best Practices

  1. Data Validation: Ensure all required fields are present and properly formatted.
  2. Timestamps: Use a valid positive integer or ISO 8601 string for event_timestamp.
  3. Platform: Use one of the allowed values for platform.
  4. Source Tracking: Always set source to “COBI” when tracking interactions from recommendation API responses.
Need help? Contact our support team at [email protected]