> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raul.ugps.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get SIM connectivity info by GPS IMEI

> Get real-time or cached connectivity information for a GPS device by its IMEI.

    This endpoint:
    1. Looks up the GPS device by IMEI
    2. Finds the associated SIM phone number
    3. Gets the Emnify endpoint_id from the ChipCatalog
    4. Fetches fresh connectivity data from Emnify API (network type, operator, last connection)
    5. Falls back to cached data from database if API call fails

    **Response Status Values:**
    - `live`: Fresh data from Emnify API
    - `cached`: Data from local database (API call failed or unavailable)
    - `no_sim`: GPS device has no associated SIM
    - `no_endpoint`: SIM found but no Emnify endpoint_id
    - `error`: Error fetching from API, returned cached data

    **Notes:**
    - Only works for Emnify SIMs (phone numbers starting with "42")
    - Data includes network type (2G/3G/LTE/5G), operator name, and last connection timestamp
    - Cached data may be stale; check the `status` field



## OpenAPI

````yaml /generated/specs/diagnostics.json get /api/v1/emnify/connectivity/{imei}
openapi: 3.0.0
info:
  title: Raul API - Diagnostico
  description: Health, consumo, conectividad, SIMs, webhooks fallidos y estados tecnicos.
  version: 2.0.0
  contact: {}
servers:
  - url: https://api.raul.ugps.io
    description: Production
security: []
tags: []
paths:
  /api/v1/emnify/connectivity/{imei}:
    get:
      tags:
        - Connectivity
      summary: Get SIM connectivity info by GPS IMEI
      description: >-
        Get real-time or cached connectivity information for a GPS device by its
        IMEI.

            This endpoint:
            1. Looks up the GPS device by IMEI
            2. Finds the associated SIM phone number
            3. Gets the Emnify endpoint_id from the ChipCatalog
            4. Fetches fresh connectivity data from Emnify API (network type, operator, last connection)
            5. Falls back to cached data from database if API call fails

            **Response Status Values:**
            - `live`: Fresh data from Emnify API
            - `cached`: Data from local database (API call failed or unavailable)
            - `no_sim`: GPS device has no associated SIM
            - `no_endpoint`: SIM found but no Emnify endpoint_id
            - `error`: Error fetching from API, returned cached data

            **Notes:**
            - Only works for Emnify SIMs (phone numbers starting with "42")
            - Data includes network type (2G/3G/LTE/5G), operator name, and last connection timestamp
            - Cached data may be stale; check the `status` field
      operationId: ConnectivityController_getConnectivityByImei
      parameters:
        - name: imei
          required: true
          in: path
          description: GPS device IMEI (15 digits)
          schema:
            example: '866425031234567'
            type: string
      responses:
        '200':
          description: Connectivity data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectivityResponseDto'
        '404':
          description: GPS device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmnifyErrorDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmnifyErrorDto'
      security:
        - bearerAuth: []
components:
  schemas:
    ConnectivityResponseDto:
      type: object
      properties:
        imei:
          type: string
          example: '866425031234567'
          description: GPS device IMEI
        phone_number:
          type: object
          example: '4201234567'
          description: SIM phone number
          nullable: true
        endpoint_id:
          type: object
          example: 123456
          description: Emnify endpoint ID
          nullable: true
        network_type:
          type: object
          example: LTE
          description: Network type (e.g., 2G, 3G, LTE, 5G)
          nullable: true
        operator:
          type: object
          example: Movistar Chile
          description: Mobile operator name
          nullable: true
        last_connection:
          type: object
          example: '2026-02-11T12:34:56.000Z'
          description: Last connection timestamp (ISO 8601)
          nullable: true
        connection_status:
          type: string
          example: ONLINE
          description: 'Device connection status from Emnify: ONLINE, OFFLINE, ATTACHED'
          nullable: true
          enum:
            - ONLINE
            - OFFLINE
            - ATTACHED
        country:
          type: object
          example: Chile
          description: Country name where the device is currently connected
          nullable: true
        pdp_context:
          description: Active PDP context (session) details. Null when device is offline.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ConnectivityPdpContextDto'
          type: object
        status:
          type: string
          example: live
          description: >-
            Data source status: live (fresh from API), cached (from DB), no_sim,
            no_endpoint, error
          enum:
            - live
            - cached
            - no_sim
            - no_endpoint
            - error
      required:
        - imei
        - phone_number
        - endpoint_id
        - network_type
        - operator
        - last_connection
        - connection_status
        - country
        - status
    EmnifyErrorDto:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: string
      required:
        - error
        - message
    ConnectivityPdpContextDto:
      type: object
      properties:
        duration:
          type: object
          example: '435:49:48'
          nullable: true
        created:
          type: object
          example: '2026-02-20 08:56:26'
          nullable: true
        ue_ip_address:
          type: object
          example: 10.56.250.213
          nullable: true
        ci:
          type: object
          example: '5974278'
          nullable: true
        breakout_ip:
          type: object
          example: 185.57.217.126
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication

````