openapi: 3.0.0
info:
  version: 2.0.9
  title: Subscription signalling usages
  description: |

    #### Copyright
    © Aeris Communications, Inc. 2026. All rights reserved. No part of this document may be reproduced in any form without the written permission of the copyright owner.

    #### Disclaimer

    The contents of this document are subject to revision without notice due to continued progress in methodology, design and manufacturing.
    Aeris shall have no liability for any error or damage of any kind resulting from the use of this document.

    #### Trademark List

    All trademarks mentioned herein are the property of their respective owners.
    These are shown in the document Trademark Information.

    # Introduction

    This API provides resources for getting aggregated usage reports for subscriptions.

    ## Scope

    This document covers the following topics:

    — An overview of the API

    — A detailed description of all operations offered by the API

    ## Prerequisites
    In this document, it is assumed that the user is familiar with the following:

    — Java Script Object Notation (JSON)

    — Basic understanding of REST web services

    — The [OpenAPI Initiative](https://www.openapis.org/) for the standardized format used in this document.

    ## Related Information
    The definition and explanation of acronyms and terminology and typographic conventions can be found in the following documents:

    — IoTA Glossary of Terms and Acronyms

    — Typographic Conventions

    # General API Guidelines

    ## Compatibility

    API audience must be prepared for compatible API extensions:

    - Be tolerant with unknown fields in the payload (see also Fowler’s "TolerantReader" post), i.e. ignore new fields but do not eliminate them from payload if needed for subsequent PUT requests.
    - Be prepared that "x-extensible-enum" return parameter may deliver new values. Either be agnostic or provide default behavior for unknown values.
    - Be prepared to handle HTTP status codes not explicitly specified in endpoint definitions.
    - Follow the redirect when the server returns HTTP status 301 Moved Permanently.

    ## Security

    This section describes the security measures in the API. Security measures include authentication, authorization, and encryption.

    ### Authentication and Authorization

    The API uses OAuth2 and OpenID Connect (OIDC) for authentication and authorization.

    All API endpoints require authentication, which is performed by passing a token in the Authorization header in each request, preceded by the word Bearer and a space. See the following example:
    ```
    curl -i -X GET "https://<baseURL>/iot/api/xdr/reports/data-usage?sort=apn:asc" -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN_GOES_HERE>"
    ```
    To fetch the token using e.g. curl, submit the following:
    ```
    curl -X POST "https://<baseURL>/iot/api/auth/token" -H "Accept: application/vnd.dcp-v1+json" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&client_id=<client_id>&username=<username>&password=<password>"
    ```
    ### Encryption

    All API requests are encrypted using the HTTPS protocol to grant secure data transfer.

   
    ## Deprecation

    API deprecation will be reflected in the OpenAPI definition. If a method on a path, a whole path or even a whole API endpoint (multiple paths) should be deprecated, they will be marked as deprecated.
    During deprecation phase, a Deprecation header and a Sunset header fields will be added in the response.

    Example:
    ```
    Deprecation: Tue, 31 Dec 2024 23:59:59 GMT
    Sunset: Wed, 31 Dec 2025 23:59:59 GMT
    ```
    
    API audience should not start using a deprecated API.

    API audience is encouraged to monitor for Deprecation and Sunset header.

  x-audience: external-public
  x-api-id: 9905be63-e917-4d7f-b115-9da23f6392aa
tags:
  -
    name: Reports
    description: Aggregated reports of data and SMS usage for subscriptions.
servers:
  - url: https://iot-api.aeris.com/iot/api/xdr/reports
    description: API server
paths:
  /data-usage:
    get:
      tags:
        - Reports
      summary: Aggregated reports of data usage.
      description: |
        The reports are based on all of the IMSIs that you supply in the request.

        __LIMITATION:__

        Currently we have a limitation in our analytics system which prohibits us from supporting pagination of report items. This will be addressed in a future release.

        __NOTE:__

        * Data is only available from 8 days prior to the current time.
        * The maximum interval to query is 8 days.
        * Should specify one of 'imsi', 'msisdn' and 'sort'

      operationId: getAllDataUsageReports
      parameters:
        - $ref: '#/components/parameters/imsiParam'
        - $ref: '#/components/parameters/msisdnParam'
        - $ref: '#/components/parameters/fromParam'
        - $ref: '#/components/parameters/toParam'
        - $ref: '#/components/parameters/sortParam'
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit-Second:
              $ref: '#/components/headers/X-RateLimit-Limit-Second'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/X-RateLimit-Limit-Minute'
            X-RateLimit-Remaining-Second:
              $ref: '#/components/headers/X-RateLimit-Remaining-Second'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/X-RateLimit-Remaining-Minute'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataUsageResponse'
        '400':
          description: Bad reqeust.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/400Response'
        '401':
          description: Authentication Failure
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/401Response'
        '404':
          description: No Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/404Response'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/500Response'
        '503':
          description: Service Unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/503Response'
        '529':
          description: Service Overloaded
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/529Response'
        default:
          description: The standard http error codes will be given. 4XX for client errors and 5XX for server errors.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          OAuth2:
            - xdr-report-api.read
            - subscription-signalling-usages.read
  /sms-usage:
    get:
      tags:
        - Reports
      summary: Aggregated reports of SMS usage.
      description: |
        The reports are based on all of the IMSIs that you supply in the request.

        __NOTE:__

        * Data is only available from 8 days prior to the current time.
        * The maximum interval to query is 8 days.
        * Should specify one of 'imsi', 'msisdn' and 'sort'

      operationId: getAllSmsUsageReports
      parameters:
        - $ref: '#/components/parameters/imsiParam'
        - $ref: '#/components/parameters/msisdnParam'
        - $ref: '#/components/parameters/fromParam'
        - $ref: '#/components/parameters/toParam'
        - $ref: '#/components/parameters/sortParam'
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit-Second:
              $ref: '#/components/headers/X-RateLimit-Limit-Second'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/X-RateLimit-Limit-Minute'
            X-RateLimit-Remaining-Second:
              $ref: '#/components/headers/X-RateLimit-Remaining-Second'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/X-RateLimit-Remaining-Minute'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsUsageResponse'
        '400':
          description: Bad reqeust.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/400Response'
        '401':
          description: Authentication Failure
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/401Response'
        '404':
          description: No Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/404Response'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/500Response'
        '503':
          description: Service Unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/503Response'
        '529':
          description: Service Overloaded
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/529Response'
        default:
          description: The standard http error codes will be given. 4XX for client errors and 5XX for server errors.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          OAuth2:
            - xdr-report-api.read
            - subscription-signalling-usages.read
components:
  parameters:
    imsiParam:
      in: query
      name: imsi
      description: One or more IMSIs, comma separated, which identifies the subscription(s) to get reports for, e.g. "238208000000001,238208000000002". Can only be specified if msisdn is NOT.
      required: false
      style: form
      explode: false
      schema:
        type: string
      allowReserved: true
      example: '238208000000001,238208000000002'
    msisdnParam:
      in: query
      name: msisdn
      description: One or more MSISDNs, comma separated, which identifies the subscription(s) to get reports for, e.g. "01151601063,01151601064". Can only be specified if imsi is NOT.
      required: false
      style: form
      explode: false
      schema:
        type: string
      allowReserved: true
      example: '01151601063,01151601064'
    fromParam:
      in: query
      name: from
      description: The start time, UTC, for the time window processed to generate the response, e.g. "2019-06-28T00:00:00.000Z". If not input, will use default value "One hour ago (UTC)".
      required: false
      schema:
        type: string
        format: date-time
      allowReserved: true
      example: '2019-06-28T00:00:00.000Z'
    toParam:
      in: query
      name: to
      description: The end time, UTC, for the time window processed to generate the response, e.g. "2019-06-28T01:00:00.000Z". If not input, will use default value "Now (UTC)".
      required: false
      schema:
        type: string
        format: date-time
      allowReserved: true
      example: '2019-06-28T00:00:00.000Z'
    sortParam:
      in: query
      name: sort
      schema:
        type: string
        enum:
          - imsi:asc
          - imsi:desc
          - msisdn:asc
          - msisdn:desc
          - apn:asc
          - apn:desc
          - vplmn:asc
          - vplmn:desc
          - rat_type:asc
          - rat_type:desc
      description: |
        Sort parameter containing sort field and sort mode used for generating reports. This is used to group usage reports, if not input, will use default value ''imsi:asc".

        - imsi: The international mobile subscriber identity. An internationally standardized unique number to identify a mobile subscription. Only support when imsi or msisdn is specified.
        - msisdn: The telephone number that is assigned to a mobile subscription.  Only support when imsi or msisdn is specified.
        - apn: Access Point Name.
        - vplmn: [Visited] Public Land Mobile Network is the PLMN that the mobile subscription has visited.
        - rat_type: The radio technology used by the mobile subscription. 0 (reserved), 1 (UTRAN (3G)), 2 (GERAN (2G)), 3 (WLAN), 4 (GAN), 5 (HSPA Evolution), 6 (EUTRAN (LTE/4G), 7 (Virtual), 8-255 (spare)
      allowReserved: true
  schemas:
    UsageResponse:
      type: object
      properties:
        cycle_started_at:
          type: string
          format: date-time
          description: The start time for the time window processed to generate the report.
          example: '2019-06-27T00:00:00.000Z'
        cycle_ended_at:
          type: string
          example: '2019-06-28T00:00:00.000Z'
          format: date-time
          description: The end time for the time window processed to generate the report.
        key_type:
          type: string
          example: 'imsi'
          description: The field name of the key in items.
    DataUsageResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/UsageResponse'
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DataUsageReport'
    SmsUsageResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/UsageResponse'
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SmsUsageReport'
    UsageReport:
      type: object
      properties:
        key:
          type: string
          description: |
            The value of the key used to aggregate the reports. This is the sort field supplied in the request.
            If the request was made witout a specified sort, then it will default to imsi.
          example: '238208000000001'
    DataUsageReport:
      type: object
      allOf:
        - $ref: '#/components/schemas/UsageReport'
      properties:
        uploaded:
          type: integer
          format: int64
          example: 500000
          description: The amount of uploaded data in bytes.
        downloaded:
          type: integer
          format: int64
          example: 500000
          description: The amount of downloaded data in bytes.
    SmsCount:
      type: object
      properties:
        success_count:
          type: integer
          format: int64
          example: 10
          description: The number of successful messages.
        error_count:
          type: integer
          format: int64
          example: 1
          description: The number of erroneous messages.
    SmsUsageReport:
      type: object
      allOf:
        - $ref: '#/components/schemas/UsageReport'
      properties:
        received:
          allOf:
            - $ref: '#/components/schemas/SmsCount'
          description: The number of received messages.
        sent:
          allOf:
            - $ref: '#/components/schemas/SmsCount'
          description: The number of sent messages.
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the problem type. When dereferenced,it SHOULD provide
            human-readable documentation for the problem type (e.g., using HTML).
          default: about:blank
          example: 'http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4'
        title:
          type: string
          description: |
            A short, summary of the problem type. Written in english and readable for engineers (usually not suited
            for non technical stakeholders and not localized.
          example: 'Service Unavailable'
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 100
          maximum: 600
          example: 503
        detail:
          type: string
          description: A human readable explanation specific to this occurrence of the problem.
          example: 'Connection to database timed out.'
        instance:
          type: string
          description: An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
          example: 'https://api.documentation.url/request-id'
        parameters:
          type: object
          additionalProperties:
            type: string
    400Response:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            title:
              example: Bad Request
            status:
              example: 400
    401Response:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            title:
              example: Authentication Failure
            status:
              example: 401
    404Response:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            title:
              example: No Found
            status:
              example: 404
    500Response:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            title:
              example: Internal server error
            status:
              example: 500
    503Response:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            title:
              example: Service Unavailable
            status:
              example: 503
    529Response:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            title:
              example: Service Overloaded
            status:
              example: 529
  headers:
    X-RateLimit-Limit-Second:
      description: The maximum number of requests allowed in a second.
      schema:
        type: integer
        format: int32
    X-RateLimit-Limit-Minute:
      description: The maximum number of requests allowed in a minute.
      schema:
        type: integer
        format: int32
    X-RateLimit-Remaining-Second:
      description: The number of requests remaining in a second.
      schema:
        type: integer
        format: int32
    X-RateLimit-Remaining-Minute:
      description: The number of requests remaining in a minute.
      schema:
        type: integer
        format: int32
  securitySchemes:
    OAuth2:
      type: oauth2
      description: The resources in the API are protected using the OAuth 2.0 protocol with the password grant flow.
      flows:
        password:
          tokenUrl: /iot/api/auth/token
          scopes:
            xdr-report-api.read: Grant read access to usage reports.
            subscription-signalling-usages.read: Grant read access to subscription signalling usages API.