openapi: 3.0.0
info:
  version: 3.0.0
  title: Cloud4wi Explore APIs
  description: How To Use |
    Using the clientKey and clientSecret perform a request to /v1/sts/login/services.
    Copy the token received and paste it in the dialog that pops up clicking the button "Authorize".
    Note -> scopes are not currently enforced

security:
  - bearerAuth: []

servers:
  - url: https://explore.cloud4wi.com/
    description: Cloud4Wi APIs

paths:

  ########################
  ### STS
  ########################

  '/v1/sts/login/services':
    post:
      summary: Get authentication token
      description: Returns a JWT token inside the body and in the Authorization Header of the response
      security: []   # No security
      tags:
        - sts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                clientKey:
                  type: string
                clientSecret:
                  type: string
      responses:
        '200':
          description: User authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: JWT token
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  '/v1/sts/logout':
    post:
      summary: Revoke authetnication Token
      description: It revokes the JWT token passed in the header.
      tags:
        - sts
      responses:
        '200':
          description: The token has been revoked
        '401':
          description: The token is not valid
        '500':
          description: Internal server error

  ########################
  ### CUSTOMERS
  ########################

  '/v2/customers/organizations/{cid}':
    get:
      summary: "List all the Contacts of an organization matching the search parameters "
      description:  |
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_read, customer_read
      parameters:
        - in: path
          name: cid
          description: organization cid
          required: true
          schema:
            type: string
        - in: query
          name: sid
          description: 'The sid can be used to retrieve a large number of results from a search request. Read the full docs to learn how to use the sid'
          required: false
          schema:
            type: string
        - in: query
          name: size
          description: Number of Contacts returned by the request. Allowed values between 1 and 10000. It is not possible to change this values during a scrolling.
          required: false
          schema:
            type: string
        - in: query
          name: hasEmail
          description: Return Contacts with email
          required: false
          schema:
            type: boolean
        - in: query
          name: emailVerified
          description: Return Contacts with an email verified
          required: false
          schema:
            type: boolean
        - in: query
          name: hasPhone
          description: Return Contacts with phone number
          required: false
          schema:
            type: boolean
        - in: query
          name: phoneVerified
          description: Return Contacts with an phone number verified
          required: false
          schema:
            type: boolean
        - in: query
          name: signupMethods
          description: Return Contacts with the requested signup method
          required: false
          schema:
            type: string
        - in: query
          name: locationCids
          description: Return Contacts registered on specific locations
          required: false
          schema:
            type: string
        - in: query
          name: segmentCids
          description: Return Contacts belonging to specific segment or segments (comma separated)
          required: false
          schema:
            type: string
        - in: query
          name: createdStart
          description: 'Return Contacts with creation date >= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z'
          required: false
          schema:
            type: string
        - in: query
          name: createdEnd
          description: 'Return Contacts with creation date <= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z'
          required: false
          schema:
            type: string
        - in: query
          name: modifiedStart
          description: 'Return Contacts with modified date >= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z'
          required: false
          schema:
            type: string
        - in: query
          name: modifiedEnd
          description: 'Return Contacts with modified date <= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z'
          required: false
          schema:
            type: string
        - in: query
          name: mktgCommunications
          description: 'Return Contacts with marketing communication opt-in with value true'
          required: false
          schema:
            type: boolean
        - in: query
          name: ageVerification
          description: 'Return Contacts with age verification set to true'
          required: false
          schema:
            type: boolean
        - in: query
          name: customOptIn.*
          description: 'Return Contacts with specific custom opt-ins set to true. Eg: customOptin.my_policy=true'
          required: false
          schema:
            type: boolean
        - in: query
          name: sortBy
          description: 'firstName, lastName, gender, birthDate, country, created, privacy, termsOfUse, mktgCommunications, ageVerification, phone, phoneVerified, email, emailVerified, provider, username, locked, locations, system, enabled, type,  modified_absolute,created_absolute,totalVisits,visitedLocations'
          required: false
          schema:
            type: string
        - in: query
          name: sortReverse
          description: 'Reverse sort order. sortBy argument is required'
          required: false
          schema:
            type: boolean
        - in: query
          name: email
          description: 'Search by email address'
          required: false
          schema:
            type: string
        - in: query
          name: phoneNumber
          description: 'Search by phone number'
          required: false
          schema:
            type: string
        - in: query
          name: username
          description: 'Search by username'
          required: false
          schema:
            type: string
        - in: query
          name: extId
          description: 'Search by external Id'
          required: false
          schema:
            type: string
        - in: query
          name: extProp1
          description: 'Search by external property 1'
          required: false
          schema:
            type: string
        - in: query
          name: extProp2
          description: 'Search by external property 2'
          required: false
          schema:
            type: string

      tags:
        - customers
      responses:
        '200':
          description: The array of the customers
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated:
                    type: string
                  totalCount:
                    type: number
                  count:
                    type: number
                  sId:
                    type: string
                    description: 'id used in the scrolling'
                  customers:
                    type: array
                    items:
                      $ref: '#/components/schemas/customerListResponse'
        default:
          description: errorResponse

  '/v2/customers/{cid}/otp' :
    post:
      summary: It creates an access code (called OTP) for the customer passed in input.
      description: |
        <br><b>Role</b>: Organization Manager and above
        <br><b>Scope</b>: organization_write, customer_write
      parameters:
        - $ref: '#/components/parameters/userCid'
      tags:
        - customers
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated:
                    type: string
                  status:
                    type: string
                  otp:
                    type: string

  '/v1/customers/{cid}/policies':
    put:
      summary: Update the opt-ins of a Contact
      description: |
        For the custom opt-ins add the prefix "customs." to the policyKey. For example, if the custom opt-in has title "emailMarketing" to update it use the policyKey "customs.emailMarketing" 
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_write, customer_write
      parameters:
        - $ref: '#/components/parameters/userCid'
      tags:
        - customers
      requestBody:
        description: desc
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/policiesUpdate'
      responses:
        '200':
          description: Update done.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responseOkUpdatePolicies'
        '207':
          description: Some of the opt-ins have not been updated. More details in the response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responseOkUpdatePolicies'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'


  '/v1/customers/{cid}':
    delete:
      summary: Delete a Contact
      description: |
        Delete a Contact by Id
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_write, customer_write
      parameters:
        - $ref: '#/components/parameters/userCid'
      tags:
        - customers
      responses:
        '200':
          description: Deleted done.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responseOk'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
  '/v2/customers/{cid}':
    get:
      summary: Get a Contact
      description: |
        Retrieve Contact profile by Id
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_read, customer_read
      tags:
        - customers
      parameters:
        - $ref: '#/components/parameters/userCid'
      responses:
        '200':
          description: Data present


  '/v2/customers/{cid}/accountings':
    get:
      summary: List all WiFi Connections of a Contact
      description: |
        Retrieve WiFi connections of a specific Contact Id, including metadata such as duration, traffic, access point used
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_read, customer_read
      tags:
        - customers
      parameters:
        - $ref: '#/components/parameters/userCid'
      responses:
        '200':
          description: Array with the accountings
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated:
                    type: string
                  sId:
                    type: string
                  count:
                    type: number
                  connections:
                    type: array
                    items:
                      type: object
                      properties:
                        start:
                          type: string
                        startBusiness:
                          type: string
                        stop:
                          type: string
                        stopBusiness:
                          type: string
                        duration:
                          type: number
                        traffic:
                          type: number
                        locationName:
                          type: string
                        locationId:
                          type: string
                        apName:
                          type: string
                        apId:
                          type: string
                        latitude:
                          type: number
                        longitude:
                          type: number
                        macAddressClient:
                          type: string
                        ipAddressClient:
                          type: string
                        terminateCause:
                          type: string

  '/v2/customers/{cid}/activities':
    get:
      summary: 'List applicaiton and marketing activities for a Contact'
      description: |
        Retrieve logs of interactions with content applicaitons such as Survey, messages sent/receives/opened
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_read, customer_read
      tags:
        - customers
      parameters:
        - $ref: '#/components/parameters/userCid'
      responses:
        '200':
          description: Data present
  '/v2/customers/{cid}/devices':
    get:
      summary: 'List all devices of a Contact'
      description: |
        Retrieve device information like WiFi MAC address, number of WiFi connections and last WiFi connection date on the device.
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_read, customer_read
      tags:
        - customers
      parameters:
        - $ref: '#/components/parameters/userCid'
      responses:
        '200':
          description: Data present

  '/v2/customers/{cid}/events':
    get:
      summary: 'List location Events of a Contact'
      description: |
        Retrieve list of visits and WiFi connections including metadata such as date and duration.
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_read, customer_read
      tags:
        - customers
      parameters:
        - $ref: '#/components/parameters/userCid'
      responses:
        '200':
          description: Data present

  ###########################
  ### Events
  ###########################
  '/v1/organizations/{cid}/events':
    get:
      summary: List all events for an organziation id
      description: |
        List all Events, including Visits, WiFi connections and application events, of an Organization
        Retrieve all events og of the given organization . 
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_read, events_read
      tags:
        - organizations
      parameters:
        - $ref: '#/components/parameters/organizationCid'
        - in: query
          name: dateStart
          description: 'Return events with date >= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z'
          required: false
          schema:
            type: string
        - in: query
          name: dateEnd
          description: 'Return events with date <= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z'
          required: false
          schema:
            type: string

        - in: query
          name: events
          description: 'List of events (comma separated). Possible values: visit,signup, login, send_email,open_email,click_email,send_sms,click_sms,survey, promo'
          required: false
          schema:
            type: string
        - in: query
          name: size
          description: Number of events returned by the request. Allowed values between 1 and 10000. It is not possible to change this values during a scrolling.
          required: false
          schema:
            type: string
        - in: query
          name: sortBy
          description: 'Sort list by: businessTime, utcTime (default is businessTime)'
          required: false
          schema:
            type: string
        - in: query
          name: sortReverse
          description: 'Reverse sort order'
          required: false
          schema:
            type: boolean
        - in: query
          name: enableScroll
          description: 'Enable scroll. If true, the response will contain a scrollId. Use it to get the next page of results.  '
          required: false
          schema:
            type: boolean
        - in: query
          name: scrollId
          description: 'Scroll id. Use it to get the next page of results.'
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eventsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  '/v1/organizations/{cid}/customers/{id}/events':
    get:
      summary: List all events of a specific Contact
      description: |
        List all events, including WiFi Connections, Visits and applicaiton events of a given Contact Id
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_read, events_read
      tags:
        - organizations
      parameters:
        - $ref: '#/components/parameters/organizationCid'
        - $ref: '#/components/parameters/userId'
        - in: query
          name: dateStart
          description: 'Return events with date >= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z'
          required: false
          schema:
            type: string
        - in: query
          name: dateEnd
          description: 'Return events with date <= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z'
          required: false
          schema:
            type: string

        - in: query
          name: events
          description: 'List of events (comma separated). Possible values: visit,signup, login, send_email,open_email,click_email,send_sms,click_sms,survey, promo'
          required: false
          schema:
            type: string
        - in: query
          name: size
          description: Number of events returned by the request. Allowed values between 1 and 10000. It is not possible to change this values during a scrolling.
          required: false
          schema:
            type: string
        - in: query
          name: sortBy
          description: 'Sort list by: businessTime, utcTime (default is businessTime)'
          required: false
          schema:
            type: string
        - in: query
          name: sortReverse
          description: 'Reverse sort order'
          required: false
          schema:
            type: boolean

      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eventsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'







  ########################
  ### segments
  ########################

  '/v2/segments/organizations/{cid}':
    get:
      summary: List Segments
      description: |
        List the segments of an organization
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_read, segments_read
      parameters:
        - $ref: '#/components/parameters/organizationCid'
      tags:
        - segments
      responses:
        '200':
          description: Array with the segments
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated:
                    type: string
                  size:
                    type: number


                  segments:
                    type: array
                    items:
                      $ref: '#/components/schemas/segmentListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  ########################
  ### Hotspots
  ########################



  '/v3/hotspots':
    post:
      summary: Create a new hotspot
      description: |
        Create a new hotspot        
        Note:        
        Depending on the routerType, the fields macAddress, hotspotIdentifier, and ssid may be required, optional, or not allowed. Please refer to the documentation for further information.        
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: hotspots_write, organization_write
      tags:
        - hotspots
      requestBody:
        description: " "
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - routerType
                - macAddress
                - latitude
                - longitude
                - organziationId
                - locationId
              properties:
                organizationId:
                  type: string
                venueId:
                  type: string
                name:
                  type: string
                description:
                  type: string
                routerType:
                  type: string
                  enum:
                    -  Aerohive Networks, Inc.
                    -  Aruba Networks
                    -  Browan Communication, Inc.
                    -  Cambium Networks Limited
                    -  chillispot
                    -  Cisco Systems
                    -  coovachilli
                    -  Cradlepoint
                    -  dd-wrt
                    -  endian
                    -  Endian s.r.l.
                    -  EnGenius
                    -  EnGenius CP ready
                    -  Extreme Networks
                    -  FortiNet
                    -  Hewlett Packard
                    -  Huawei
                    -  ICC
                    -  Icomera Moovbox
                    -  IgniteNet
                    -  LigoWave VAC
                    -  Meraki, Inc.
                    -  Mojo Networks, Inc.
                    -  Nomadix, Inc.
                    -  Open Mesh, Inc.
                    -  PowerCloud Systems, Inc.
                    -  Routerboard.com
                    -  routeros
                    -  Ruckus Wireless (Controller)
                    -  Ruckus Wireless (SCG)
                    -  Ruckus Wireless (Standalone)
                    -  Ruckus Wireless (Xclaim)
                    -  Samsung
                    -  tanaza
                    -  tanaza_os
                    -  Teldat
                    -  Teltonika
                    -  Tiesse SpA
                    -  Ubiquiti Networks, Inc.
                    -  Wi-Next s.r.l.
                    -  Wilibox Deliberant Group LLC
                    -  Xirrus Inc
                    -  Zebra Technologies Inc
                macAddress:
                  type: string
                hotspotIdentifier:
                  description: use according with routerType
                  type: string
                ssid:
                  description: use according with routerType
                  type: string
                addressAsLocation:
                  type: boolean
                  description: Use address, city, country, zip and state from location
                country:
                  type: string
                  description: country code as ISO 3166-1 alpha-2. Required if addressAsLocation is false
                address:
                  type: string
                  description: Required if addressAsLocation is false
                city:
                  type: string
                  description: Required if addressAsLocation is false
                state:
                  type: string
                  description: Required if addressAsLocation is false
                zip:
                  type: string
                  description: Required if addressAsLocation is false
                latitude:
                  type: number
                longitude:
                  type: number


      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated:
                    type: string
                  status:
                    type: string
                  locationId:
                    type: string
                  hotspotId:
                    type: string
  '/v3/hotspots/{hotspotId}':
    get:
      summary: Get an Access Point
      description: |
        Get Access Point by Id
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_read, hotspots_read
      parameters:
        - in: path
          name: hotspotId
          description: 'Hotspot id'
          required: true
          schema:
            type: string

      tags:
        - hotspots
      responses:
        '200':
          description: Hotspot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/hotspotResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
    put:
      summary: Update an hotspot
      description: |
        Update an hotspot.
        
        Note: 
        The properties venueId, routerType, macAddress, hotspotIdentifier, and ssid are not allowed.          
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: hotspots_write, organization_write           

      parameters:
        - in: path
          name: hotspotId
          description: 'Hotspot id'
          required: true
          schema:
            type: string

      tags:
        - hotspots
      requestBody:
        description: " "
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - organziationId
                - locationId
              properties:
                name:
                  type: string
                description:
                  type: string
                country:
                  type: string
                  description: country code as ISO 3166-1 alpha-2. Required if addressAsLocation is false
                address:
                  type: string
                  description: Required if addressAsLocation is false
                city:
                  type: string
                  description: Required if addressAsLocation is false
                state:
                  type: string
                  description: Required if addressAsLocation is false
                zip:
                  type: string
                  description: Required if addressAsLocation is false
                latitude:
                  type: number
                longitude:
                  type: number
                enabled:
                  type: boolean

      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated:
                    type: string
                  status:
                    type: string
                  locationId:
                    type: string
                  hotspotId:
                    type: string
    delete:
      summary: Delete an hotspot
      description: |
        Delete an hotspot
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: hotspots_write, organization_write
      parameters:
        - in: path
          name: hotspotId
          description: 'Hotspot id'
          required: true
          schema:
            type: string


      tags:
        - hotspots
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated:
                    type: string
                  status:
                    type: string



  '/v3/hotspots/identifier/{hotspotIdentifier}':
    get:
      summary: Get an Acess Point by hotspot identifier
      description: |
        Get an Access Point by hotspot identifier
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_read, hotspots_read
      parameters:
        - in: path
          name: hotspotIdentifier
          description: 'Hotspot identifier as configured in the dashboard'
          required: true
          schema:
            type: string

      tags:
        - hotspots
      responses:
        '200':
          description: Hotspot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/hotspotResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  '/v3/hotspots/organizations/{cid}':
    get:
      summary: List of access points of an organization
      description: |
        List hotspots for the organization
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_read, hotspots_read
      parameters:
        - $ref: '#/components/parameters/organizationCid'
        - in: query
          name: creationDateStart
          description: 'Filter hotspots with date bigger than. Format YYYY-MM-DD'
          required: false
          schema:
            type: string
        - in: query
          name: creationDateStop
          description: 'Filter hotspots with date lower than. Format YYYY-MM-DD'
          required: false
          schema:
            type: string
        - in: query
          name: name
          description: 'Filter by name'
          required: false
          schema:
            type: string
        - in: query
          name: macAddress
          description: 'Filter by hotspot macaddress'
          required: false
          schema:
            type: string
        - in: query
          name: hotspotIdentifier
          description: 'Filter by hotspot identifier'
          required: false
          schema:
            type: string
        - in: query
          name: venueId
          description: 'Filter by venueId'
          required: false
          schema:
            type: string
        - in: query
          name: deleted
          description: 'Filter by deleted properties. Default deleted=false'
          required: false
          schema:
            type: string

        - in: query
          name: limit
          required: false
          schema:
            type: string
        - in: query
          name: offset
          required: false
          schema:
            type: string
      tags:
        - hotspots
      responses:
        '200':
          description: Array with the hotspots
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/hotspotsListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'



  ########################
  ### organizations / locations
  ########################

  '/v2/organizations/{cid}/accountings':
    get:
      summary: List all WiFi Connections of the organization
      description: |
        Retrieve all WiFi connection of the organization
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>: organization_read, customer_read
      parameters:
        - $ref: '#/components/parameters/organizationCid'
        - in: query
          name: sid
          description: 'The sid can be used to retrieve a large number of results from a search request. Read here to get more information about how to use the sid'
          required: false
          schema:
            type: string
        - in: query
          name: size
          description: Number of WiFi Connections returned by the request. Allowed values between 1 and 10000. It is not possible to change this values during a scrolling.
          required: false
          schema:
            type: string
        - in: query
          name: locationId
          description: Return WiFi Connections occurred on a specific Location Id
          required: false
          schema:
            type: string
        - in: query
          name: hotspotId
          description: Return WiFi Connections occurred on a specific Access Point Id
          required: false
          schema:
            type: string
        - in: query
          name: dateStart
          description: "Return WiFi Connections with date >= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z' or '2019-07-31' but is necessary set timezone"
          required: false
          schema:
            type: string
        - in: query
          name: dateEnd
          description: "Return WiFi Connections with creation date >= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z' or '2019-07-31' but is necessary set timezone"
          required: false
          schema:
            type: string
        - in: query
          name: timeZone
          description: "Timezone"
          required: false
          schema:
            type: string

      tags:
        - organizations
      responses:
        '200':
          description: Array with the list of WiFi Connections
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated:
                    type: string
                  sId:
                    type: string
                  count:
                    type: number
                  connections:
                    type: array
                    items:
                      type: object
                      properties:
                        customerId:
                          type: string
                        organizationId:
                          type: string
                        start:
                          type: string
                        startBusiness:
                          type: string
                        stop:
                          type: string
                        stopBusiness:
                          type: string
                        duration:
                          type: number
                        traffic:
                          type: number
                        locationName:
                          type: string
                        locationId:
                          type: string
                        hotspotName:
                          type: string
                        hotspotIdentifier:
                          type: string
                        hotspotId:
                          type: string
                        latitude:
                          type: number
                        longitude:
                          type: number
                        macAddressClient:
                          type: string
                        ipAddressClient:
                          type: string
                        terminateCause:
                          type: string

        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'



  '/v1/organizations/{cid}/locations':
    get:
      summary: List Locations of the organization
      description: |
        Retrieve all Locations configured in the organization
        <br><b>Role</b>: Location Manager, Organization Manager
        <br><b>Scope</b>: organization_read
      parameters:
        - $ref: '#/components/parameters/organizationCid'
        - in: query
          name: tags
          description: 'Filter by a tag or a list of tags comma separated'
          required: false
          schema:
            type: string

      tags:
        - locations
      responses:
        '200':
          description: Array with the list of Locations
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated:
                    type: string
                  size:
                    type: number


                  locations:
                    type: array
                    items:
                      $ref: '#/components/schemas/locationListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
    post:
      summary: Add a new location
      description: |
        Add a new location
        <br>
        Read https://create.cloud4wi.com/dev-hub/api-reference/getting-started/locations for details
        <br>
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>:  organization_write
      parameters:
        - $ref: '#/components/parameters/organizationCid'
      tags:
        - locations
      requestBody:
        description: desc
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                loginProfileId:
                  type: string
                timezone:
                  type: string
                  description: In format "Europe/Rome"
                locationProfileId:
                  type: string
                welcomePortalId:
                  type: string
                country:
                  type: string
                  description: country code as ISO 3166-1 alpha-2.
                address:
                  type: string
                city:
                  type: string
                state:
                  type: string
                zip:
                  type: string
                onNet:
                  type: boolean
                  description: https://cloud4wi.zendesk.com/hc/en-us/articles/200923267-What-is-the-On-Net-option-for-the-Venue-
                externalId:
                  type: string
                description:
                  type: string
                categoryName:
                  type: string
                  description: 'valid category: other, consumer electronics, sports center, fast food, disco, pools, bar, ice cream, piano bar, underwear, cinema, computers, footwear, gyms, sandwich, sporting goods, hairstyle, public administration, phone, hotels, pizzeria, coffee, restaurants, clothing, pub'
                tags:
                  type: array
                  items:
                    type: string
                enabled:
                  type: boolean
                organizationPlanId:
                  type: string
                  description: internet plan id at organization level


              required:
                - name
                - loginProfileId
                - timezone
                - locationProfileId
                - welcomePortalId
                - country
                - address
                - city
                - state
                - zip



      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated:
                    type: string
                  status:
                    type: string
                  locationId:
                    type: string
                  newTags:
                    type: array
                    items:
                      type: string
                      description: new tags added


  '/v1/organizations/{cid}/locations/{lid}':
    put:
      summary: Update a location
      description: |
        Update a location
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>:  organization_write
      parameters:
        - $ref: '#/components/parameters/organizationCid'
        - $ref: '#/components/parameters/locationCid'
      tags:
        - locations

      requestBody:
        description: desc
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                categoryName:
                  type: string
                  description: 'valid category: other, consumer electronics, sports center, fast food, disco, pools, bar, ice cream, piano bar, underwear, cinema, computers, footwear, gyms, sandwich, sporting goods, hairstyle, public administration, phone, hotels, pizzeria, coffee, restaurants, clothing, pub'
                tags:
                  type: array
                  items:
                    type: string
                externalId:
                  type: string
                country:
                  type: string
                  description: country code as ISO 3166-1 alpha-2.
                address:
                  type: string
                city:
                  type: string
                state:
                  type: string
                zip:
                  type: string
                timezone:
                  type: string
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated:
                    type: string
                  status:
                    type: string
                  locationId:
                    type: string
                  newTags:
                    type: array
                    items:
                      type: string
                      description: new tags added

    delete:
      summary: Delete a location
      description: |
        Delete a location
        <br><b>Role</b>: Organization Manager
        <br><b>Scope</b>:  organization_write
      parameters:
        - $ref: '#/components/parameters/organizationCid'
        - $ref: '#/components/parameters/locationCid'
      tags:
        - locations
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated:
                    type: string
                  status:
                    type: string


  '/v1/locations/{lid}':
    get:
      summary: Get a Location by id
      description: |
        List locations belongs to an organization
        <br><b>Scope</b>: organization_read
      parameters:
        - in: path
          name: lid
          description: 'Location id'
          required: true
          schema:
            type: string

      tags:
        - locations
      responses:
        '200':
          description: Array with the list of Locations
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated:
                    type: string
                  size:
                    type: number


                  location:
                    $ref: '#/components/schemas/locationListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  ##############################
  ### analytics / wifi-reports
  ##############################

  '/v2/organizations/{cid}/analytics/wifi_reports/active_users_per_day':
    post:
      summary: Generate active users per day report
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageNumberOfUsersConnectedEachDay:
                    type: integer
                    description: Average number of users connected each day
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        time:
                          type: string
                          description: Time of the connection
                        value:
                          type: integer
                          description: Value of the active users
                      example:
                        time: "string"
                        value: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/active_users_per_day_per_location':
    post:
      summary: Generate active users per day per location report
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageNumberOfUsersConnectEachDayPerLocation:
                    type: integer
                    description: Average number of users connected each day per location
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        locationId:
                          type: string
                          description: ID of the location
                        valueAvgOverPeriod:
                          type: integer
                          description: Average value of users over the period
                        valueSum:
                          type: number
                          description: Sum of the values over the period
                      example:
                        locationId: "string"
                        valueAvgOverPeriod: 0
                        valueSum: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/active_users_per_day_per_organization':
    post:
      summary: Generate active users per day per organization report
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageNumberOfUsersConnectEachDayPerOrganization:
                    type: integer
                    description: Average number of users connected each day per organization
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        organizationId:
                          type: string
                          description: ID of the organization
                        valueAvgOverPeriod:
                          type: integer
                          description: Average value of users over the period
                        valueSum:
                          type: number
                          description: Sum of the values over the period
                      example:
                        organizationId: "string"
                        valueAvgOverPeriod: 0
                        valueSum: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/connection_time_breakdown':
    post:
      summary: Generate connection time breakdown report
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        duration:
                          type: string
                          description: Duration of the connection
                        value:
                          type: integer
                          description: Value of the connection duration
                      example:
                        duration: "string"
                        value: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/connection_time_per_day':
    post:
      summary: Generate connection time per day report
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageConnectionTimeEachDay:
                    type: integer
                    description: Average connection time each day
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        time:
                          type: string
                          description: Time of the connection
                        value:
                          type: integer
                          description: Value of the connection time
                      example:
                        time: "string"
                        value: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/connection_time_per_day_per_location':
    post:
      summary: Generate connection time per day per location report
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageConnectionTimeEachDayPerLocation:
                    type: integer
                    description: Average connection time each day per location
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        locationId:
                          type: string
                          description: ID of the location
                        valueAvgOverPeriod:
                          type: integer
                          description: Average value over the period
                        valueAvgOverPeriodOverActiveUsers:
                          type: integer
                          description: Average value over the period over active users
                        valueSum:
                          type: integer
                          description: Sum of values
                      example:
                        locationId: "string"
                        valueAvgOverPeriod: 0
                        valueAvgOverPeriodOverActiveUsers: 0
                        valueSum: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/connection_time_per_day_per_organization':
    post:
      summary: Generate connection time per day per organization report
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageConnectionTimeEachDayPerOrganization:
                    type: integer
                    description: Average connection time each day per organization
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        organizationId:
                          type: string
                          description: ID of the organization
                        valueAvgOverPeriod:
                          type: integer
                          description: Average value over the period
                        valueAvgOverPeriodOverActiveUsers:
                          type: integer
                          description: Average value over the period over active users
                        valueSum:
                          type: integer
                          description: Sum of values
                      example:
                        organizationId: "string"
                        valueAvgOverPeriod: 0
                        valueAvgOverPeriodOverActiveUsers: 0
                        valueSum: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/connections_per_day':
    post:
      summary: Generate number of connections per day report
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageNumberOfConnectionsEachDay:
                    type: integer
                    description: Average number of connections each day
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        time:
                          type: string
                          description: Time of the data point
                        value:
                          type: integer
                          description: Number of connections
                      example:
                        time: "string"
                        value: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/connections_per_day_per_location':
    post:
      summary: Generate number of connections per day per location report
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageNumberOfConnectionsEachDayPerLocation:
                    type: integer
                    description: Average number of connections each day per location
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        locationId:
                          type: string
                          description: ID of the location
                        valueAvgOverPeriod:
                          type: integer
                          description: Average value over the period
                        valueSum:
                          type: integer
                          description: Sum of values
                      example:
                        locationId: "string"
                        valueAvgOverPeriod: 0
                        valueSum: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/connections_per_day_per_organization':
    post:
      summary: Generate number of connections per day per organization report
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageNumberOfConnectionsEachDayPerOrganization:
                    type: integer
                    description: Average number of connections each day per organization
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        organizationId:
                          type: string
                          description: ID of the organization
                        valueAvgOverPeriod:
                          type: integer
                          description: Average value over the period
                        valueSum:
                          type: integer
                          description: Sum of values
                      example:
                        organizationId: "string"
                        valueAvgOverPeriod: 0
                        valueSum: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/day_of_week_breakdown':
    post:
      summary: Generate breakdown of connections by day of the week
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        day:
                          type: string
                          description: Day of the week
                        value:
                          type: integer
                          description: Value for the day
                      example:
                        day: "Monday"
                        value: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/exchange_data_breakdown':
    post:
      summary: Generate breakdown of exchange data
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        value:
                          type: integer
                          description: Value
                        volume:
                          type: string
                          description: Volume
                      example:
                        value: 0
                        volume: "string"

  '/v2/organizations/{cid}/analytics/wifi_reports/exchanged_data_per_day':
    post:
      summary: Generate exchanged data per day
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageDataExchangeEachDay:
                    type: integer
                    description: Average data exchange for each day
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        time:
                          type: string
                          description: Time of the day
                        value:
                          type: integer
                          description: Value for the time
                      example:
                        time: "string"
                        value: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/exchanged_data_per_day_per_location':
    post:
      summary: Generate exchanged data per day per location
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageExchangedDataEachDayPerLocation:
                    type: integer
                    description: Average exchanged data for each day per location
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        locationId:
                          type: string
                          description: ID of the location
                        valueAvgOverPeriod:
                          type: integer
                          description: Average value over the period
                        valueAvgOverPeriodOverActiveUsers:
                          type: integer
                          description: Average value over the period over active users
                        valueSum:
                          type: integer
                          description: Sum of values
                      example:
                        locationId: "string"
                        valueAvgOverPeriod: 0
                        valueAvgOverPeriodOverActiveUsers: 0
                        valueSum: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/exchanged_data_per_day_per_organization':
    post:
      summary: Generate exchanged data per day per organization
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageExchangedDataEachDayPerOrganization:
                    type: integer
                    description: Average exchanged data for each day per organization
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        organizationId:
                          type: string
                          description: ID of the organization
                        valueAvgOverPeriod:
                          type: integer
                          description: Average value over the period
                        valueAvgOverPeriodOverActiveUsers:
                          type: integer
                          description: Average value over the period over active users
                        valueSum:
                          type: integer
                          description: Sum of values
                      example:
                        organizationId: "string"
                        valueAvgOverPeriod: 0
                        valueAvgOverPeriodOverActiveUsers: 0
                        valueSum: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/network_auth_method_breakdown':
    post:
      summary: Generate network authentication method breakdown
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        method:
                          type: string
                          description: Authentication method
                        percentageValue:
                          type: number
                          description: Percentage value of the method
                        value:
                          type: integer
                          description: Value of the method
                      example:
                        method: "string"
                        percentageValue: 0.0
                        value: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/returning_users_per_day':
    post:
      summary: Generate percentage of returning users per day
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageDailyPercentageOfReturningUsers:
                    type: number
                    description: Average daily percentage of returning users
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        percentageValue:
                          type: number
                          description: Percentage value of returning users
                        time:
                          type: string
                          description: Time period
                        value:
                          type: integer
                          description: Value of returning users
                      example:
                        percentageValue: 0.0
                        time: "string"
                        value: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/returning_users_per_day_per_location':
    post:
      summary: Generate percentage of returning users per day per location
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averagePercentageOfReturningUsersByLocation:
                    type: number
                    description: Average percentage of returning users by location
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        locationId:
                          type: string
                          description: ID of the location
                        percentageValue:
                          type: number
                          description: Percentage value of returning users by location
                        value:
                          type: integer
                          description: Value of returning users by location
                      example:
                        locationId: "string"
                        percentageValue: 0.0
                        value: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/returning_users_per_day_per_organization':
    post:
      summary: Generate percentage of returning users per day per organization
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averagePercentageOfReturningUsersConnectEachDayPerOrganization:
                    type: number
                    description: Average percentage of returning users connected each day per organization
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        organizationId:
                          type: string
                          description: ID of the organization
                        percentageValueAvgOverPeriod:
                          type: number
                          description: Average percentage value of returning users over the period
                        percentageValueSum:
                          type: number
                          description: Sum of percentage values of returning users
                        valueAvgOverPeriod:
                          type: integer
                          description: Average value of returning users over the period
                        valueSum:
                          type: integer
                          description: Sum of returning users
                      example:
                        organizationId: "string"
                        percentageValueAvgOverPeriod: 0
                        percentageValueSum: 0
                        valueAvgOverPeriod: 0
                        valueSum: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/time_of_day_breakdown':
    post:
      summary: Generate breakdown of user activity by time of day
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        hour:
                          type: integer
                          description: Hour of the day (0-23)
                        value:
                          type: integer
                          description: Value of user activity at this hour
                      example:
                        hour: 0
                        value: 0

  '/v2/organizations/{cid}/analytics/wifi_reports/user_source_breakdown':
    post:
      summary: Generate breakdown of user activity by source
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]

      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        percentageValue:
                          type: number
                          description: Percentage value of user activity from a specific source
                        source:
                          type: string
                          description: Source of the user activity
                        value:
                          type: integer
                          description: Value of user activity from a specific source
                      example:
                        percentageValue: 0
                        source: "string"
                        value: 0

  ##############################
  ### analytics / acquisitions
  ##############################

  '/v2/organizations/{cid}/analytics/acquisitions/consent_collection_breakdown':
    post:
      summary: Generate breakdown of consent collection by source
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                organizations:
                  type: array
                  items:
                    type: string
                  example: [ "string" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        consentName:
                          type: string
                          description: Name of the consent
                        percentageValue:
                          type: number
                          format: float
                          description: Percentage value of consent collected
                        value:
                          type: integer
                          description: Value of consent collected
                      example:
                        consentName: "string"
                        percentageValue: 0.0
                        value: 0

  '/v2/organizations/{cid}/analytics/acquisitions/contact_properties_breakdown':
    post:
      summary: Generate breakdown of contact properties by source
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                organizations:
                  type: array
                  items:
                    type: string
                  example: [ "string" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        contactProperty:
                          type: string
                          description: Name of the contact property
                        percentageValue:
                          type: number
                          description: Percentage value of contact property
                        value:
                          type: integer
                          description: Value of contact property
                      example:
                        contactProperty: "string"
                        percentageValue: 0
                        value: 0

  '/v2/organizations/{cid}/analytics/acquisitions/kpis':
    post:
      summary: Generate acquisition KPIs
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                organizations:
                  type: array
                  items:
                    type: string
                  example: [ "string" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  marketingOptIn:
                    type: integer
                    description: KPIs for marketing opt-in
                    example: 0
                  newContacts:
                    type: integer
                    description: Number of new contacts
                    example: 0
                  totalContacts:
                    type: integer
                    description: Total number of contacts
                    example: 0
  
  '/v2/organizations/{cid}/analytics/acquisitions/subscription_method_breakdown':
    post:
      summary: Generate subscription method breakdown
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                organizations:
                  type: array
                  items:
                    type: string
                  example: [ "string" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        method:
                          type: string
                          description: Subscription method
                        percentageValue:
                          type: number
                          description: Percentage value of subscription method
                        value:
                          type: integer
                          description: Value of subscription method
                      example:
                        method: "string"
                        percentageValue: 0
                        value: 0

  '/v2/organizations/{cid}/analytics/acquisitions/subscription_source_breakdown':
      post:
        summary: Generate subscription source breakdown
        parameters:
          - name: cid
            in: path
            required: true
            schema:
              type: string
            description: Encoded ID of the organization
        tags:
          - analytics
        requestBody:
          required: true
          content:
            application/json:
              schema:
                type: object
                properties:
                  startDate:
                    type: string
                    format: date
                    example: "2024-10-18"
                  endDate:
                    type: string
                    format: date
                    example: "2024-10-25"
                  locations:
                    type: array
                    items:
                      type: string
                    example: [ "ff8080815ced2ace015d804ee45011ba" ]
                  organizations:
                    type: array
                    items:
                      type: string
                    example: [ "string" ]
                  sources:
                    type: array
                    items:
                      type: string
                    example: [ "apis", "test" ]
        responses:
          '200':
            description: Successful response
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          source:
                            type: string
                            description: Subscription source
                          percentageValue:
                            type: number
                            description: Percentage value of subscription source
                          value:
                            type: integer
                            description: Value of subscription source
                        example:
                          source: "string"
                          percentageValue: 0.0
                          value: 0

  '/v2/organizations/{cid}/analytics/acquisitions/new_contacts_per_day':
    post:
      summary: Generate acquisitions trend with selectedGraph set to new_contacts
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                organizations:
                  type: array
                  items:
                    type: string
                  example: [ "string" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
                selectedGraph:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageNumberOfUsersMarketingEachDay:
                    type: integer
                    description: Average number of users marketing each day
                  averageNumberOfUsersSignedUpEachDay:
                    type: integer
                    description: Average number of users signed up each day
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        time:
                          type: string
                          description: Time point of the trend data
                        value:
                          type: integer
                          description: Value at the time point
                    example:
                      time: "string"
                      value: 0

  '/v2/organizations/{cid}/analytics/acquisitions/marketing_opt_in_per_day':
    post:
      summary: Generate acquisitions trend with selectedGraph set to marketing_opt_in
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                organizations:
                  type: array
                  items:
                    type: string
                  example: [ "string" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
                selectedGraph:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageNumberOfUsersMarketingEachDay:
                    type: integer
                    description: Average number of users marketing each day
                  averageNumberOfUsersSignedUpEachDay:
                    type: integer
                    description: Average number of users signed up each day
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        time:
                          type: string
                          description: Time point of the trend data
                        value:
                          type: integer
                          description: Value at the time point
                    example:
                      time: "string"
                      value: 0

  '/v2/organizations/{cid}/analytics/acquisitions/new_contacts_per_day_per_location':
    post:
      summary: Generate acquisitions trend by locations with selectedGraph set to new_contacts
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                organizations:
                  type: array
                  items:
                    type: string
                  example: [ "string" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
                selectedGraph:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageNumberOfUsersMarketingEachDayPerLocation:
                    type: integer
                    description: Average number of users marketing each day per location
                  averageNumberOfUsersSignedUpEachDayPerLocation:
                    type: integer
                    description: Average number of users signed up each day per location
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        locationId:
                          type: string
                          description: ID of the location
                        percentageValue:
                          type: number
                          description: Percentage value of the metric for the location
                        valueAvgOverPeriod:
                          type: integer
                          description: Average value over the period for the location
                        valueSum:
                          type: integer
                          description: Sum of values over the period for the location
                    example:
                      locationId: "string"
                      percentageValue: 0.0
                      valueAvgOverPeriod: 0
                      valueSum: 0

  '/v2/organizations/{cid}/analytics/acquisitions/marketing_opt_in_per_day_per_location':
    post:
      summary: Generate acquisitions trend by locations with selectedGraph set to marketing_opt_in
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                organizations:
                  type: array
                  items:
                    type: string
                  example: [ "string" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
                selectedGraph:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageNumberOfUsersMarketingEachDayPerLocation:
                    type: integer
                    description: Average number of users marketing each day per location
                  averageNumberOfUsersSignedUpEachDayPerLocation:
                    type: integer
                    description: Average number of users signed up each day per location
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        locationId:
                          type: string
                          description: ID of the location
                        percentageValue:
                          type: number
                          description: Percentage value of the metric for the location
                        valueAvgOverPeriod:
                          type: integer
                          description: Average value over the period for the location
                        valueSum:
                          type: integer
                          description: Sum of values over the period for the location
                    example:
                      locationId: "string"
                      percentageValue: 0.0
                      valueAvgOverPeriod: 0
                      valueSum: 0

  '/v2/organizations/{cid}/analytics/acquisitions/verified_touchpoints':
    post:
      summary: Generate verified touchpoints data
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                  format: date
                  example: "2024-10-18"
                endDate:
                  type: string
                  format: date
                  example: "2024-10-25"
                locations:
                  type: array
                  items:
                    type: string
                  example: [ "ff8080815ced2ace015d804ee45011ba" ]
                organizations:
                  type: array
                  items:
                    type: string
                  example: [ "string" ]
                sources:
                  type: array
                  items:
                    type: string
                  example: [ "apis", "test" ]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  emailVerifiedPercentageOverEmails:
                    type: number
                    description: Percentage of verified emails over total emails
                  emailVerifiedPercentageOverTotal:
                    type: number
                    description: Percentage of verified emails over total touchpoints
                  phoneVerifiedPercentageOverPhones:
                    type: number
                    description: Percentage of verified phones over total phones
                  phoneVerifiedPercentageOverTotal:
                    type: number
                    description: Percentage of verified phones over total touchpoints
              example:
                emailVerifiedPercentageOverEmails: 0.0
                emailVerifiedPercentageOverTotal: 0.0
                phoneVerifiedPercentageOverPhones: 0.0
                phoneVerifiedPercentageOverTotal: 0.0

  ##################################
  ### analytics / audience-insights
  ##################################

  '/v2/organizations/{cid}/analytics/audience-insights/age_breakdown':
    post:
      summary: Generate audience insights data
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                endDate:
                  type: string
                locations:
                  type: array
                  items:
                    type: string
                sources:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  availableForContacts:
                    type: integer
                    description: Total number of available contacts
                  availableForContactsPercentage:
                    type: number
                    description: Percentage of available contacts
                  biggestAgeBucket:
                    type: string
                    description: The age bucket with the largest number of contacts
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        age:
                          type: string
                          description: Age of the contacts in the bucket
                        percentageValue:
                          type: number
                          description: Percentage value of the contacts in the age bucket
                        value:
                          type: integer
                          description: The number of contacts in the age bucket
              example:
                availableForContacts: 0
                availableForContactsPercentage: 0.0
                biggestAgeBucket: "string"
                items:
                  - age: "string"
                    percentageValue: 0.0
                    value: 0

  '/v2/organizations/{cid}/analytics/audience-insights/contact_properties_breakdown':
    post:
      summary: Generate audience insights data
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                endDate:
                  type: string
                locations:
                  type: array
                  items:
                    type: string
                sources:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        contactProperty:
                          type: string
                          description: Specific contact property breakdown
                        percentageValue:
                          type: number
                          description: Percentage value of the contacts with this property
                        value:
                          type: integer
                          description: The number of contacts with this property
              example:
                items:
                  - contactProperty: "string"
                    percentageValue: 0.0
                    value: 0

  '/v2/organizations/{cid}/analytics/audience-insights/country_breakdown':
    post:
      summary: Generate audience insights country breakdown data
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                endDate:
                  type: string
                locations:
                  type: array
                  items:
                    type: string
                sources:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  availableForContacts:
                    type: integer
                    description: Total number of available contacts
                  availableForContactsPercentage:
                    type: number
                    description: Percentage of available contacts
                  biggestCountryBucket:
                    type: string
                    description: The country bucket with the largest number of contacts
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        country:
                          type: string
                          description: Country of the contacts in the bucket
                        percentageValue:
                          type: number
                          description: Percentage value of the contacts in the country bucket
                        value:
                          type: integer
                          description: The number of contacts in the country bucket
              example:
                availableForContacts: 0
                availableForContactsPercentage: 0.0
                biggestCountryBucket: "string"
                items:
                  - country: "string"
                    percentageValue: 0.0
                    value: 0

  '/v2/organizations/{cid}/analytics/audience-insights/gender_breakdown':
    post:
      summary: Generate audience insights gender breakdown data
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                endDate:
                  type: string
                locations:
                  type: array
                  items:
                    type: string
                sources:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  availableForContacts:
                    type: integer
                    description: Total number of available contacts
                  availableForContactsPercentage:
                    type: number
                    description: Percentage of available contacts
                  biggestGenderBucket:
                    type: string
                    description: The gender bucket with the largest number of contacts
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        gender:
                          type: string
                          description: Gender of the contacts in the bucket
                        percentageValue:
                          type: number
                          description: Percentage value of the contacts in the gender bucket
                        value:
                          type: integer
                          description: The number of contacts in the gender bucket
              example:
                availableForContacts: 0
                availableForContactsPercentage: 0.0
                biggestGenderBucket: "string"
                items:
                  - gender: "string"
                    percentageValue: 0.0
                    value: 0

  '/v2/organizations/{cid}/analytics/audience-insights/gender_breakdown_by_location':
    post:
      summary: Generate audience insights gender breakdown data by location
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                endDate:
                  type: string
                locations:
                  type: array
                  items:
                    type: string
                sources:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: object

  '/v2/organizations/{cid}/analytics/audience-insights/kpis':
    post:
      summary: Generate audience insights KPIs
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                endDate:
                  type: string
                locations:
                  type: array
                  items:
                    type: string
                sources:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  contacts:
                    type: integer
                    description: Total number of contacts
                  contactsMarketingOptIns:
                    type: number
                    description: Percentage of contacts with marketing opt-ins
                  emails:
                    type: integer
                    description: Total number of email contacts
                  emailsVerified:
                    type: number
                    description: Percentage of verified emails
                  phoneNumbers:
                    type: integer
                    description: Total number of phone number contacts
                  phoneNumbersVerified:
                    type: number
                    description: Percentage of verified phone numbers
              example:
                contacts: 0
                contactsMarketingOptIns: 0.0
                emails: 0
                emailsVerified: 0.0
                phoneNumbers: 0
                phoneNumbersVerified: 0.0

  '/v2/organizations/{cid}/analytics/audience-insights/language_breakdown':
    post:
      summary: Generate audience insights language breakdown
      parameters:
        - name: cid
          in: path
          required: true
          schema:
            type: string
          description: Encoded ID of the organization
      tags:
        - analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: string
                endDate:
                  type: string
                locations:
                  type: array
                  items:
                    type: string
                sources:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  availableForContacts:
                    type: integer
                  availableForContactsPercentage:
                    type: number
                  biggestLanguageBucket:
                    type: string
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        language:
                          type: string
                        percentageValue:
                          type: number
                        value:
                          type: integer
              example:
                availableForContacts: 0
                availableForContactsPercentage: 0.0
                biggestLanguageBucket: "string"
                items:
                  - language: "string"
                    percentageValue: 0.0
                    value: 0

########################
### COMPONENTS
########################

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  ########################
  ### PARAMETERS
  ########################

  parameters:
    serviceIss:
      name: iss
      in: path
      description: iss of the service (srv-123456789)
      required: true
      schema:
        type: string
    userId:
      name: id
      in: path
      description: id of the user (ID of the table w.USERS) passed inside the JWT received at login
      required: true
      schema:
        type: string
    organizationCid:
      name: cid
      in: path
      description: id of the organization (aka tenant)
      required: true
      schema:
        type: string
    locationCid:
      name: lid
      in: path
      description: id of the location
      required: true
      schema:
        type: string
    serviceCid:
      name: cid
      in: path
      description: id of the service
      required: true
      schema:
        type: string
    userCid:
      name: cid
      in: path
      description: id of the customer
      required: true
      schema:
        type: string
    hotspotCid:
      name: hotspotId
      in: path
      description: id of the hotspot
      required: true
      schema:
        type: string

  ########################
  ### SCHEMA
  ########################
  schemas:
    updateCustomer:
      type: object
      properties:





        firstName:
          type: string
          description: First name

        lastName:
          type: string
          description: Last name

        phoneNumber:
          type: string
          description: Phone number in E.164 format
          example: "+14155552671"

        phoneVerified:
          type: boolean
          description: Phone number is verified

        email:
          type: string
          description: Customer email

        emailVerified:
          type: boolean
          description: Email address is verified

        gender:
          type: string
          description: Gender of customer
          enum: [null,"male","female","other"]

        birthDate:
          type: string
          description: Birthdate. Format YYYY-MM-DD
          example: "1975-03-16"

        language:
          type: string
          description: "Customer language. Format: ISO 639-1 codes"
          example: "en"



        country:
          type: string
          description: "Customer country. Format: ISO 3166-2 codes"
          example: "gb"

        zipCode:
          type: string
          description: Zipcode

        companyName:
          type: string
          description: Company name

        civilStatus:
          type: string
          description: Civil status
          enum: [null,"Mr","Miss","Lady"]

        doubleOptin:
          type: string
          description: Double optin
          enum: [null,"confirmed","confirm_waiting"]

        custom:
          type: object
          description: Custom attributes
          example: '{"custom1":"custom value","property": "1234"}'



        document:
          type: object
          properties:
            memberId:
              type: string
            number:
              type: string
            passportNumber:
              type: string
            personalId:
              type: string
            type:
              type: string
        extId:
          type: string
          description: Identifier of the customer inside an external service

        extProp1:
          type: string
          description: Identifier of the customer inside an external service

        extProp2:
          type: string
          description: Identifier of the customer inside an external service

    policiesUpdate:
      type: object
      properties:
        policies:
          type: array
          items:
            $ref: '#/components/schemas/policyUpdate'
    policyUpdate:
      type: object
      properties:
        policyKey:
          type: string
          description: policy name
        accepted:
          type: boolean
          description: true/false
    responseOk:
      type: object
      properties:
        status:
          type: string
          description: OK
        generated:
          type: string
          description: date time of response
    errorResponse:
      type: object
      properties:
        message:
          type: string
          description: 'Error message'

    ########################
    ### RESPONSE
    ########################

    eventsResponse:
      type: object
      properties:
        status:
          type: string
          description: OK
        generated:
          type: string
          description: date time of response
        count:
          type: number
        events:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                description: 'visit,signup, login, send_email,open_email,click_email,send_sms,click_sms,survey, promo'
              id:
                type: string
              visit:
                description: 'Available if type is visit'
                type: object
                properties:
                  startAt:
                    type: string
                  startAtLocal:
                    type: string
                  timezone:
                    type: string
                  duration:
                    type: integer
                    format: int32
              signup:
                type: object
                description: 'Available if type is signup'
                properties:
                  source:
                    type: string
              email:
                type: object
                description: 'Available if type is *_email'
                properties:
                  campaignId:
                    type: string
                  communicationId:
                    type: string
                  channel:
                    type: string
                  campaignName:
                    type: string
                  email:
                    type: string
              sms:
                type: object
                description: 'Available if type is *_sms'
                properties:
                  campaignId:
                    type: string
                  communicationId:
                    type: string
                  channel:
                    type: string
                  campaignName:
                    type: string
                  phone:
                    type: string
                  prefix:
                    type: string
              survey:
                type: object
                description: 'Available if type is survey'
                properties:
                  campaignId:
                    type: string
                  campaignName:
                    type: string
                  answerId:
                    type: string
                  questions:
                    type: object
                    properties:
                      question_1:
                        type: string
                  answers:
                    type: object
                    properties:
                      answer_1:
                        type: string
              promo:
                type: object
                description: 'Available if type is promo'
                properties:
                  type:
                    type: string





    hotspotsListResponse:
      type: object
      properties:
        status:
          type: string
          description: OK
        generated:
          type: string
          description: date time of response
        count:
          type: number
        hotspots:
          type: array
          items:
            $ref: '#/components/schemas/hotspot'
    hotspotResponse:
      type: object
      properties:
        status:
          type: string
          description: OK
        generated:
          type: string
          description: date time of response
        hotspot:
          $ref: '#/components/schemas/hotspot'

    hotspot:
      type: object
      properties:
        id:
          type: string
          description: Hotspot id
        name:
          type: string
          description: Hotspot name
        description:
          type: string
        firmware:
          type: string
        vendor:
          type: string
        hotspotIdentifier:
          type: string
        date:
          type: string
          description: date creation. Format iso8601
        macAddress:
          type: string
          description: Hotspot mac address
        venueId:
          type: string
        country:
          type: string
        city:
          type: string
        address:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        deleted:
          type: boolean

    locationListResponse:
      type: object
      properties:
        id:
          type: string
          description: location id
        name:
          type: string
          description: location name
        organziationId:
          type: string
          description: organization id
        lat:
          type: number
          description: latitude
        lng:
          type: number
          description: longitude
        timezone:
          type: string
          description: location's time zone
        address:
          type: object
          properties:
            address:
              type: string
              description: address
            city:
              type: string
              description: city
            state:
              type: string
              description: state/province/region
            zip:
              type: string
              description: zip/postal code
            country:
              type: string
              description: country
        externalId:
          type: string
        tags:
          type: array
          items:
            type: string


    segmentListResponse:
      type: object
      properties:
        id:
          type: string
          description: segment id
        name:
          type: string
          description: segment name
        description:
          type: string
          description: segment description
        lastRun:
          type: string
          description: last calculation of segment (date format iso8601)
        created:
          type: string
          description: segment creation date time (date format iso8601)
        modified:
          type: string
          description: segmente last modified date time (date format iso8601)
        segmentStatus:
          type: string
          description: segment status
        audience:
          type: number
          description: audience of segment

    responseOkUpdatePolicies:
      type: object
      properties:
        policyKey:
          type: boolean
          description: the new value of the policyKey

    customerListResponse:
      type: object
      properties:
        cid:
          type: string
          description: customer cid
        title:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        gender:
          type: string
        birthDate:
          type: string
        birthDay:
          type: string
        age:
          type: string
        country:
          type: string
        zipCode:
          type: string
        created:
          type: string
        modified:
          type: string
        email:
          type: string
        emailVerified:
          type: boolean
        phone:
          type: string
        phoneVerified:
          type: boolean
        signupMethod:
          type: string
        externalIdentityId:
          type: string
        username:
          type: string
        locked:
          type: boolean
        organizationCid:
          type: string
        locationCid:
          type: string
        system:
          type: string
        enabled:
          type: boolean
        type:
          type: string
        locationName:
          type: string
        personalId:
          type: string
        externalSource:
          type: string
        lastLogin:
          type: string
        segmentCids:
          type: string
        logins:
          type: number
        policies:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              accepted:
                type: boolean
        segments:
          type: array
          items:
            type: object
            properties:
              cid:
                type: string
              name:
                type: string
        extId:
          type: object
          properties:
            id:
              type: string
            prop1:
              type: string
            prop2:
              type: string

        metrics:
          $ref: '#/components/schemas/metricsResponse'
    customerUpdateResponse:
      type: object
      properties:
        status:
          type: string
          description: Request status. OK or KO if there is any error
        generated:
          type: string
          description: Time of current response
    metricsResponse:
      type: object
      properties:
        frequencyMonthlyVisit:
          type: number
        compassTopLocation:
          type: string
        compassTopLocationCount:
          type: number
        topFrequencyBuckets:
          type: string
        lastVisitVenue:
          type: string
        prefVisitWDay:
          type: string
        lastVisitDateUtc:
          type: string
        avgVisitLength:
          type: number
        countVisitedLocations:
          type: number
        prefVisitTimebucket:
          type: string
        prefVisitTimeHour:
          type: string
        lastVisitDateBusiness:
          type: string
        countTotalVisits:
          type: number
        conversionRate:
          type: number
        avgDaysBetweenVisits:
          type: number
