openapi: 3.0.3
info:
  title: Verizon ThingSpace Connectivity Management Accounts Devices API
  description: Verizon ThingSpace Connectivity Management API provides device lifecycle management, account administration, session management, SMS messaging, and callback subscription services for IoT device deployments on Verizon's wireless network. Manage device activations, deactivations, SIM changes, service plan changes, and usage reporting for connected IoT devices at scale.
  version: '1.0'
  contact:
    name: Verizon ThingSpace Support
    url: https://thingspace.verizon.com/
  license:
    name: Verizon Terms of Service
    url: https://www.verizon.com/about/terms-conditions/
  x-generated-from: documentation
servers:
- url: https://thingspace.verizon.com/api/m2m/v2
  description: Verizon ThingSpace Connectivity Management API v2
security:
- OAuth2ClientCredentials: []
tags:
- name: Devices
  description: Device activation, deactivation, and management
paths:
  /accounts/{accountName}/devices/actions/list:
    post:
      operationId: listDevicesInAccount
      summary: Verizon List Devices in Account
      description: Returns a list of devices in an account and their associated account, service plan, MDN, and IP address information.
      tags:
      - Devices
      parameters:
      - name: accountName
        in: path
        required: true
        description: Account name
        schema:
          type: string
        example: 0000123456-00001
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceListRequest'
            examples:
              ListDevicesInAccountRequestExample:
                summary: Default listDevicesInAccount request
                x-microcks-default: true
                value:
                  deviceIds:
                  - kind: imei
                    id: '990013907835573'
                  filter:
                    servicePlans:
                    - ThingSpace
      responses:
        '200':
          description: Device list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceListResponse'
              examples:
                ListDevicesInAccount200Example:
                  summary: Default listDevicesInAccount 200 response
                  x-microcks-default: true
                  value:
                    devices:
                    - accountName: 0000123456-00001
                      deviceIds:
                      - kind: imei
                        id: '990013907835573'
                      state: active
                      servicePlan: ThingSpace
                      mdn: '19085551234'
                    hasMoreData: false
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /accounts/{accountName}/devices/actions/activate:
    post:
      operationId: activateDevices
      summary: Verizon Activate Devices
      description: Activate one or more devices to a specified service plan, and optionally set a MDN, service address, custom fields, and device group assignments.
      tags:
      - Devices
      parameters:
      - name: accountName
        in: path
        required: true
        description: Account name
        schema:
          type: string
        example: 0000123456-00001
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivateDevicesRequest'
            examples:
              ActivateDevicesRequestExample:
                summary: Default activateDevices request
                x-microcks-default: true
                value:
                  devices:
                  - deviceIds:
                    - kind: imei
                      id: '990013907835573'
                    servicePlan: ThingSpace
                    mdnZipCode: 08540
      responses:
        '200':
          description: Device activation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceRequestResponse'
              examples:
                ActivateDevices200Example:
                  summary: Default activateDevices 200 response
                  x-microcks-default: true
                  value:
                    requestId: 595f5c44-c31c-4552-8670-020a1545a959
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /accounts/{accountName}/devices/actions/deactivate:
    post:
      operationId: deactivateDevices
      summary: Verizon Deactivate Devices
      description: Deactivate one or more devices from the Verizon wireless network. Deactivated devices are billed for the remainder of their billing cycle.
      tags:
      - Devices
      parameters:
      - name: accountName
        in: path
        required: true
        description: Account name
        schema:
          type: string
        example: 0000123456-00001
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeactivateDevicesRequest'
            examples:
              DeactivateDevicesRequestExample:
                summary: Default deactivateDevices request
                x-microcks-default: true
                value:
                  devices:
                  - deviceIds:
                    - kind: imei
                      id: '990013907835573'
                  reasonCode: FF
      responses:
        '200':
          description: Device deactivation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceRequestResponse'
              examples:
                DeactivateDevices200Example:
                  summary: Default deactivateDevices 200 response
                  x-microcks-default: true
                  value:
                    requestId: 595f5c44-c31c-4552-8670-020a1545a959
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ActivateDevicesRequest:
      type: object
      required:
      - devices
      description: Request to activate one or more devices
      properties:
        devices:
          type: array
          items:
            type: object
            properties:
              deviceIds:
                type: array
                items:
                  $ref: '#/components/schemas/DeviceId'
              servicePlan:
                type: string
                description: Service plan to activate on
                example: ThingSpace
              mdnZipCode:
                type: string
                description: ZIP code for MDN assignment
                example: 08540
              customFields:
                type: array
                items:
                  type: object
                  properties:
                    key:
                      type: string
                    value:
                      type: string
    DeviceInformation:
      type: object
      description: Device information
      properties:
        accountName:
          type: string
          description: Account the device belongs to
          example: 0000123456-00001
        deviceIds:
          type: array
          items:
            $ref: '#/components/schemas/DeviceId'
        state:
          type: string
          enum:
          - active
          - inactive
          - ready
          - deactivated
          description: Device state
          example: active
        servicePlan:
          type: string
          description: Current service plan
          example: ThingSpace
        mdn:
          type: string
          description: Mobile Directory Number
          example: '19085551234'
    DeviceListRequest:
      type: object
      description: Request to list devices with optional filtering
      properties:
        deviceIds:
          type: array
          items:
            $ref: '#/components/schemas/DeviceId'
        filter:
          type: object
          description: Filter criteria
          properties:
            servicePlans:
              type: array
              items:
                type: string
              description: Filter by service plans
              example:
              - ThingSpace
            states:
              type: array
              items:
                type: string
              description: Filter by device states
            maxNumberOfDevices:
              type: integer
              description: Maximum number of devices to return
              example: 100
    DeviceId:
      type: object
      description: Device identifier
      properties:
        kind:
          type: string
          enum:
          - imei
          - meid
          - esn
          - iccid
          - min
          - mdn
          - otaid
          description: Type of device identifier
          example: imei
        id:
          type: string
          description: Device identifier value
          example: '990013907835573'
    DeviceRequestResponse:
      type: object
      description: Response containing request ID for async operations
      properties:
        requestId:
          type: string
          description: Unique request ID to track the operation
          example: 595f5c44-c31c-4552-8670-020a1545a959
        failedDevices:
          type: array
          items:
            type: object
            properties:
              deviceId:
                type: string
              cause:
                type: string
    DeactivateDevicesRequest:
      type: object
      required:
      - devices
      - reasonCode
      description: Request to deactivate one or more devices
      properties:
        devices:
          type: array
          items:
            type: object
            properties:
              deviceIds:
                type: array
                items:
                  $ref: '#/components/schemas/DeviceId'
        reasonCode:
          type: string
          description: Reason code for deactivation
          example: FF
        etfWaiver:
          type: boolean
          description: Whether to waive early termination fee
          example: false
    DeviceListResponse:
      type: object
      description: Response containing list of devices
      properties:
        devices:
          type: array
          items:
            $ref: '#/components/schemas/DeviceInformation'
        hasMoreData:
          type: boolean
          description: Whether there are more devices to retrieve
          example: false
        lastSeenDeviceId:
          type: string
          description: ID of the last device returned for pagination
          example: '990013907835573'
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://thingspace.verizon.com/api/m2m/v2/session/token
          scopes:
            DISCOVERYREAD: Read discovery information
            SERVICEPROFILEREAD: Read service profiles
            EVENTSREAD: Read device events