openapi: 3.0.0
info:
  title: HLR Lookup API
  description: |
    HLR lookup is a service that minimizes message loss and unsuccessful call attempts with real-time phone number verification, providing key information on a user's phone number, such as subscriber status and roaming data.
  version: '1.0'
  contact:
    name: tyntec API Support
    url: https://www.tyntec.com/support
    email: support@tyntec.com
  x-repository: https://github.com/tyntec/api-collection/blob/master/verification
  x-specification-file: hlrLookup.yaml
  x-major-version: v1
servers:
  - url: https://api.tyntec.com/nis/v1/
tags:
  - name: "HLR Lookup"
    description: |
      tyntec's Global Number Verification (GNV) minimizes message loss and unsuccessful call attempts with real-time phone number verification, providing key information on a user's phone number, such as subscriber status and roaming data.
security:
  - APIKeyHeader: []
paths:
  /gnv:
    get:
      tags:
        - "HLR Lookup"
      summary: Number Information from HLR
      description: |
        Extended Number Information can be requested directly from the Home Location Registry (HLR) serving the specific MSISDN
      operationId: gnvRequestGET
      parameters:
        - in: query
          name: msisdn
          required: true
          schema:
            type: string
          style: form
          description: |
            The phone number of interest, given in the international format
          example: +49569858597
        - in: query
          name: callbackUrl
          schema:
            type: string
          required: false
          description: |
            The asynchronous response can be triggered by this request parameter.

            In this case, tyntec's system will POST the requested number information to your webserver at the given URL, instead of the default synchronous response given in the body of the "HTTP 200 OK" response. If your server does not answer "HTTP 200 OK" within two seconds, tyntec's system will retry to POST the number information after 1, 5, 10, 20, 30, 60 minutes for a maximum of 48 hours.
          example: https://my.callback.io/gnv-response
      responses:
        '200':
          description: A successful GNV response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GnvResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

components:
  responses:
    BadRequest:
      description: An error in MSISDN or in the callback URL
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: Authorization information is missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: Invalid account credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
    PaymentRequired:
      description: The current credit balance is not sufficient for this request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
    InternalError:
      description: Something went wrong. :-(
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: apiKey
  schemas:
    GnvResponse:
      type: object
      description: The number information response for GNV
      properties:
        requestId:
          type: string
          description: |
            The unique identifier provided for each request
          example: "12-86cfafba-8677-f42b-5050-ece6af6abf01"
        msisdn:
          type: string
          description: |
            The phone number of interest given in the international format
          example: "+491622943176"
        ported:
          type: string
          description: |
            Indicates the porting status true/false/unknown.
          example: "false"
        roaming:
          type: string
          description: |
            Indicates the roaming status true/false/unknown.
          example: "false"
        presence:
          type: string
          description: |
            The latest handset status (switched on/off) known by the operator (stored in the respective HLR)
          example: "true"
        price:
          type: number
          description: |
            The price for the query
          example: 0.001
        currency:
          type: string
          description: |
            The currency in which the pricing is given; it corresponds to the currency of the invoice.
          example: "EUR"
        priceEffective:
          type: string
          description: |
            The date when "price" became effective
          example: "2010-11-01T00:00:00+0000"
        errorCode:
          type: string
          description: |
            The reason for an unsuccessful attempt
          example: "0"
        nrhMCC:
          type: string
          description: |
            A representative MCC (Mobile Country Code) of the NRH's network (Number Range Holder)
          example: "262"
        nrhMNC:
          type: string
          description: |
            A representative MNCs (Mobile Network Codes) of the NRH's network
          example: "02"
        nrhTtId:
          type: string
          description: |
            The respective tyntec ID of the NRH
          example: "15"
        nrhOperator:
          type: string
          description: |
            A human-readable name of the NRH
          example: "Vodafone"
        nrhCountry:
          type: string
          description: |
            The three-letter code (following ISO 3166-1 alpha-3) of the country where the NRH's network is located
          example: "DEU"
        nrhTimeZone:
          type: string
          description: |
            Local time zone of the NRH's network, relative to UTC
          example: "+0100"
        nrhTechnology:
          type: string
          description: |
            The technology used by the NRH operator's network; possible values are: GSM, MVNO GSM, GSM/CDMA, Satellite, CDMA, iDen, iDen/GSM, Pager, Fixed.
          example: "GSM"
        imsiMCC:
          type: string
          description: |
            The MCC of the subscriber's IMSI (International Mobile Subscriber Identity)
          example: "262"
        imsiMNC:
          type: string
          description: |
            The MNC of the subscriber's IMSI
          example: "02"
        imsi:
          type: string
          description: |
            The subscriber's International Mobile Subscriber Identity
        imsiTtId:
          type: string
          description: |
            The respective tyntec ID of the subscription network operator
          example: "15"
        imsiOperator:
          type: string
          description: |
            A human-readable name of the subscription network operator
          example: "Vodafone"
        imsiCountry:
          type: string
          description: |
            The three-letter code of the country where the subscription network is located
          example: "DEU"
        imsiTimeZone:
          type: string
          description: |
            The local time zone of the subscription network, relative to UTC
          example: "+0100"
        imsiTechnology:
          type: string
          description: |
            The technology used by the subscription network; possible values are: GSM, MVNO GSM, GSM/CDMA, Satellite, CDMA, iDen, iDen/GSM, Pager, Fixed.
          example: "GSM"
        hlrCC:
          type: string
          description: |
            The CC (Country Code) of the responding HLR (Home Location Register)
          example: "49"
        hlrNDC:
          type: string
          description: |
            The NDC (National Dialling Code) of the responding HLR
          example: "162"
        hlrMCC:
          type: string
          description: |
            A representative MCC of the HLR's operator
          example: "262"
        hlrMNC:
          type: string
          description: |
            A representative MNC of the HLR's operator
          example: "02"
        hlr:
          type: string
          description: |
            The representative Home Location Register
        hlrTtId:
          type: string
          description: |
            The respective tyntec ID of the operator's HLR
          example: "15"
        hlrOperator:
          type: string
          description: |
            A human-readable name of the operator's HLR
          example: "Vodafone"
        hlrCountry:
          type: string
          description: |
            The three-letter code of the country where the HLR is located
          example: "DEU"
        hlrTimeZone:
          type: string
          description: |
            The local time zone of the HLR, relative to UTC; +HH:mm (according to ISO 8601)
          example: "+0100"
        hlrTechnology:
          type: string
          description: |
            The technology used by the HLR operator network; possible values are: GSM, MVNO GSM, GSM/CDMA, Satellite, CDMA, iDen, iDen/GSM, Pager, Fixed.
          example: "GSM"
        mscCC:
          type: string
          description: |
            The CC of the MSC (Mobile Switching Center)
          example: "49"
        mscNDC:
          type: string
          description: |
            The MSC of the NDC
          example: "162"
        mscMCC:
          type: string
          description: |
            A representative MCC of the operator's MSC
          example: "262"
        mscMNC:
          type: string
          description: |
            A representative MNC of the operator's MSC
          example: "02"
        msc:
          type: string
          description: |
            The representative Mobile Switching Center
        mscTtId:
          type: string
          description: |
            The respective tyntec ID of the operator's MSC
          example: "15"
        mscOperator:
          type: string
          description: |
            A human-readable name of the operator's MSC
          example: "Vodafone"
        mscCountry:
          type: string
          description: |
            The three-letter country code (following ISO 3166-1 alpha-3) of the network operating the MSC
          example: "DEU"
        mscTimeZone:
          type: string
          description: |
            The local time zone of the MSC, relative to UTC; +HH:mm (according to ISO 8601)
          example: "+0100"
        mscTechnology:
          type: string
          description: |
            The technology used by the MSC operator's network; possible values are: GSM, MVNO GSM, GSM/CDMA, Satellite, CDMA, iDen, iDen/GSM, Pager, Fixed.
          example: "GSM"
        synchronous:
          type: boolean
          description: |
            Indicates whether the response body contains the number information (synchronous) or just the requestId of the asynchronous response
          example: true
    Problem:
      type: object
      additionalProperties: true
      description: The problem object follows the RFC-7807 (https://tools.ietf.org/html/rfc7807).
      properties:
        type:
          description: A URI reference [RFC3986] that identifies the problem type
          example: https://docs.tyntec.com/problems/DataNotParseable
          type: string
        title:
          type: string
          example: The given data were not parsable.
          description: Short, human-readable summary of the problem type
        status:
          description: The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem
          type: number
          example: 400
        detail:
          description: Human-readable explanation specific to this occurrence of the problem
          type: string
          example: |
            Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]