---
openapi: 3.0.3
info:
  title: Subscription Location API
  version: 1.0.2
  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 Location API that returns Cell Global Identity (CGI) of a subscription.
    The Subscription Location API is based on the Representational State Transfer (REST) interface.
    From this point on, the Subscription Location  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-availability: limited
  x-availability-scope: "Swisscom only — requires HLR/VLR signalling support at network level"
  x-api-id: 01db42b6-605c-4db5-937b-1b5e4f385012
  x-audience: external-partner   # retained — Swisscom IS an external partner
servers:
  - url: https://iot-api.aeris.com/iot/api/subscriptions
    description: API server
security:
  - Oauth2_auth: []
paths:
  /locations/cell-global-identities:
    get:
      tags:
        - Cell Global Identities
      summary: Get cell global identity information of a subscription.
      description: |
        > **Limited Availability — Not globally accessible.**
        > This endpoint requires network-level HLR/VLR signalling support and is
        > currently only available for Swisscom. It is not configurable for other operators.
        > Contact your Aeris account team before attempting to use this endpoint.

        Returns cell global identity information of a subscription.
      operationId: get-cell-global-identity-of-subscription
      security:
        - Oauth2_auth:
            - "sulo.cell-global-identities.read"
      parameters:
        - name: Authorization
          in: header
          description: "Token 3 (JWT) as: Bearer <token>"
          schema:
            type: string
          required: true
        - name: subscriptionIdType
          in: query
          description: Subscription ID type
          required: true
          schema:
            $ref: '#/components/schemas/SubscriptionIdTypeEnum'
        - name: subscriptionId
          in: query
          description: Subscription ID
          required: true
          schema:
            type: string
        - name: networkGen
          in: query
          description: Mobile network generation(3G/4G)
          required: false
          schema:
            type: string
            default: 4G
            description: Network generation
            enum:
              - 3G
              - 4G
      responses:
        "200":
          description: OK
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CellGlobalIdentity'
              examples:
                cgi-example:
                  value:
                    subscriptionIdType: "IMSI"
                    subscriptionId: "901210000000075"
                    mcc: "241"
                    mnc: "09"
                    lac: "422"
                    cellId: "17531"
                    radioType: "WCDMA"
                    updatedAt: "2022-02-11T11:27:27+01:00"
        "400":
          description: Bad Request
          headers:
            Content-Type:
              schema:
                type: string
              description: Handle Content-Type
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                undefined-subscription-id-type:
                  value:
                    type: https://www.iana.org/assignments/http-status-codes/
                    title: "Bad Request"
                    status: 400
                    detail: "Subscription id type must be one of [IMSI, MSISDN, ICC]"
                    instance: 423e4567-e89b-12d3-a456-426614175000
                undefined-network-generation:
                  value:
                    type: https://www.iana.org/assignments/http-status-codes/
                    title: "Bad Request"
                    status: 400
                    detail: "Undefined networkGen value: foo. Allowed values: [3G, 4G]"
                    instance: 423e4567-e89b-12d3-a456-426614175000
        "429":
          description: "Too Many Requests"
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                problem-response-example:
                  value:
                    type: about:blank
                    title: Too Many Requests
                    status: 429
                    detail: Too Many Requests
                    instance: null
        "500":
          description: Internal Server Error
          headers:
            Content-Type:
              schema:
                type: string
              description: Handle Content-Type
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                bad-request-example:
                  value:
                    type: https://www.iana.org/assignments/http-status-codes/
                    title: "Internal Server Error"
                    status: 500
                    detail: "Internal Server Error occurred while processing the request."
                    instance: 523e4567-e89b-12d3-a456-426614175000
        default:
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  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'
  securitySchemes:
    Oauth2_auth:
      flows:
        password:
          tokenUrl: |
            /iot/api/auth/token
          scopes:
            sulo.cell-global-identities.read: Access cell global identity
      type: oauth2
  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:
    CellGlobalIdentity:
      type: object
      properties:
        subscriptionIdType:
          $ref: '#/components/schemas/SubscriptionIdTypeEnum'
        subscriptionId:
          type: string
        mcc:
          type: string
        mnc:
          type: string
        lac:
          type: string
        cellId:
          type: string
        radioType:
          $ref: '#/components/schemas/RadioTypeEnum'
        updatedAt:
          type: string
          format: date-time
      description: Cell Global Identities
    SubscriptionIdTypeEnum:
      type: string
      description: Subscription ID type
      enum:
        - IMSI
        - MSISDN
        - ICC
    RadioTypeEnum:
      type: string
      description: Radio types
      enum:
        - GSM
        - WCDMA
        - LTE
    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).
        title:
          type: string
          description: |
            A short summary of the problem type in english and readable for
            engineers.
          example: 'Bad request'
        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: 400
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          example: 'Unknown subscription-id-type'
        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.
