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/summary:
    get:
      tags:
        - events
      summary: Get event summary
      description: Retrieves a summary of event counts grouped by platform for the specified date range. Returns each event with its group name and total occurrence count, organized by platform (iOS, Android, macOS, etc.). If startdate and enddate are not provided, the API returns data for the past 7 days. A maximum of 500 events are returned per request; use the offset parameter to paginate through additional results.
      parameters:
        - $ref: '#/components/parameters/zsoid'
        - $ref: '#/components/parameters/projectid'
        - name: startdate
          in: query
          required: false
          description: 'Beginning of date range. Required format: dd-MM-yyyy. Defaults to 7 days before enddate if not provided.'
          schema:
            type: string
          example: 01-07-2024
        - name: enddate
          in: query
          required: false
          description: 'End of date range. Required format: dd-MM-yyyy. Defaults to today if not provided.'
          schema:
            type: string
          example: 31-07-2024
        - $ref: '#/components/parameters/platform'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: timezone
          in: query
          required: false
          description: Timezone for events data aggregation.(e.g., "America/New_York", "Asia/Tokyo")
          schema:
            type: string
          example: Asia/Kolkata
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event-summary-response'
              examples:
                success:
                  summary: Successful response
                  value:
                    data:
                      result:
                        iOS:
                          - GROUP: app_lifecycle
                            'EVENTS NAME ': app_launched
                            EVENTS COUNT: 4561
                          - GROUP: user_action
                            'EVENTS NAME ': button_click
                            EVENTS COUNT: 2341
                          - GROUP: navigation
                            'EVENTS NAME ': screen_view
                            EVENTS COUNT: 1823
                        Android:
                          - GROUP: app_lifecycle
                            'EVENTS NAME ': app_launched
                            EVENTS COUNT: 3210
                          - GROUP: user_action
                            'EVENTS NAME ': button_click
                            EVENTS COUNT: 1987
                          - GROUP: navigation
                            'EVENTS NAME ': screen_view
                            EVENTS COUNT: 1456
                      userParams:
                        StartDate: 01-Jul-2024
                        EndDate: 31-Jul-2024
                    status: 200
      security:
        - Zoho_Auth:
            - JProxy.jmobileapi.ALL
  /event/countbydate:
    get:
      tags:
        - events
      summary: Get event count by date
      description: Retrieves event counts grouped per day for the specified date range, organized by platform. Returns each event entry with its group name, event name, occurrence count, and the date (as an epoch millisecond timestamp). If startdate and enddate are not provided, the API returns data for the past 7 days. A maximum of 500 event entries are returned per request; use the offset parameter to paginate through additional results.
      parameters:
        - $ref: '#/components/parameters/zsoid'
        - $ref: '#/components/parameters/projectid'
        - name: startdate
          in: query
          required: false
          description: 'Beginning of date range. Required format: dd-MM-yyyy. Defaults to 7 days before enddate if not provided.'
          schema:
            type: string
          example: 01-07-2024
        - name: enddate
          in: query
          required: false
          description: 'End of date range. Required format: dd-MM-yyyy. Defaults to today if not provided.'
          schema:
            type: string
          example: 31-07-2024
        - $ref: '#/components/parameters/platform'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: timezone
          in: query
          required: false
          description: Timezone for events data aggregation (e.g., "America/New_York", "Asia/Tokyo")
          schema:
            type: string
          example: Asia/Kolkata
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event-countbydate-response'
              examples:
                success:
                  summary: Successful response
                  value:
                    data:
                      result:
                        iOS:
                          - GROUP: app_lifecycle
                            EVENT NAME: app_launched
                            EVENT COUNT: 3
                            DATE: 1647072000000
                          - GROUP: user_action
                            EVENT NAME: button_click
                            EVENT COUNT: 5
                            DATE: 1647072000000
                          - GROUP: app_lifecycle
                            EVENT NAME: app_launched
                            EVENT COUNT: 4
                            DATE: 1647158400000
                        Android:
                          - GROUP: app_lifecycle
                            EVENT NAME: app_launched
                            EVENT COUNT: 7
                            DATE: 1647072000000
                          - GROUP: navigation
                            EVENT NAME: screen_view
                            EVENT COUNT: 2
                            DATE: 1647072000000
                          - GROUP: user_action
                            EVENT NAME: button_click
                            EVENT COUNT: 3
                            DATE: 1647158400000
                      userParams:
                        StartDate: 12-Mar-2022
                        EndDate: 13-Mar-2022
                    status: 200
      security:
        - Zoho_Auth:
            - JProxy.jmobileapi.ALL
  /search/event:
    get:
      tags:
        - events
      summary: Search events
      description: Retrieves raw event log entries for a given date range with optional filtering by event name and group name. Also accessible via the alias <code>/ferret/event</code>. If startdate and enddate are not provided, the API returns data for the past 7 days. A maximum of 500 records are returned per request; use the offset parameter to paginate through additional results.
      parameters:
        - $ref: '#/components/parameters/zsoid'
        - $ref: '#/components/parameters/projectid'
        - name: startdate
          in: query
          required: false
          description: 'Beginning of date range. Required format: dd-MM-yyyy. Defaults to 7 days ago if not provided.'
          schema:
            type: string
          example: 01-07-2024
        - name: enddate
          in: query
          required: false
          description: 'End of date range. Required format: dd-MM-yyyy. Defaults to today if not provided.'
          schema:
            type: string
          example: 31-07-2024
        - $ref: '#/components/parameters/platform'
        - $ref: '#/components/parameters/eventname'
        - $ref: '#/components/parameters/groupname'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event-search-response'
              examples:
                success:
                  summary: Successful response
                  value:
                    data:
                      result:
                        - customproperties: ''
                          janalyticversion: '1.3'
                          appversion: 2.1.0
                          when: 1751132723264
                          userid: 100000000000001
                          deviceid: 200000000000001
                          platform: iOS
                          sessionstarttime: 1751100000000
                          eventgroup: app_lifecycle
                          appreleaseversion: 2.1.3
                          model: 48900
                          event: app_launched
                          screenname: HomeScreen
                          osversion: '17.0'
                        - customproperties: ''
                          janalyticversion: '1.3'
                          appversion: 2.0.0
                          when: 1751132800000
                          userid: 100000000000002
                          deviceid: 200000000000002
                          platform: Android
                          sessionstarttime: 1751101000000
                          eventgroup: user_action
                          appreleaseversion: 2.0.5
                          model: 49100
                          event: button_click
                          screenname: DashboardScreen
                          osversion: '14'
                      usergivenparams:
                        startdate: 01-Jul-2024
                        enddate: 31-Jul-2024
                        nexturl: ''
                        offset: 0
                        limit: 0
                        maxresult: 500
                    status: 200
      security:
        - Zoho_Auth:
            - JProxy.jmobileapi.ALL
  /event/countrysummary:
    get:
      tags:
        - events
      summary: Get event count by country
      description: Retrieves the total event count aggregated by country for the specified date range. Returns a flat map of country names to their event counts. If startdate and enddate are not provided, the API returns data for the past 7 days. A maximum of 500 country entries are returned per request; use the offset parameter to paginate through additional results.
      parameters:
        - $ref: '#/components/parameters/zsoid'
        - $ref: '#/components/parameters/projectid'
        - name: startdate
          in: query
          required: false
          description: 'Beginning of date range. Required format: dd-MM-yyyy. Defaults to 7 days before enddate if not provided.'
          schema:
            type: string
          example: 01-07-2024
        - name: enddate
          in: query
          required: false
          description: 'End of date range. Required format: dd-MM-yyyy. Defaults to today if not provided.'
          schema:
            type: string
          example: 31-07-2024
        - $ref: '#/components/parameters/platform'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event-countrysummary-response'
              examples:
                success:
                  summary: Successful response
                  value:
                    data:
                      result:
                        CANADA: 42
                        ITALY: 11
                        DENMARK: 6
                        INDIA: 98
                        UNITED STATES: 215
                      userParams:
                        StartDate: 01-Jul-2024
                        Platform:
                          - iOS
                          - Android
                          - tvOS
                          - macOS
                        EndDate: 31-Jul-2024
                    status: 200
      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:
    event-search-response:
      type: object
      properties:
        data:
          type: object
          properties:
            result:
              type: array
              description: List of raw event log entries matching the specified filters
              items:
                type: object
                properties:
                  customproperties:
                    type: string
                    description: Custom properties associated with the event
                    example: ''
                  janalyticversion:
                    type: string
                    description: Apptics SDK version
                    example: '1.3'
                  appversion:
                    type: string
                    description: App version from which the event was sent
                    example: 2.1.0
                  when:
                    type: integer
                    format: int64
                    description: Epoch timestamp (ms) when the event occurred
                    example: 1751132723264
                  userid:
                    type: integer
                    format: int64
                    description: Apptics user identifier
                    example: 100000000000001
                  deviceid:
                    type: integer
                    format: int64
                    description: Apptics device identifier
                    example: 200000000000001
                  platform:
                    type: string
                    description: Platform from which the event was sent
                    example: iOS
                  sessionstarttime:
                    type: integer
                    format: int64
                    description: Epoch timestamp (ms) when the session started
                    example: 1751100000000
                  eventgroup:
                    type: string
                    description: Group name of the event
                    example: app_lifecycle
                  appreleaseversion:
                    type: string
                    description: App release version string
                    example: 2.1.3
                  model:
                    type: integer
                    description: Internal device model identifier
                    example: 48900
                  event:
                    type: string
                    description: Event name
                    example: app_launched
                  screenname:
                    type: string
                    description: Screen name where the event was triggered
                    example: HomeScreen
                  osversion:
                    type: string
                    description: OS version of the device
                    example: '17.0'
            usergivenparams:
              type: object
              properties:
                startdate:
                  type: string
                  example: 01-Jul-2024
                enddate:
                  type: string
                  example: 31-Jul-2024
                nexturl:
                  type: string
                  example: ''
                offset:
                  type: integer
                  example: 0
                limit:
                  type: integer
                  example: 0
                maxresult:
                  type: integer
                  example: 500
        status:
          type: integer
          example: 200
    event-countrysummary-response:
      type: object
      properties:
        data:
          type: object
          properties:
            result:
              type: object
              description: Map of country names (uppercase) to their total event counts
              additionalProperties:
                type: integer
              example:
                CANADA: 42
                ITALY: 11
                INDIA: 98
            userParams:
              type: object
              properties:
                StartDate:
                  type: string
                  example: 01-Jul-2024
                Platform:
                  type: array
                  items:
                    type: string
                  example:
                    - iOS
                    - Android
                EndDate:
                  type: string
                  example: 31-Jul-2024
        status:
          type: integer
          example: 200
    event-countbydate-response:
      type: object
      properties:
        data:
          type: object
          properties:
            result:
              type: object
              description: Event entries grouped by platform, each containing daily counts
              additionalProperties:
                type: array
                items:
                  type: object
                  properties:
                    GROUP:
                      type: string
                      example: app_lifecycle
                    EVENT NAME:
                      type: string
                      example: app_launched
                    EVENT COUNT:
                      type: integer
                      example: 3
                    DATE:
                      type: integer
                      format: int64
                      description: Date as epoch millisecond timestamp
                      example: 1647072000000
            userParams:
              type: object
              properties:
                StartDate:
                  type: string
                  example: 12-Mar-2022
                EndDate:
                  type: string
                  example: 13-Mar-2022
        status:
          type: integer
          example: 200
    event-summary-response:
      type: object
      properties:
        data:
          type: object
          properties:
            result:
              type: object
              description: Event counts grouped by platform
              additionalProperties:
                type: array
                items:
                  type: object
                  properties:
                    GROUP:
                      type: string
                      example: app_lifecycle
                    'EVENTS NAME ':
                      type: string
                      example: app_launched
                    EVENTS COUNT:
                      type: integer
                      example: 4561
            userParams:
              type: object
              properties:
                StartDate:
                  type: string
                  example: 01-Jul-2024
                EndDate:
                  type: string
                  example: 31-Jul-2024
        status:
          type: integer
          example: 200
    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
