openapi: 3.0.3
info:
  title: MCC-MNC API
  version: 1.0.0
  description: >-
    Partner API for mobile operator lookup by MCC/MNC, PLMN, country ISO, dial
    code, or operator name search.


    ## Quick Start


    1. Get your `client_id` and `client_secret` from [OmaxTelecom
    Console](https://console.omaxtelecom.com)

    2. Run **Auth → Get Access Token** to obtain a Bearer token

    3. All other endpoints use the `access_token` in the `Authorization` header


    ## Authentication (OAuth 2.0)


    This API uses the **OAuth 2.0 Client Credentials** grant type ([RFC 6749
    §4.4](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)).


    **Token endpoint:**


    ```

    POST https://api.omaxtelecom.com/auth/token

    ```


    ## Billing


    Each successful lookup, by-country, or search request is billed per
    organization `price_per_request` via Console Wallet API when price > 0.


    ## Response envelope


    Success: `{ "success": true, "data": { ... } }`


    Error: `{ "success": false, "error": { "code": "...", "message": "..." } }`
tags:
  - name: Auth
    description: OAuth 2.0 authentication using the **Client Credentials** grant
      type ([RFC 6749
      §4.4](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)). Use
      your **Client ID** and **Client Secret** from [OmaxTelecom
      Console](https://console.omaxtelecom.com) to obtain an access token.
  - name: MCC-MNC
security:
  - bearerAuth: []
paths:
  /auth/token:
    servers:
      - url: https://api.omaxtelecom.com
    post:
      tags:
        - Auth
      summary: Get Access Token
      description: |-
        ## Get Access Token

        Obtain a Bearer access token using the OAuth 2.0 **Client Credentials** grant ([RFC 6749 §4.4](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)).

        ### Setup

        1. Get your `client_id` from [OmaxTelecom Console](https://console.omaxtelecom.com)
        2. Get your `client_secret` from [OmaxTelecom Console](https://console.omaxtelecom.com)

        ### Request

        ```
        POST https://api.omaxtelecom.com/auth/token
        Content-Type: application/x-www-form-urlencoded

        grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
        ```

        ### Response (200 OK)

        ```json
        {
          "access_token": "eyJhbGciOiJSUzI1NiIs...",
          "expires_in": 300,
          "token_type": "Bearer",
          "scope": "openid"
        }
        ```

        ### Token Usage

        Include the token in the `Authorization` header:

        ```
        Authorization: Bearer {access_token}
        ```
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                grant_type:
                  type: string
                  description: OAuth 2.0 grant type (RFC 6749 §4.4)
                  example: client_credentials
                client_id:
                  type: string
                  description: Your Client ID
                  example: "{{client_id}}"
                client_secret:
                  type: string
                  description: Your Client Secret
                  example: "{{client_secret}}"
      security:
        - noauthAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/x-www-form-urlencoded
        - name: Accept
          in: header
          schema:
            type: string
          example: application/json
      responses:
        "200":
          description: Successful response
          content:
            application/json: {}
  /health:
    servers:
      - url: https://api.omaxtelecom.com/tools/mcc-mnc
        description: MCC-MNC API
    get:
      tags:
        - MCC-MNC
      summary: Service health
      security: []
      responses:
        "200":
          description: Service operational
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceHealthResponse"
              example:
                ok: true
                timestamp: 2026-08-20T16:42:00+00:00
        "503":
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceHealthResponse"
              example:
                ok: false
                timestamp: 2026-08-20T16:42:00+00:00
  /lookup:
    servers:
      - url: https://api.omaxtelecom.com/tools/mcc-mnc
        description: MCC-MNC API
    post:
      tags:
        - MCC-MNC
      summary: Lookup operator by MCC+MNC or PLMN
      responses:
        "200":
          description: Operator found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LookupSuccessResponse"
              examples:
                operatorFound:
                  summary: Operator found
                  value:
                    success: true
                    data:
                      mcc: "242"
                      mnc: "99"
                      plmn: "24299"
                      region: Europe
                      country: Norway
                      iso: NO
                      dial_code: "+47"
                      dial_codes:
                        - "+47"
                      operator: TampNet AS
                      brand: null
                      tadig: NORTM
                      bands: LTE 800, LTE 1800
        "402":
          description: INSUFFICIENT_BALANCE
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                error:
                  code: INSUFFICIENT_BALANCE
                  message: Insufficient wallet balance.
        "403":
          description: MCC_MNC_DISABLED or BILLING_NOT_CONFIGURED
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                disabled:
                  summary: MCC-MNC disabled
                  value:
                    success: false
                    error:
                      code: MCC_MNC_DISABLED
                      message: MCC-MNC API is not enabled for this organization.
                billingNotConfigured:
                  summary: Billing not configured
                  value:
                    success: false
                    error:
                      code: BILLING_NOT_CONFIGURED
                      message: Billing is not configured for this organization.
        "404":
          description: OPERATOR_NOT_FOUND
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                error:
                  code: OPERATOR_NOT_FOUND
                  message: No operator matched the request
      parameters:
        - name: mcc
          in: query
          schema:
            type: string
            default: "242"
          example: "242"
        - name: mnc
          in: query
          schema:
            type: string
            default: "99"
          example: "99"
        - name: plmn
          in: query
          schema:
            type: string
            default: "24299"
          example: "24299"
  /by-country:
    servers:
      - url: https://api.omaxtelecom.com/tools/mcc-mnc
        description: MCC-MNC API
    post:
      tags:
        - MCC-MNC
      summary: List operators by ISO country or dial code
      responses:
        "200":
          description: Operators list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ByCountrySuccessResponse"
              example:
                success: true
                data:
                  iso: NO
                  dial_code: "+47"
                  count: 2
                  operators:
                    - mcc: "242"
                      mnc: "01"
                      plmn: "24201"
                      region: Europe
                      country: Norway
                      iso: NO
                      dial_code: "+47"
                      dial_codes:
                        - "+47"
                      operator: Telenor Norge AS
                      brand: Telenor
                      tadig: NORTM
                      bands: GSM 900, UMTS 2100, LTE 800
                    - mcc: "242"
                      mnc: "02"
                      plmn: "24202"
                      region: Europe
                      country: Norway
                      iso: NO
                      dial_code: "+47"
                      dial_codes:
                        - "+47"
                      operator: Telia Norge AS
                      brand: Telia
                      tadig: NORTL
                      bands: GSM 900, UMTS 2100, LTE 800
      parameters:
        - name: iso
          in: query
          schema:
            type: string
            default: NO
          example: NO
        - name: dial_code
          in: query
          schema:
            type: string
            default: "+47"
          example: "+47"
  /search:
    servers:
      - url: https://api.omaxtelecom.com/tools/mcc-mnc
        description: MCC-MNC API
    post:
      tags:
        - MCC-MNC
      summary: Search operators by name
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchSuccessResponse"
              examples:
                resultsFound:
                  summary: Matching operators found
                  value:
                    success: true
                    data:
                      query: Telenor
                      iso: NO
                      limit: 10
                      count: 1
                      operators:
                        - mcc: "242"
                          mnc: "01"
                          plmn: "24201"
                          region: Europe
                          country: Norway
                          iso: NO
                          dial_code: "+47"
                          dial_codes:
                            - "+47"
                          operator: Telenor Norge AS
                          brand: Telenor
                          tadig: NORTM
                          bands: GSM 900, UMTS 2100, LTE 800
                noResults:
                  summary: No matching operators
                  value:
                    success: true
                    data:
                      query: NonexistentCarrier
                      iso: NO
                      limit: 10
                      count: 0
                      operators: []
      parameters:
        - name: query
          in: query
          schema:
            type: string
            minLength: 2
            default: Telenor
          required: true
          example: Telenor
        - name: iso
          in: query
          schema:
            type: string
            default: NO
          example: NO
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          example: 10
  /bulk/lookup:
    servers:
      - url: https://api.omaxtelecom.com/tools/mcc-mnc
        description: MCC-MNC API
    post:
      tags:
        - MCC-MNC
      summary: Bulk operator lookup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
              properties:
                items:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    properties:
                      mcc:
                        type: string
                      mnc:
                        type: string
                      plmn:
                        type: string
            example:
              items:
                - mcc: "242"
                  mnc: "01"
                - plmn: "24299"
      responses:
        "202":
          description: Job accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkAcceptedResponse"
              example:
                success: true
                data:
                  job_id: 9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c
  /bulk/lookup/{job}:
    servers:
      - url: https://api.omaxtelecom.com/tools/mcc-mnc
        description: MCC-MNC API
    get:
      tags:
        - MCC-MNC
      summary: Poll bulk lookup job
      parameters:
        - name: job
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c
      responses:
        "200":
          description: Job status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkJobResponse"
              examples:
                processing:
                  summary: Job in progress
                  value:
                    success: true
                    data:
                      job_id: 9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c
                      status: processing
                      total_count: 2
                      processed_count: 1
                      failed_count: 0
                      items:
                        - plmn: "24201"
                          status: completed
                          result:
                            mcc: "242"
                            mnc: "01"
                            plmn: "24201"
                            region: Europe
                            country: Norway
                            iso: NO
                            dial_code: "+47"
                            dial_codes:
                              - "+47"
                            operator: Telenor Norge AS
                            brand: Telenor
                            tadig: NORTM
                            bands: GSM 900, UMTS 2100, LTE 800
                          error: null
                        - plmn: "24299"
                          status: pending
                          result: null
                          error: null
                completed:
                  summary: Job completed with failures
                  value:
                    success: true
                    data:
                      job_id: 9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c
                      status: completed
                      total_count: 2
                      processed_count: 2
                      failed_count: 1
                      items:
                        - plmn: "24201"
                          status: completed
                          result:
                            mcc: "242"
                            mnc: "01"
                            plmn: "24201"
                            region: Europe
                            country: Norway
                            iso: NO
                            dial_code: "+47"
                            dial_codes:
                              - "+47"
                            operator: Telenor Norge AS
                            brand: Telenor
                            tadig: NORTM
                            bands: GSM 900, UMTS 2100, LTE 800
                          error: null
                        - plmn: "99999"
                          status: failed
                          result: null
                          error: No operator matched the request
        "404":
          description: Job not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: Bulk lookup job not found.
components:
  securitySchemes:
    noauthAuth:
      type: http
      scheme: noauth
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Operator:
      type: object
      properties:
        mcc:
          type: string
        mnc:
          type: string
        plmn:
          type: string
        region:
          type: string
        country:
          type: string
        iso:
          type: string
        dial_code:
          type: string
        dial_codes:
          type: array
          items:
            type: string
        operator:
          type: string
        brand:
          type: string
          nullable: true
        tadig:
          type: string
          nullable: true
        bands:
          type: string
          nullable: true
    ServiceHealthResponse:
      type: object
      required:
        - ok
        - timestamp
      properties:
        ok:
          type: boolean
        timestamp:
          type: string
          format: date-time
    ApiError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          $ref: "#/components/schemas/ApiError"
    LookupSuccessResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          $ref: "#/components/schemas/Operator"
    ByCountrySuccessResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: object
          properties:
            iso:
              type: string
            dial_code:
              type: string
            count:
              type: integer
            operators:
              type: array
              items:
                $ref: "#/components/schemas/Operator"
    SearchSuccessResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: object
          properties:
            query:
              type: string
            iso:
              type: string
            limit:
              type: integer
            count:
              type: integer
            operators:
              type: array
              items:
                $ref: "#/components/schemas/Operator"
    BulkAcceptedResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: object
          required:
            - job_id
          properties:
            job_id:
              type: string
              format: uuid
    BulkJobItem:
      type: object
      properties:
        mcc:
          type: string
        mnc:
          type: string
        plmn:
          type: string
        status:
          type: string
          enum:
            - pending
            - completed
            - failed
        result:
          allOf:
            - $ref: "#/components/schemas/Operator"
          nullable: true
        error:
          type: string
          nullable: true
    BulkJobResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: object
          required:
            - job_id
            - status
            - total_count
            - processed_count
            - failed_count
            - items
          properties:
            job_id:
              type: string
              format: uuid
            status:
              type: string
              enum:
                - pending
                - processing
                - completed
                - failed
            total_count:
              type: integer
            processed_count:
              type: integer
            failed_count:
              type: integer
            items:
              type: array
              items:
                $ref: "#/components/schemas/BulkJobItem"