---
openapi: 3.0.3
info:
  title: Number Management API
  version: 1.0.5
  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 document describes the IoT Accelerator Number management API that
      provides resources to retrieve number management inventory and details.
      The Number management API is based on the Representational State Transfer
      (REST) interface.
      From this point on, the Number management API is referred to as API in this
      document.

      ## 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 "http://<baseURL>/iot/api/nm"
      -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.

      ### Permission

      API endpoints permissions are authorized by authorization server based
      on the account roles. Required permissions for this API are documented
      in 'securitySchemes' section. You can view available permissions for
      your account through permission library in Service Portal by navigating
      Administration > Users & roles > Permission library or
      Role administration > Actions > View permission library. Make sure
      permission is available to your account before you start utilizing this
      API.

      Below shows the permissions related to the endpoints in this API:

        API: View Subscriptions


      ## 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-api-id: f9fccdac-8c1f-43bc-90a7-99edee52fe2f
  x-audience: external-public
servers:
  - url: https://iot-api.aeris.com/iot/api/subscriptions
    description: API server
tags:
  - name: NumberScheme
    description: 'Number scheme API'
  - name: ImsiRange
    description: 'IMSI Range API'
  - name: MsisdnPool
    description: 'MSISDN Pool API'
  - name: MsisdnRange
    description: 'MSISDN Range API'
paths:
  /number-schemes:
    get:
      tags:
        - NumberScheme
      operationId: listNumberSchemes
      summary: List Number schemes
      description: Provides list of number schemes mapped to
        specific organization ID.
      parameters:
        - $ref: '#/components/parameters/Header-Authorization'
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
            example: "22311000"
          description: |
            The number schemes mapped to the specific organization ID
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/cursorParam'
      responses:
        '200':
          $ref: '#/components/responses/NumberSchemesResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/default'
      security:
        - OAuth2:
            - 'cnx_subscription_view'
  /number-schemes/{schemeId}:
    get:
      tags:
        - NumberScheme
      operationId: getNumberSchemeInfo
      summary: Number scheme detail
      description: Provides details of numberscheme mapped to specific scheme
      parameters:
        - $ref: '#/components/parameters/Header-Authorization'
        - in: path
          name: schemeId
          required: true
          schema:
            type: string
            example: "TESTOPPREFSCHEME00021"
          description: |
            The number scheme mapped to the specific scheme ID
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
            example: "22311000"
          description: |
            The number schemes mapped to the specific organization ID

      responses:
        '200':
          $ref: '#/components/responses/NumberSchemeResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/default'
      security:
        - OAuth2:
            - 'cnx_subscription_view'
  /imsi-ranges:
    get:
      tags:
        - ImsiRange
      operationId: listImsiRanges
      summary: List Imsi ranges
      description: Provides list of imsi ranges mapped to a
        specific organization.
      parameters:
        - $ref: '#/components/parameters/Header-Authorization'
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
            example: "22311000"
          description: |
            The imsi ranges mapped to the specific organization ID
        - in: query
          name: schemeId
          required: true
          schema:
            type: string
            example: "TESTOPPREFSCHEME00021"
          description: |
            The imsi ranges mapped to the specific scheme ID
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/cursorParam'
      responses:
        '200':
          $ref: '#/components/responses/ImsiRangesResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/default'
      security:
        - OAuth2:
            - 'cnx_subscription_view'
  /imsi-ranges/{imsiRangeNo}:
    get:
      tags:
        - ImsiRange
      operationId: getImsiInfo
      summary: Imsi range details
      description: Provides imsi range mapped to a imsi range number.
      parameters:
        - $ref: '#/components/parameters/Header-Authorization'
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
            example: "22311000"
          description: |
            The imsi ranges mapped to the specific organization ID
        - in: query
          name: schemeId
          required: true
          schema:
            type: string
            example: "TESTOPPREFSCHEME00021"
          description: |
            The imsi ranges mapped to the specific scheme ID
        - in: path
          name: imsiRangeNo
          required: true
          schema:
            type: integer
            format: int64
            example: 22311000
          description: |
            The imsi range mapped to the imsi range number
      responses:
        '200':
          $ref: '#/components/responses/ImsiRangeResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/default'
      security:
        - OAuth2:
            - 'cnx_subscription_view'
  /msisdn-pools:
    get:
      tags:
        - MsisdnPool
      operationId: listMsisdnPools
      summary: List MSISDN pools
      description: Provides list of msisdn pools mapped to a
        specific organization.
      parameters:
        - $ref: '#/components/parameters/Header-Authorization'
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
            example: 22311000
          description: |
            The msisdn pools mapped to the specific organization ID
        - in: query
          name: schemeId
          required: true
          schema:
            type: string
            example: "TESTOPPREFSCHEME00021"
          description: |
            The msisdn pools mapped to the specific scheme ID
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/cursorParam'
      responses:
        '200':
          $ref: '#/components/responses/MsisdnPoolsResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/default'
      security:
        - OAuth2:
            - 'cnx_subscription_view'
  /msisdn-pools/{poolId}:
    get:
      tags:
        - MsisdnPool
      operationId: getMsisdnPool
      summary: MSISDN pool details
      description: Provides list of msisdn pools mapped to a
        specific organization.
      parameters:
        - $ref: '#/components/parameters/Header-Authorization'
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
            example: 22311000
          description: |
            The msisdn pools mapped to the specific organization ID
        - in: query
          name: schemeId
          required: true
          schema:
            type: string
            example: "TESTOPPREFSCHEME00021"
          description: |
            The msisdn pools mapped to the specific scheme ID
        - in: path
          name: poolId
          required: true
          schema:
            type: string
            example: "TESTOPPREFSCHEME00021"
          description: |
            The msisdn pools mapped to the specific scheme ID
      responses:
        '200':
          $ref: '#/components/responses/MsisdnPoolResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/default'
      security:
        - OAuth2:
            - 'cnx_subscription_view'
  /msisdn-ranges:
    get:
      tags:
        - MsisdnRange
      operationId: listMsisdnRanges
      summary: List MSISDN ranges
      description: Provides list of msisdn ranges mapped to a
        specific organization.
      parameters:
        - $ref: '#/components/parameters/Header-Authorization'
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
            example: 22311000
          description: |
            The msisdn ranges mapped to the specific organization ID
        - in: query
          name: poolId
          required: true
          schema:
            type: string
            example: "TESTOPPREFSCHEME00021"
          description: |
            The msisdn ranges mapped to the specific pool ID
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/cursorParam'
      responses:
        '200':
          $ref: '#/components/responses/MsisdnRangesResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/default'
      security:
        - OAuth2:
            - 'cnx_subscription_view'
  /msisdn-ranges/{msisdnRangeno}:
    get:
      tags:
        - MsisdnRange
      operationId: getMsisdnRangeInfo
      summary: MSISDN range details
      description: Provides list of msisdn ranges mapped to a range number.
      parameters:
        - $ref: '#/components/parameters/Header-Authorization'
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
            example: 22311000
          description: |
            The msisdn ranges mapped to the specific organization ID
        - in: query
          name: poolId
          required: true
          schema:
            type: string
            example: "TESTOPPREFSCHEME00021"
          description: |
            The msisdn ranges mapped to the specific pool ID
        - in: path
          name: msisdnRangeno
          required: true
          schema:
            type: integer
            format: int64
            example: 191010
          description: |
            The msisdn range mapped to the specific msisdn range number.
      responses:
        '200':
          $ref: '#/components/responses/MsisdnRangeResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/default'
      security:
        - OAuth2:
            - 'cnx_subscription_view'
components:
  schemas:
    numberSchemes:
      type: object
      properties:
        numberSchemes:
          type: array
          items:
            $ref: '#/components/schemas/numberScheme'
        next:
          type: string
    numberScheme:
      type: object
      description: |
        Number Scheme information.
      properties:
        schemeId:
          type: string
          description: ID of Scheme.
          example: 'TESTOPPREFSCHEME00021'
        hlrRID:
          type: integer
          format: int32
          description: Specific Id of the HLR.
          example: 0
        schemeName:
          type: string
          description: The name of the number scheme.
          example: 'NS022311'
        regionEnabled:
          type: boolean
          description: Check for region enabled.
          example: false
        hosted:
          type: boolean
          description: True for sims on DCP platform
          example: true
        rangeDuplication:
          type: boolean
          description: Check for range duplicates.
          example: false
    imsiRanges:
      type: object
      properties:
        imsiStores:
          type: array
          items:
            $ref: '#/components/schemas/imsiStore'
        next:
          type: string
    imsiStore:
      type: object
      description: |
        Imsi Store information.
      properties:
        rangeName:
          type: string
          description: Name of the Imsi Range
          example: "IMSI_LPWA_4405250720033083"
        rangeDesc:
          type: string
          description: Description of the Imsi Range.
          example: "IMSI_LPWA_44052507"
        date:
          type: string
          description: Date
          example: "2018-05-29T09:56:56Z"
        imsiRangeNo:
          type: integer
          format: int64
          description: Number for Imsi Range.
          example: 3083
        dcpImsiId:
          type: string
          description: Imsi Id for DCP
          example: "KDCIMSI020033083"
        rangeDetails:
          $ref: '#/components/schemas/rangeDetails'

    msisdnRanges:
      type: object
      properties:
        msisdnStores:
          type: array
          items:
            $ref: '#/components/schemas/msisdnStore'
        next:
          type: string

    msisdnStore:
      type: object
      properties:
        status:
          type: string
          description: Status of the Msisdn Range.
          example: "ACTIVE"
        msisdnRangeno:
          type: integer
          format: int64
          description: Number for MSISDN Range.
          example: 3083
        orderId:
          type: string
          description: Order Id of the Msisdn Range.
          example: "INT300000011300"
        rangeDetails:
          $ref: '#/components/schemas/rangeDetails'

    msisdnPools:
      type: object
      properties:
        pools:
          type: array
          items:
            $ref: '#/components/schemas/msisdnPoolDetail'
        next:
          type: string

    msisdnPoolDetail:
      type: object
      description: |
        MSISDN pool information.
      properties:
        poolId:
          type: string
          description: Id of Msisdn Pool.
          example: "TESTOPPREFMSISDNP00002"
        status:
          type: string
          description: Status of Msisdn Pool.
          example: "Active"
        poolData:
          $ref: '#/components/schemas/poolData'

    poolData:
      type: object
      description: |
        Pool data.
      properties:
        shortName:
          type: string
          description: The name of MSISDN pool used in the number scheme.
          example: "pool22312"
        poolDesc:
          type: string
          description: Description of Msisdn Pool.
          example: "Test pool"
        quarantinePeriod:
          type: integer
          format: int32
          description: Number of days the MSISDNs are locked before being made
            available for reallocation
          example: 60
        numberLength:
          type: integer
          format: int32
          description: Length of number.
          example: 15

    rangeDetails:
      type: object
      description: |
        Range information.
      properties:
        nextNumber:
          type: string
          description: Next number in the range.
          example: "440525070026589"
        freeAmount:
          type: integer
          format: int64
          description: The free amount in the number range
          example: 0
        reservedFor:
          type: string
          description: Status of the Range.
          example: "NOTRESERVED"
        numberRange:
          $ref: '#/components/schemas/numberRange'

    numberRange:
      type: object
      description: |
        Number Range information.
      properties:
        startNumber:
          type: string
          description: The IMSI/MSISDN with which the range starts.
          example: "440525070026500"
        endNumber:
          type: string
          description: The IMSI/MSISDN with which the range ends.
          example: "440525070026799"
        amount:
          type: integer
          format: int64
          description: Difference between start and end number.
          example: 100

    Problem:
      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: https://your.api.documentation.url
        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
          exclusiveMaximum: true
          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.

  responses:
    RateLimitedResponse:
      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-Type:
          $ref: '#/components/headers/Content-Type'
    NumberSchemesResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/numberSchemes'
          examples:
            number-schemes:
              value:
                numberSchemes:
                  - schemeId: "TESTOPPREFSCHEME00021"
                    hlrRID: 0
                    schemeName: "NS022311"
                    regionEnabled: false
                    hosted: true
                    rangeDuplication: true
                next: "/number-schemes?organizationId=05000001\
                      &limit=10&cursor=ODk0NTA0MjExNzEyMDYwMjIyMjI="
      description: OK
      allOf:
        - $ref: '#/components/responses/RateLimitedResponse'
    NumberSchemeResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/numberScheme'
          example:
            schemeId: "TESTOPPREFSCHEME00021"
            hlrRID: 0
            schemeName: "NS022311"
            regionEnabled: false
            hosted: true
            rangeDuplication: true
      description: OK
      allOf:
        - $ref: '#/components/responses/RateLimitedResponse'

    ImsiRangesResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/imsiRanges'
          examples:
            imsiRanges:
              value:
                imsiStore:
                  - startNumber: "440525070026500"
                    endNumber: "440525070026799"
                    amount: 100
                    nextNumber: "686187022311006"
                    freeAmount: 0
                    reservedFor: "NOTRESERVED"
                    rangeName: "IMSI_LPWA_4405250720033083"
                    rangeDesc: "IMSI_LPWA_44052507"
                    date: "2018-05-29T09:56:56Z"
                    imsiRangeNo: 3083
                    dcpImsiId: "KDCIMSI020033083"
                next: "/imsi-ranges?organizationId=0500001&schemeId=ZZRSCHEME01
                      &limit=10&cursor=ODk0NTA0MjExNzEyMDYwMjIyMjI="
      description: OK
      allOf:
        - $ref: '#/components/responses/RateLimitedResponse'

    ImsiRangeResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/imsiStore'
          example:
            startNumber: "440525070026500"
            endNumber: "440525070026799"
            amount: 100
            nextNumber: "686187022311006"
            freeAmount: 0
            reservedFor: "NOTRESERVED"
            rangeName: "IMSI_LPWA_4405250720033083"
            rangeDesc: "IMSI_LPWA_44052507"
            date: "2018-05-29T09:56:56Z"
            imsiRangeNo: 3083
            dcpImsiId: "KDCIMSI020033083"
      description: OK
      allOf:
        - $ref: '#/components/responses/RateLimitedResponse'

    MsisdnPoolsResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/msisdnPools'
          examples:
            msisdnPoolDetail:
              value:
                pools:
                  - shortName: "pool22312"
                    poolDesc: "Test pool"
                    quarantinePeriod: 60
                    numberLength: 15
                    poolId: "TESTOPPREFMSISDNP00002"
                    status: "ACTIVE"
                next: "/msisdn-pools?organizationId=050001&schemeId=ZZRSCHEME01
                      &limit=10&cursor=ODk0NTA0MjExNzEyMDYwMjIyMjI="
      description: OK
      allOf:
        - $ref: '#/components/responses/RateLimitedResponse'

    MsisdnPoolResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/msisdnPoolDetail'
          example:
            shortName: "pool22312"
            poolDesc: "Test pool"
            quarantinePeriod: 60
            numberLength: 15
            poolId: "TESTOPPREFMSISDNP00002"
            status: "ACTIVE"
      description: OK
      allOf:
        - $ref: '#/components/responses/RateLimitedResponse'

    MsisdnRangesResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/msisdnRanges'
          examples:
            msisdnRanges:
              value:
                msisdnRanges:
                  - startNumber: "686187022311000"
                    endNumber: "686187022311099"
                    amount: 100
                    nextNumber: "686187022311006"
                    freeAmount: 94
                    reservedFor: "NOTRESERVED"
                    status: "ACTIVE"
                    msisdnRangeno: 191010
                    orderId: "INT300000011300"
                next: "/msisdn-ranges?organizationId=0500001&poolId=DLGMSIS141
                      &limit=10&cursor=ODk0NTA0MjExNzEyMDYwMjIyMjI="
      description: OK
      allOf:
        - $ref: '#/components/responses/RateLimitedResponse'

    MsisdnRangeResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/msisdnStore'
          example:
            startNumber: "686187022311000"
            endNumber: "686187022311099"
            amount: 100
            nextNumber: "686187022311006"
            freeAmount: 94
            reservedFor: "NOTRESERVED"
            status: "ACTIVE"
            msisdnRangeno: 191010
            orderId: "INT300000011300"
      description: OK
      allOf:
        - $ref: '#/components/responses/RateLimitedResponse'


    '400':
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            response:
              value:
                type: 'https://www.iana.org/assignments/http-status-codes/'
                title: 'Bad Request'
                status: 400
                detail: 'organizationId can not be null'
                instance: "https://exmaple.api.documentation.url/123e4567-\
                    e89b-12d3-a456-426614174000"
      description: Bad Request
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
    '401':
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            response:
              value:
                type: 'https://www.iana.org/assignments/http-status-codes/'
                title: 'Unauthorized'
                status: 401
                detail: "Token expired"
                instance: "https://exmaple.api.documentation.url/123e4567-\
                    e89b-12d3-a456-426614174000"
      description: Unauthorized
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
    '403':
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            response:
              value:
                type: 'https://www.iana.org/assignments/http-status-codes/'
                title: 'Forbidden'
                status: 403
                detail: "You do not have access to the resource"
                instance: "https://exmaple.api.documentation.url/123e4567-\
                    e89b-12d3-a456-426614174000"
      description: Forbidden
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
    '405':
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Method Not Allowed
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
    '404':
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            response:
              value:
                type: 'https://www.iana.org/assignments/http-status-codes/'
                title: 'Not Found'
                status: 404
                detail: "Not Found"
                instance: "https://exmaple.api.documentation.url/123e4567-\
                    e89b-12d3-a456-426614174000"
      description: Not Found
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
    '429':
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            response:
              value:
                type: 'https://www.iana.org/assignments/http-status-codes/'
                title: 'Too Many Requests'
                status: 429
                detail: "API rate limit exceeded"
                instance: "https://exmaple.api.documentation.url/123e4567-\
                    e89b-12d3-a456-426614174000"
      description: Too Many Requests
      allOf:
        - $ref: '#/components/responses/RateLimitedResponse'
    '500':
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            response:
              value:
                type: 'https://www.iana.org/assignments/http-status-codes/'
                title: 'Internal Server Error'
                status: 500
                detail: 'Internal Server Error'
                instance: "https://exmaple.api.documentation.url/123e4567-\
                    e89b-12d3-a456-426614174000"
      description: Internal Server Error
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
    default:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            response:
              value:
                type: 'https://www.iana.org/assignments/http-status-codes/'
                title: 'Internal Server Error'
                status: 500
                detail: 'Internal Server Error'
                instance: "https://exmaple.api.documentation.url/123e4567-\
                                e89b-12d3-a456-426614174000"
      description: Internal Server Error

  headers:
    Content-Type:
      description: Handle Content-Type
      schema:
        type: string
    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

  parameters:
    Header-Authorization:
      name: Authorization
      in: header
      required: true
      description: A valid token string in the form Bearer <token string>
      schema:
        type: string
    limitParam:
      in: query
      name: limit
      schema:
        type: integer
        default: 100
      description: |
        Specifies the maximum number of results to be returned.
        Allowed interval is 1-10000.
    cursorParam:
      in: query
      name: cursor
      schema:
        type: string
      example: 'DFVSDB3434%DFB%EYY445'
      description: |
        Encoded string parameter used for pagination. This field is
        automatically populated in the response field "next" if there
        are more results in the system than delivered in the response.
  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: https://iot-api.aeris.com/iot/api/auth/token
          scopes:
            cnx_subscription_view: Grant user read access to Number management
              inventory resource
