openapi: 3.0.0
info:
  title: Active Devices
  description: The active devices API provides analytics on unique device engagement and user activity patterns across your application. This suite enables multi-dimensional analysis of active device counts with customizable grouping by device type, platform, bundle, date, app version, and country.
  contact: {}
  version: 1.0.0
servers:
  - url: https://apptics.zoho.com/cx/api/v1
    description: API Endpoint
tags:
  - name: active-devices
    description: Active Devices Module
paths:
  /activedevice/countbydate:
    get:
      tags:
        - active-devices
      summary: Get active device count by date
      description: Retrieves the date-wise count of active devices for the specified date range, organized by platform. Returns each entry with the date (as an epoch millisecond timestamp) and the corresponding active device count. If startdate and enddate are not provided, the API returns data for the past 7 days. A maximum of 500 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 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/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/active-device-countbydate-response'
              examples:
                success:
                  summary: Successful response
                  value:
                    data:
                      result:
                        iOS:
                          - DATE: 1647072000000
                            ActiveDevices COUNT: 4
                          - DATE: 1647158400000
                            ActiveDevices COUNT: 3
                        Android:
                          - DATE: 1647072000000
                            ActiveDevices COUNT: 3
                          - DATE: 1647158400000
                            ActiveDevices COUNT: 1
                      userParams:
                        StartDate: 01-Jul-2024
                        EndDate: 31-Jul-2024
                    status: 200
      security:
        - Zoho_Auth:
            - JProxy.jmobileapi.ALL
  /activedevice/multigroup:
    get:
      tags:
        - active-devices
      summary: Get active devices count by group
      description: The get active devices count by group API provides flexible active devices analytics with customizable grouping and aggregation capabilities.<br>This endpoint allows you to analyze active devices data across multiple dimensions simultaneously, creating hierarchical breakdowns of active devices counts based on specified grouping criteria. The API requires a date range and grouping configuration, with optional filtering by platform. <br>The unique grouping system enables multi-dimensional analysis by combining up to three grouping entities such as device type, platform, bundle, date, app version and country. 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/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/active-devices-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 Active Devices (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 Active Devices. 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: false
      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
  schemas:
    active-device-countbydate-response:
      type: object
      properties:
        data:
          type: object
          properties:
            result:
              type: object
              description: Active device entries grouped by platform
              additionalProperties:
                type: array
                items:
                  type: object
                  properties:
                    DATE:
                      type: integer
                      format: int64
                      description: Date as epoch millisecond timestamp
                      example: 1647072000000
                    ActiveDevices COUNT:
                      type: integer
                      description: Number of active devices on this date
                      example: 4
            userParams:
              type: object
              properties:
                StartDate:
                  type: string
                  example: 01-Jul-2024
                EndDate:
                  type: string
                  example: 31-Jul-2024
        status:
          type: integer
          example: 200
    active-devices-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
