openapi: 3.0.0
info:
  title: Events
  description: 'The events API suite provides comprehensive user behavior analytics and event tracking capabilities for your application. These endpoints enable measurement of user engagement, feature adoption, and behavioral patterns through flexible multi-dimensional analysis. Key capabilities include tracking event frequencies and unique device reach, analyzing user interactions across different segments like platforms and geographic regions, and measuring actual user engagement through unique device counting rather than raw event volumes. The APIs support customizable grouping configurations, timezone-aware data aggregation, and hierarchical data organization for complex analytical queries.'
  contact: {}
  version: 1.0.0
servers:
  -
    url: 'https://apptics.zoho.com/cx/api/v1'
    description: 'API Endpoint'
tags:
  -
    name: events
    description: 'Events Module'
paths:
  /event/devicecount:
    get:
      tags:
        - events
      summary: 'Get event-based active device Count'
      description: 'The get events and their active devices count API provides unique device counts for events within a specified time period and timezone context. This endpoint measures user engagement by tracking how many distinct devices triggered specific events, offering insights into actual user reach rather than simple event frequency. The API requires date range, environment mode, and timezone parameters, with optional filtering by platform and application bundle. It returns event data with active device counts, where response keys follow the format "event_name(group_name)" and values represent the number of unique devices that generated each event during the specified period. This API is particularly valuable for understanding true user engagement, measuring feature adoption rates, and analyzing the actual reach of specific user actions.'
      parameters:
        - $ref: '#/components/parameters/zsoid'
        - $ref: '#/components/parameters/projectid'
        - $ref: '#/components/parameters/startdate'
        - $ref: '#/components/parameters/enddate'
        - $ref: '#/components/parameters/mode'
        - $ref: '#/components/parameters/platform'
        - $ref: '#/components/parameters/timezone'
        - $ref: '#/components/parameters/bundle'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/events-active-device-response'
      security:
        -
          Zoho_Auth:
            - JProxy.jmobileapi.ALL
  
  /event/multigroup:
    get:
      tags:
        - events
      summary: 'Get events count by group'
      description: 'The get events Count by group API provides flexible event analytics with customizable grouping and aggregation capabilities. This endpoint allows you to analyze event data across multiple dimensions simultaneously, creating hierarchical breakdowns of event counts based on specified grouping criteria. The API requires a date range and grouping configuration, with optional filtering by platform, group name, and event name. The unique grouping system enables multi-dimensional analysis by combining up to three grouping entities such as device type, platform, bundle, date, app version, country, and event type. The response structure dynamically adapts to match your grouping configuration, creating nested JSON hierarchies that reflect the specified group order. For example, grouping by "platform,country,devicetype" returns data organized first by platform, then by country within each platform, and finally by device type within each country. This flexible structure supports complex analytical queries and enables detailed segmentation analysis.'
      parameters:
        - $ref: '#/components/parameters/zsoid'
        - $ref: '#/components/parameters/projectid'
        - $ref: '#/components/parameters/startdate'
        - $ref: '#/components/parameters/enddate'
        - $ref: '#/components/parameters/group'
        - $ref: '#/components/parameters/platform'
        - $ref: '#/components/parameters/groupname'
        - $ref: '#/components/parameters/eventname'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/events-count-by-group-response'
      security:
        -
          Zoho_Auth:
            - JProxy.jmobileapi.ALL
  
components:
  parameters:
    zsoid:
      name: zsoid
      description: 'Portal ID'
      in: header
      required: true
      schema:
        type: string
      example: '10234695'
    projectid:
      name: projectid
      description: 'Project ID'
      in: header
      required: true
      schema:
        type: string
      example: '12345689'
    startdate:
      name: startdate
      description: 'Beginning of date range for data retrieval, required format - dd-MM-yyyy'
      in: query
      required: true
      schema:
        type: string
      example: 02-08-2025
    enddate:
      name: enddate
      description: 'End of date range for data retrieval, required format - dd-MM-yyy'
      in: query
      required: true
      schema:
        type: string
      example: 24-08-2025
    platform:
      name: platform
      description: 'Platform to filter Events (iOS, Android, Windows, tvOS, watchOS, macOS). Default - all platforms.'
      in: query
      required: false
      schema:
        type: string
      example: Android
    group:
      name: group
      description: 'Comma-separated list of grouping entities (devicetype, platform, bundle, date, appversion, country, event). Maximum 3 groups. Response structure follows the specified group order in nested JSON format.'
      in: query
      required: true
      schema:
        type: string
      example: platform,devicetype
    appversion:
      name: appversion
      description: 'Comma-separated list of app versions to filter Events. Default - all app versions. Maximum 10 values allowed.'
      in: query
      required: false
      schema:
        type: string
      example: 1.0,1.1,1.2
    mode:
      name: mode
      description: 'Environment filter. 0 for development, 1 for production. Default - 1 (production).'
      in: query
      required: true
      schema:
        type: string
      example: 0
    offset:
      name: offset
      description: 'Starting position for result pagination (default - 0). Increment by limit value for next page (e.g., 501, 1001).'
      in: query
      required: false
      schema:
        type: string
      example: 501
    limit:
      name: limit
      description: 'Number of results per page. Default and maximum: 500. Use smaller values to limit response size.'
      in: query
      required: false
      schema:
        type: string
      example: 100
    groupname:
      name: groupname
      description: 'Group Name of an Event to Filter. Need to be used in combination with eventname param.'
      in: query
      required: false
      schema:
        type: string
      example: module_group
    eventname:
      name: eventname
      description: 'A specific Event to filter. Need to be used in combination with groupname param.'
      in: query
      required: false
      schema:
        type: string
      example: module_event
    timezone:
      name: timezone
      description: 'Timezone for events data aggregation.(e.g., "America/New_York", "Asia/Tokyo")'
      in: query
      required: true
      schema:
        type: string
      example: Asia/Kolkata
    bundle:
      name: bundle
      description: 'Application id filter. Need to be used in combination with platform param(e.g., "com.example.demo")'
      in: query
      required: false
      schema:
        type: string
      example: com.example.demo
  schemas:
    events-active-device-response:
      type: object
      properties:
        result:
          type: object
          properties:
            event_name(group_name):
              type: integer
              example: 121
            module_click(module_group):
              type: integer
              example: 100
        status:
          type: string
          example: success
    events-count-by-group-response:
      type: object
      properties:
        result:
          type: object
          properties:
            iOS:
              type: object
              properties:
                iPhone:
                  type: integer
                  example: 155248
                iPad:
                  type: integer
                  example: 3496
            Android:
              type: object
              properties:
                Phone:
                  type: integer
                  example: 40011
                Tablet:
                  type: integer
                  example: 1110
                Foldables:
                  type: integer
                  example: 1186
        status:
          type: string
          example: success
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: 'https://accounts.zoho.com/oauth/v2/auth'
          scopes:
            JProxy.jmobileapi.ALL: 'Analytics & Insight view'
