Aeris Subscription Search API

openapi: 3.2.0
info:
  title: Subscription Search API
  version: 1.0.5
  description: '#### Copyright

    © Aeris Communications, Inc.'
  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
tags:
- name: Subscription Search API
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-19 07:38:00.780000+00:00
                      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
      operationId: postDetails
      x-operation-id-source: derived
    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
      operationId: getDetails
      x-operation-id-source: derived
components:
  schemas:
    SubscriptionState:
      x-extensible-enum:
      - ACTIVE
      - ACTIVE_NO_BILLING
      - DEACTIVATED
      - DEACTIVATED_NO_BILLING
      - OPERATOR_BLOCKED
      - PAUSE
      - TERMINATED
      - TERMINATED_PENDING
      type: string
    CustomFieldArray:
      uniqueItems: true
      type: array
      items:
        $ref: '#/components/schemas/CustomField'
    PrimaryKeyQueryResponse:
      type: object
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionResponse'
    SetIpResponse:
      uniqueItems: true
      type: array
      items:
        $ref: '#/components/schemas/IpResponse'
    Order:
      enum:
      - ICC
      - IMSI
      - MSISDN
      type: string
    CustomField:
      type: object
      properties:
        fieldName:
          type: string
        fieldValue:
          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
    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'
    IdentifierValues:
      description: 'List of identifiers of the given type

        '
      type: array
      items:
        type: string
    IpVersion:
      x-extensible-enum:
      - IPV4
      - IPV6
      type: string
    IpResponse:
      type: object
      properties:
        apnName:
          type: string
        ip:
          type: string
        ipVersion:
          $ref: '#/components/schemas/IpVersion'
        operatorId:
          type: string
        server:
          type: string
        subnet:
          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
    SetIndividualApnResponse:
      uniqueItems: true
      type: array
      items:
        $ref: '#/components/schemas/IndividualApnResponse'
    GetSubscriptionDetailsByPrimaryKey:
      type: object
      required:
      - identifierType
      - identifierValues
      properties:
        identifierType:
          $ref: '#/components/schemas/IdentifierType'
        identifierValues:
          $ref: '#/components/schemas/IdentifierValues'
    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
          example: 503
          exclusiveMaximum: 600
        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.

            '
    Date:
      type: string
      format: date-time
  responses:
    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_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
    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_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
    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_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_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
  headers:
    X-RateLimit-Remaining-Minute:
      description: The number of requests remaining 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
    Content-Type:
      description: Handle Content-Type
      schema:
        type: string
    X-RateLimit-Limit-Minute:
      description: The maximum number of requests allowed in a minute.
      schema:
        type: integer
        format: int32
    X-RateLimit-Limit-Second:
      description: The maximum number of requests allowed in a second.
      schema:
        type: integer
        format: int32
  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