openapi: 3.0.3
info:
  title: AT&T Enterprise Connectivity APIs Device Status SIM Swap API
  description: Enterprise-grade APIs for AT&T wireline business services including service qualification, quoting, ordering, and provisioning. The Alliance API suite supports automated ordering of AVPN, IPBB, ATTPhone, ASE, and AT&T Internet Air for Business services.
  version: 1.0.0
  contact:
    name: AT&T Alliance Developer Portal
    url: https://devex-web.att.com/alliance
  termsOfService: https://www.att.com/gen/general?pid=11561
servers:
- url: https://devex-web.att.com
  description: AT&T Enterprise API Server
security:
- oauth2: []
tags:
- name: SIM Swap
  description: SIM card change detection for fraud prevention
paths:
  /sim-swap/v1/check:
    post:
      operationId: checkSimSwap
      summary: Check AT&T SIM Swap Status
      description: Check whether a SIM swap has occurred for a phone number within a specified time period to detect fraud.
      tags:
      - SIM Swap
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimSwapCheckRequest'
            examples:
              check:
                summary: SIM Swap Check
                value:
                  phoneNumber: '+12125551234'
                  maxAge: 240
      responses:
        '200':
          description: SIM swap check result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimSwapCheckResponse'
              examples:
                notSwapped:
                  summary: No Recent SIM Swap
                  value:
                    swapped: false
                swapped:
                  summary: SIM Swap Detected
                  value:
                    swapped: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /sim-swap/v1/retrieve-date:
    post:
      operationId: retrieveSimSwapDate
      summary: Retrieve AT&T SIM Swap Date
      description: Retrieve the most recent date when a SIM swap occurred for a given phone number.
      tags:
      - SIM Swap
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimSwapDateRequest'
            examples:
              retrieve:
                summary: Retrieve SIM Swap Date
                value:
                  phoneNumber: '+12125551234'
      responses:
        '200':
          description: SIM swap date retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimSwapDateResponse'
              examples:
                withDate:
                  summary: SIM Swap Date Found
                  value:
                    latestSimChange: '2026-04-15T14:30:00Z'
        '404':
          description: No SIM swap records found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SimSwapCheckResponse:
      type: object
      properties:
        swapped:
          type: boolean
          description: Whether a SIM swap occurred within the specified time period
    SimSwapDateRequest:
      type: object
      required:
      - phoneNumber
      properties:
        phoneNumber:
          type: string
          description: E.164 format phone number
          pattern: ^\+[1-9]\d{1,14}$
    SimSwapDateResponse:
      type: object
      properties:
        latestSimChange:
          type: string
          format: date-time
          description: Timestamp of most recent SIM swap
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        code:
          type: string
          description: CAMARA error code
        message:
          type: string
          description: Error description
    SimSwapCheckRequest:
      type: object
      required:
      - phoneNumber
      properties:
        phoneNumber:
          type: string
          description: E.164 format phone number
          pattern: ^\+[1-9]\d{1,14}$
        maxAge:
          type: integer
          description: Maximum age in hours for SIM swap lookback period
          minimum: 1
          maximum: 2400
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://devex-web.att.com/oauth/token
          scopes:
            enterprise: Access AT&T enterprise connectivity APIs