---
openapi: 3.0.3
info:
  title: Subscription Search 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 Subscription Search API that
    provides resources to retrieve an organization's subscription detail
    information. The Subscription Search API is based on the Representational
    State Transfer (REST) interface. From this point on, the Subscription
    Search 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/shared-bundles"
    -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 Warning header (see RFC 7234 - Warning header) field will be added
    in the response. The warn-code will be 299 and the warn-text will inform
    about what is deprecated and when it will be completely removed.

    API audience should not start using a deprecated API.

    API audience is encouraged to monitor for Warning header.

  x-audience: external-public
  x-api-id: 96f61af0-7bba-45df-8f12-005042cf1e47
servers:
  - url: https://iot-api.aeris.com/iot/api/subscriptions
    description: API server
paths:
  /details:
    post:
      tags:
        - "Subscription Search API"
      summary: Subscriptions search with identifier.
      description: |
        This API request queries subscriptions with the given identifier type
      parameters:
        - name: Authorization
          in: header
          description: A valid token string in the form Bearer \<token string\>
          schema:
            type: string
          required: true
        - name: additionalFields
          in: query
          description: |
            Collection of additional subscription field groups to include
            in the response Available values : CUSTOM_FIELDS, DATES,
            ENTERPRISE, INDIVIDUAL_APN, LABEL, LOCK_STATE, SECURITY_LOCK,
            PACKAGE, SIM_SPEC, MONTHLY_DATA, MONTHLY_SMS
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AdditionalFields'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetSubscriptionDetailsByPrimaryKey'
            examples:
              identifier-query-example-imsi:
                value:
                  identifierType: IMSI
                  identifierValues:
                    - "100000123456001"
                    - "100000123456002"
      responses:
        "200":
          description: OK
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrimaryKeyQueryResponse'
              examples:
                identifier-query-response-example:
                  value:
                    subscriptions:
                      - enterprise: 88000952
                        enterpriseName: Test Enterprise 02
                        firstActivatedAt: 2021-05-19T07:38:00.78Z
                        iccid: 99987100883000170205
                        imsi: 100883000170205
                        apns:
                          - apn: 5g.optest1.com
                            ordinal: 2
                            apnId: 22
                            qosId: 34
                            type: HSS
                          - apn: b2c.optest1.11121.com
                            ordinal: 1
                            apnId: 88
                            qosId: 34
                            type: HLR
                        msisdn: 200883000155016
                        organizationId: 3.88.952
                        state: ACTIVE
                        simSpecificationId: Test 0100
                        subscriptionPackageDescription: SP Test Enterprise 02
                        subscriptionPackageName: 200200202_SP_10
                        subscriptionStateBeforeLock: ACTIVE
                        subscriptionStateLocked: false
                        subscriptionSecurityLocked: false
                        monthlyData: 8500000000
                        monthlySms: 120
        "400":
          $ref: '#/components/responses/Response_400'
        "401":
          $ref: '#/components/responses/Response_401'
        "403":
          $ref: '#/components/responses/Response_403'
        "404":
          $ref: '#/components/responses/Response_404'
        "429":
          $ref: '#/components/responses/Response_429'
        "500":
          $ref: '#/components/responses/Response_500'
        default:
          $ref: '#/components/schemas/Problem'
      security:
        - Oauth2Auth:
            - subscription-service.write
    get:
      tags:
        - "Subscription Search API"
      summary: Search with company id, label or custom fields
      description: |
        This API request allows queries with label or company id.
      parameters:
        - name: Authorization
          in: header
          description: A valid token string in the form Bearer \<token string\>
          schema:
            type: string
          required: true
        - name: q
          in: query
          description: |
            Query with either 'label', 'company' or 'customField'. For custom
            fields query syntax is like this:
            customField IN (test-field1==value 1;test-field2==value 2)
          schema:
            type: string
            example: label==TestLabel1
        - name: order
          in: query
          description: Results ordered by specified subscription
            field (default 'IMSI')
          schema:
            $ref: '#/components/schemas/Order'
        - name: additionalFields
          in: query
          description: Collection of additional subscription field groups
            to include in the response
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AdditionalFields'
        - name: limit
          in: query
          description: |
            Specifies the maximum number of results to be returned.
            Allowed interval is 1-10000.
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 100
        - name: cursor
          in: query
          schema:
            type: string
            example: 100863000010004
          description: |
            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.
      responses:
        "200":
          description: OK
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecondaryKeyQueryResponse'
              examples:
                identifier-query-response-example:
                  value:
                    subscriptions:
                      - customFields:
                          - fieldName: Test operator 02
                            fieldValue: value
                          - fieldName: Shape
                            fieldValue: value
                          - fieldName: for test
                            fieldValue: value
                        enterprise: '78000003'
                        enterpriseName: Test Enterprise 02
                        firstActivatedAt: '2016-10-04T13:38:19.360Z'
                        iccid: '99987100783000000005'
                        imsi: '100783000000005'
                        msisdn: '200783000410116'
                        organizationId: 3.78.3
                        state: ACTIVE
                        simSpecificationId: Test 0100
                        subscriptionPackageName: 200200202_SP_01
                        subscriptionPackageDescription: SP Test Enterprise
                        subscriptionStateLocked: false
                        monthlyData: 0
                        monthlySms: 0
                      - enterprise: '78000003'
                        enterpriseName: OpKis2 Enterprise 02
                        label: AFBPPP
                        firstActivatedAt: '2016-10-04T13:38:22.331Z'
                        iccid: '99987100783000000006'
                        imsi: '100783000000006'
                        msisdn: '200783000410118'
                        organizationId: 3.78.3
                        state: ACTIVE
                        simSpecificationId: Test 0100
                        subscriptionPackageName: 200200202_SP_01
                        subscriptionPackageDescription: SP Test Enterprise
                        subscriptionStateLocked: false
                        monthlyData: 33230
                        monthlySms: 10
                      - enterprise: '78000003'
                        enterpriseName: Test Enterprise 02
                        label: Test demo
                        firstActivatedAt: '2016-10-04T13:38:24.065Z'
                        iccid: '99987100783000000007'
                        imsi: '100783000000007'
                        msisdn: '200783000410122'
                        organizationId: 3.78.3
                        state: ACTIVE
                        simSpecificationId: Test 0100
                        subscriptionPackageName: 200200202_SP_01
                        subscriptionPackageDescription: SP Test Enterprise
                        subscriptionStateLocked: false
                        monthlyData: 8500000000
                        monthlySms: 10
                    next: "/details?q=COMPANY==78000003&order=IMSI&limit=3
                      &cursor=100783000000007
                      &additional_fields=CUSTOM_FIELDS
                      &additional_fields=DATES
                      &additional_fields=ENTERPRISE
                      &additional_fields=INDIVIDUAL_APN
                      &additional_fields=LABEL
                      &additional_fields=LOCK_STATE
                      &additional_fields=SECURITY_LOCK
                      &additional_fields=PACKAGE
                      &additional_fields=SIM_SPEC
                      &additional_fields=SECURITY_LOCK
                      &additional_fields=MONTHLY_DATA
                      &additional_fields=MONTHLY_SMS"
                    size: 3
        "400":
          $ref: '#/components/responses/Response_400'
        "401":
          $ref: '#/components/responses/Response_401'
        "403":
          $ref: '#/components/responses/Response_403'
        "404":
          $ref: '#/components/responses/Response_404'
        "429":
          $ref: '#/components/responses/Response_429'
        "500":
          $ref: '#/components/responses/Response_500'
        default:
          $ref: '#/components/schemas/Problem'
      security:
        - Oauth2Auth:
            - subscription-service.write
components:
  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
  schemas:
    SecondaryKey:
      enum:
        - COMPANY
        - CUSTOM_FIELD
        - LABEL
      type: string
    GetSubscriptionDetailsByPrimaryKey:
      type: object
      required:
        - identifierType
        - identifierValues
      properties:
        identifierType:
          $ref: '#/components/schemas/IdentifierType'
        identifierValues:
          $ref: '#/components/schemas/IdentifierValues'
    IdentifierValues:
      description: |
        List of identifiers of the given type
      type: array
      items:
        type: string
    IdentifierType:
      description: |
        Used to identify a list of subscription details.
        The identifier can be of the type:
        - ICC
        - IMSI
        - MSISDN
      x-extensible-enum:
        - ICC
        - IMSI
        - MSISDN
      type: string
    Order:
      enum:
        - ICC
        - IMSI
        - MSISDN
      type: string
    AdditionalFields:
      description: |
        Collection of additional subscription field groups to include
        in the response Available values : CUSTOM_FIELDS, DATES,
        ENTERPRISE, INDIVIDUAL_APN, LABEL, LOCK_STATE, SECURITY_LOCK,
        PACKAGE, SIM_SPEC, MONTHLY_DATA, MONTHLY_SMS

        When INDIVIDUAL_APN is requested, the apns list contains only APNs
        currently enabled for the subscription. APNs disabled via
        POST /subscriptions/disabledApns will not appear in this list.
        Returns an empty list if no individual APNs are assigned to the
        subscription.
      x-extensible-enum:
        - CUSTOM_FIELDS
        - DATES
        - ENTERPRISE
        - INDIVIDUAL_APN
        - LABEL
        - LOCK_STATE
        - SECURITY_LOCK
        - PACKAGE
        - SIM_SPEC
        - MONTHLY_DATA
        - MONTHLY_SMS
      type: string
    SubscriptionResponse:
      type: object
      properties:
        arpTadigCode:
          type: string
          description: |
            Name of the ARP assigned to the subscription.
        customFields:
          $ref: '#/components/schemas/CustomFieldArray'
        enterprise:
          type: string
          description: |
            Enterprise identifier.
        enterpriseName:
          type: string
          description: |
            Enterprise name. Included only with group 'enterpriseInfo’.
        region:
          type: string
          description: |
            The region the subscription is registered in
        label:
          type: string
          description: |
            Customer label. Included only with group 'label’.
        firstActivatedAt:
          $ref: '#/components/schemas/Date'
        iccid:
          type: string
          description: |
            ICCID is the identifier of the actual SIM card itself
        detectedImei:
          type: string
          description: |
            IMEI number used to identify the device detected by
            the network event.
        assignedImei:
          type: string
          description: |
            IMEI number used to identify the device assigned to the
            subscription by the user.
        imsi:
          type: string
          description: |
            International mobile subscriber identity
        installationDateAt:
          $ref: '#/components/schemas/Date'
        apns:
          description: |
            List of individually enabled APNs for the subscription. Only
            populated when INDIVIDUAL_APN is included in additionalFields.
            Only currently enabled APNs are returned; APNs disabled via
            POST /subscriptions/disabledApns are excluded. Note: the
            disabledApns operation cannot disable all APNs — at least one
            always remains enabled after that call. Returns an empty list
            if no individual APNs are assigned.
          allOf:
            - $ref: '#/components/schemas/SetIndividualApnResponse'
        ips:
          $ref: '#/components/schemas/SetIpResponse'
        lastSubscriptionPackageChangeAt:
          $ref: '#/components/schemas/Date'
        lastSubscriptionChangeDateAt:
          $ref: '#/components/schemas/Date'
        msisdn:
          type: string
          description: |
            Mobile Station International Subscriber Directory Number (phone
            number)
        nsce:
          type: string
          description: |
            external card serial number. A 13-digit serial number
            on the SIM card. It identifies the operator that put the SIM
            card into service.
        pin1:
          type: string
          description: |
            Personal identification number 1
        pin2:
          type: string
          description: |
            Personal identification number 2
        puk1:
          type: string
          description: |
            Pin unlock key1
        puk2:
          type: string
          description: |
            Pin unlock key2
        remainingCommitmentTime:
          type: string
          description: |
            Remaining commitment time
        nonHosted:
          type: boolean
          description: |
            If true is nonHosted
        oldCompanyId:
          type: string
          description: |
            Old company Id
        operatorId:
          type: string
          description: |
            The id of the operator
        organizationId:
          type: string
          description: |
            OrganizationId
        monthlyData:
          format: int64
          type: integer
          description: |
            Monthly consumed traffic data in bytes.
          example: 8500000000
        monthlySms:
          format: int64
          type: integer
          description: |
            Monthly consumed SMS count.
          example: 100
        parameterBasedRegistrationExitAt:
          $ref: '#/components/schemas/Date'
        poolId:
          type: string
          description: |
            id of the pool used for generating numbers
        poolShortName:
          type: string
          description: |
            Short Name of the pool used for generating numbers
        resellerId:
          type: string
          description: Identifier of reseller
        schemeId:
          type: string
        state:
          $ref: '#/components/schemas/SubscriptionState'
        simSpecificationId:
          type: string
          description: |
            SIM Specification ID. Included only with group 'simSpecification’
        simSpecificationType:
          type: string
          description: |
            SIM Specification type. Included only with group 'simSpecification’
        simSpecificationDescription:
          type: string
          description:
            SIM Specification description. Included only with group
            'simSpecification’.
        profileSpecificationId:
          type: string
        subscriptionPackageName:
          type: string
          description: |
            Subscription package name. Included only with group 'packageInfo’
        subscriptionPackageDescription:
          type: string
          description: |
            Subscription package description. Included only with group
            'packageInfo’.
        subscriptionStateLocked:
          type: boolean
          description: |
            Current lock state. Included only with group 'lockStateInfo’
        subscriptionStateLockingReason:
          type: string
          description: |
            Locking reason. Included only with group 'lockStateInfo’
        subscriptionStateBeforeLock:
          type: string
          description: |
            The state of the subscription before lock. Included only
            with group 'lockStateInfo’.
        subscriptionSecurityLocked:
          type: boolean
          description: |
            Current security lock state. Included only
            with group 'securityLockStateInfo’. Requires permission
        subscriptionSecurityLockingReason:
          type: string
          description: |
            The locking reason of the subscription before lock. Included only
            with group 'securityLockStateInfo’. Requires permission
        subscriptionStateBeforeSecurityLock:
          type: string
          description: |
            The state of the subscription before lock. Included only
            with group 'securitylockStateInfo’. Requires permission
        provisionedAt:
          $ref: '#/components/schemas/Date'
    CustomField:
      type: object
      properties:
        fieldName:
          type: string
        fieldValue:
          type: string
    CustomFieldArray:
      uniqueItems: true
      type: array
      items:
        $ref: '#/components/schemas/CustomField'
    Date:
      type: string
      format: date-time
    IpResponse:
      type: object
      properties:
        apnName:
          type: string
        ip:
          type: string
        ipVersion:
          $ref: '#/components/schemas/IpVersion'
        operatorId:
          type: string
        server:
          type: string
        subnet:
          type: string
    IndividualApnResponse:
      type: object
      properties:
        ordinal:
          type: integer
          format: int32
        apn:
          type: string
        apnId:
          type: integer
          format: int32
        qosId:
          type: integer
          format: int32
        type:
          type: string
        contextEntityId:
          type: integer
          format: int32
    SetIpResponse:
      uniqueItems: true
      type: array
      items:
        $ref: '#/components/schemas/IpResponse'
    SetIndividualApnResponse:
      uniqueItems: true
      type: array
      items:
        $ref: '#/components/schemas/IndividualApnResponse'
    SubscriptionState:
      x-extensible-enum:
        - ACTIVE
        - ACTIVE_NO_BILLING
        - DEACTIVATED
        - DEACTIVATED_NO_BILLING
        - OPERATOR_BLOCKED
        - PAUSE
        - TERMINATED
        - TERMINATED_PENDING
      type: string
    IpVersion:
      x-extensible-enum:
        - IPV4
        - IPV6
      type: string
    PrimaryKeyQueryResponse:
      type: object
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionResponse'
    SecondaryKeyQueryResponse:
      type: object
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionResponse'
        next:
          type: string
        size:
          format: int32
          type: integer
    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'
    Response_400:
      description: Bad Request
      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: 'IdentifierType can not be null'
                instance: '123e4567-e89b-12d3-a456-426614174000'

    Response_401:
      description: Unauthorized
      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: '123e4567-e89b-12d3-a456-426614174000'
    Response_403:
      description: Forbidden
      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: '123e4567-e89b-12d3-a456-426614174000'
    Response_404:
      description: Not Found
      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: '123e4567-e89b-12d3-a456-426614174000'
    Response_429:
      description: Too Many Requests
      allOf:
        - $ref: '#/components/responses/RateLimitedResponse'
      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: "123e4567-e89b-12d3-a456-426614174000"
    Response_500:
      description: |
        Internal Server Error, Error occurred -
        see status code and problem object
        for more
      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: '123e4567-e89b-12d3-a456-426614174000'
  securitySchemes:
    Oauth2Auth:
      flows:
        password:
          tokenUrl: https://iot-api.aeris.com/iot/api/auth/token
          scopes:
            subscription-service.read: |
              Access right needed to read from the Subscription service.
            subscription-service.write: |
              Access right needed to write to the Subscription service.
      type: oauth2
