openapi: 3.0.3
info:
  title: Telefónica Status Device Roaming Location Verification API
  description: The Device Roaming Status API verifies the roaming status of a SIM-based device using carrier network data, without relying on GPS or risking identity information exposure. Enables fraud detection, content geo-restriction, and compliance workflows. Based on CAMARA open standards. Available in Spain and Brazil.
  version: 0.5.0
  contact:
    url: https://opengateway.telefonica.com/en/apis/device-roaming-status
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://opengateway.telefonica.com/v1
  description: Telefónica Open Gateway - Production
- url: https://sandbox.opengateway.telefonica.com/v1
  description: Telefónica Open Gateway - Sandbox
tags:
- name: Location Verification
paths:
  /location-verification/verify:
    post:
      operationId: verifyDeviceLocation
      summary: Verify Device Location
      description: Verifies whether a device is within the specified geographic area. The area can be defined as a circle or polygon. Returns a match result with confidence level.
      tags:
      - Location Verification
      security:
      - openIdConnect:
        - location-verification:verify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationVerificationRequest'
      responses:
        '200':
          description: Location verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationVerificationResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '422':
          description: Unable to determine device location.
components:
  schemas:
    Area:
      type: object
      description: Geographic area to verify device presence within.
      properties:
        areaType:
          type: string
          enum:
          - CIRCLE
          - POLYGON
        center:
          type: object
          description: Center point for circular areas.
          properties:
            latitude:
              type: number
              format: double
              minimum: -90
              maximum: 90
            longitude:
              type: number
              format: double
              minimum: -180
              maximum: 180
        radius:
          type: number
          format: double
          description: Radius in meters for circular areas.
          minimum: 2000
        polygon:
          type: array
          description: Polygon vertices for polygon area type.
          items:
            type: object
            properties:
              latitude:
                type: number
                format: double
              longitude:
                type: number
                format: double
    Device:
      type: object
      description: Device to verify location for.
      properties:
        phoneNumber:
          type: string
          pattern: ^\+[1-9][0-9]{4,14}$
        networkAccessIdentifier:
          type: string
        ipv4Address:
          type: object
          properties:
            publicAddress:
              type: string
            publicPort:
              type: integer
        ipv6Address:
          type: string
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
        code:
          type: string
        message:
          type: string
    LocationVerificationRequest:
      type: object
      required:
      - device
      - area
      properties:
        device:
          $ref: '#/components/schemas/Device'
        area:
          $ref: '#/components/schemas/Area'
        maxAge:
          type: integer
          description: Maximum age of location data in seconds.
          minimum: 60
    LocationVerificationResponse:
      type: object
      properties:
        verificationResult:
          type: string
          description: Location verification result.
          enum:
          - 'TRUE'
          - 'FALSE'
          - UNKNOWN
          - PARTIAL
        matchRate:
          type: integer
          description: Confidence percentage (0-100) when result is PARTIAL.
          minimum: 0
          maximum: 100
        lastLocationTime:
          type: string
          format: date-time
          description: Timestamp of the most recent location data used.
  securitySchemes:
    openIdConnect:
      type: openIdConnect
      openIdConnectUrl: https://opengateway.telefonica.com/.well-known/openid-configuration