openapi: 3.0.0
info:
  title: VisibilityIQ Device Management.
  version: 1.0.0
servers:
- url: https://api.zebra.com/v3/services/partners
  description: For US
- url: https://api.zebra.com/v3/eu/services/partners
  description: For EU
security:
- BearerAuth: []
- ApiKeyAuth: []
paths:
  /devices/enroll:
    post:
      tags:
      - Device Enrollment
      summary: Enroll the devices
      description: Enroll new device in VIQ by providing company name and asset details.
      operationId: Device Enroll
      parameters:
      - name: companyName
        in: header
        description: Company name
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: partnerName
        in: header
        description: Partner name
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/assetDetails'
      responses:
        "201":
          description: Successfull operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEnroll'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse400'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse401'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse500'
      deprecated: false
  /devices/unenroll:
    post:
      tags:
      - Device Unenrollment
      summary: Unenroll the devices
      description: Unenroll the devices from VIQ
      operationId: Device Unenroll
      parameters:
      - name: companyName
        in: header
        description: Company name
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: partnerName
        in: header
        description: Partner name
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/assetInfo'
      responses:
        "201":
          description: Successfull operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseUnEnroll'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse400'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse401'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse500'
      deprecated: false
  /devices/edit-device:
    put:
      tags:
      - Device Configuration
      summary: Edit the device
      description: Update an existing device in VIQ by providing the company name
        and asset details.
      parameters:
      - name: companyName
        in: header
        description: Company name
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: partnerName
        in: header
        description: Partner name
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/assetDetails'
      responses:
        "201":
          description: Successfull operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseUpdate'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse400'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse401'
        "417":
          description: Expectation Not Met
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseExpectationNotMet'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse500'
      deprecated: false
  /devices/enrollmentstatus:
    post:
      tags:
      - Device Enrollment Status
      summary: Get the status of device enrollment by providing company name and assets
        detail.
      description: Check device enrollment status in VIQ
      operationId: Enrollment Status
      parameters:
      - name: limit
        in: query
        description: 'Pagination size indicating the maximum number of results to
          be returned in the response. Valid values are 1 to 20000. Values higher
          than 20000 will be replaced with 20000. Values less than 1 will be replaced
          with 250. '
        required: false
        style: form
        explode: true
        schema:
          type: integer
          default: 250
      - name: offset
        in: query
        description: 'Pagination parameter indicating the starting record position
          for returning the results from the result set.  Any positive value is acceptable.
          An offset bigger than the number of available results will result in an
          error. A negative value will be replaced with 0. Normally, value should
          be 0 or a positive multiple of limit. '
        required: false
        style: form
        explode: true
        schema:
          type: integer
          default: 0
      - name: companyName
        in: header
        description: Company name
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: partnerName
        in: header
        description: Partner name
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: sort
        in: header
        description: Sort order for the results. Specified as a JSON object. Currently,
          only one sort case is supported in the criteria even though it is an array.
          Elements other than the first one will be ignored currently.
        required: false
        style: simple
        explode: false
        schema:
          type: object
          properties:
            criteria:
              type: array
              items:
                type: object
                properties:
                  a:
                    type: string
                    description: Field to sort by (e.g., ingestion_time).
                    enum:
                    - enroll_status
                    - model
                    - device_name
                    - site_hierarchy
                    - site_name
                    - device_manufacturer
                    - device_type
                    - contract_id
                    - ingestion_time
                  o:
                    type: string
                    description: Sort order (asc or desc).
                    enum:
                    - asc
                    - desc
          example:
            criteria:
            - a: ingestion_time
              o: desc
      - name: filter
        in: header
        description: Filter based on column values. Numeric value will be filtered
          by an exact match. Strings are case insensitive matches. The filter criteria
          are ANDed together.
        required: false
        style: simple
        explode: false
        schema:
          type: object
          properties:
            enroll_status:
              type: string
              description: Filter by enrollment status (e.g., "enrolled", "pending").
            model:
              type: string
              description: Filter by device model (e.g., "TCXXX").
            device_name:
              type: string
              description: Filter by device name.
            site_hierarchy:
              type: string
              description: Filter by site hierarchy.
            site_name:
              type: string
              description: Filter by site name.
            device_manufacturer:
              type: string
              description: Filter by device manufacturer (e.g., "Zebra").
            device_type:
              type: string
              description: Filter by device type (e.g., "Mobile Computer").
            contract_id:
              type: string
              description: Filter by contract ID.
            ingestion_time:
              type: string
              description: Filter by ingestion time.
              format: date-time
          example:
            serialNum: "12312312312329"
            assetName: ABC-TXXXX-12312312312329
      requestBody:
        $ref: '#/components/requestBodies/assetsInfo'
      responses:
        "201":
          description: Successfull operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEnrollmentStatus'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse400'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse401'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse500'
      deprecated: false
  /devices/monthly-average-devices:
    get:
      tags:
      - Monthly Average Devices
      summary: Get the monthly average devices count for a given company name and
        date range.
      description: Get the monthly average devices count.
      operationId: Monthly Average Devices
      parameters:
      - name: companyName
        in: header
        description: Company name
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: partnerName
        in: header
        description: Partner name
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: deviceType
        in: header
        description: Device Type - If no value is selected, by default all 3 are considered.
        required: false
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - MOBILE
          - PRINTER
          - SCANNER
      - name: startMonth
        in: header
        description: Start Month (MM-yyyy)
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: 06-2023
      - name: endMonth
        in: header
        description: End Month (MM-yyyy)
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: 07-2023
      responses:
        "200":
          description: Successfull operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseMonthlyAverageDevice'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse400'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse401'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse500'
      deprecated: false
components:
  schemas:
    ApiResponseEnroll:
      required:
      - response_description
      - response_status
      type: object
      properties:
        response_status:
          type: string
          description: response_status
          example: success/failure
        response_description:
          type: string
          description: response_description
          example: 'Total assets requested for enrollment: 2, Total failed assets
            : 0, Total enrolled assets : 2'
        event_time:
          type: string
          description: event_time
          example: 2023-01-03 12:10:00
        company_name:
          type: string
          description: company_name
          example: TestCompany
        failed_assets:
          type: array
          description: Assets which does not match the enrollment criteria.
          items:
            type: object
            properties:
              serial_number:
                type: string
                example: "123456788"
              model:
                type: string
                example: TCXXX
              reason:
                type: string
                example: invalid serial number
    ApiResponseUpdate:
      required:
      - response_description
      - response_status
      type: object
      properties:
        response_status:
          type: string
          description: response_status
          example: success
        response_description:
          type: string
          description: response_description
          example: 'Serial number: 123456788 has been successfully updated'
        event_time:
          type: string
          description: event_time
          example: 2023-01-03 12:10:00
        company_name:
          type: string
          description: company_name
          example: TestCompany
        partner_name:
          type: string
          description: partner_name
          example: TestCompany
        event_id:
          type: string
          description: event_time
          example: string
    ApiResponseExpectationNotMet:
      required:
      - response_description
      - response_status
      type: object
      properties:
        response_status:
          type: string
          description: response_status
          example: Failure
        response_description:
          type: string
          description: response_description
          example: Edit for MDM device is not allowed
        event_time:
          type: string
          description: event_time
          example: 2023-01-03 12:10:00
        company_name:
          type: string
          description: company_name
          example: TestCompany
        partner_name:
          type: string
          description: partner_name
          example: TestCompany
        event_id:
          type: string
          description: event_time
          example: string
    ApiResponseUnEnroll:
      required:
      - response_description
      - response_status
      type: object
      properties:
        response_status:
          type: string
          description: response_status
          example: success/failure
        response_description:
          type: string
          description: response_description
          example: 'Total assets requested for unenrollment: 2, Total failed assets
            : 0, Total unenrolled assets : 2'
        event_time:
          type: string
          description: event_time
          example: 2023-01-03 12:10:00
        company_name:
          type: string
          description: company_name
          example: TestCompany
        failed_assets:
          type: array
          description: Assets which does not match the unenrollment criteria.
          items:
            type: object
            properties:
              serial_number:
                type: string
                example: "123456788"
              model:
                type: string
                example: TCXXX
              reason:
                type: string
                example: invalid serial number
    ApiResponse400:
      required:
      - response_description
      - response_status
      type: object
      properties:
        id:
          type: string
          description: id
          example: "123"
        status:
          type: integer
          description: status
          example: 400
        code:
          type: string
          description: code
          example: 1.2.1
        title:
          type: string
          description: title
          example: 'ERROR: Bad Request'
        detail:
          type: string
          description: detail
          example: Required parameter missing
        source:
          type: object
          properties:
            parameter:
              type: string
              example: companyName
            pointer:
              type: string
              example: header/companyName
          description: source
    ApiResponse401:
      required:
      - response_description
      - response_status
      type: object
      properties:
        fault:
          type: object
          properties:
            faultstring:
              type: string
              example: Invalid ApiKey
            detail:
              type: object
              properties:
                errorcode:
                  type: string
                  example: oauth.v2.InvalidApiKey
              description: detail
          description: source
    ApiResponse500:
      required:
      - response_description
      - response_status
      type: object
      properties:
        timestamp:
          type: string
          description: timestamp
          example: 2023-01-03T12:10:00
        status:
          type: integer
          description: status
          example: 500
        error:
          type: string
          description: error
          example: Internal Server Error
        path:
          type: string
          description: detail
          example: /partners/devices
    ApiResponseEnrollmentStatus:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 200
        meta:
          type: object
          properties:
            total:
              type: integer
              description: Total number of assets
            offset:
              type: integer
              description: Offset for pagination
            limit:
              type: integer
              description: Number of assets per page
            id:
              type: string
              description: Unique identifier for the request
          description: Pagination information
        links:
          type: object
          properties:
            self:
              type: string
              description: Link to the current page
            first:
              type: string
              description: Link to the first page
            last:
              type: string
              description: Link to the last page
            next:
              type: string
              description: Link to the next page
          description: Links for pagination
        company_name:
          type: string
          description: Company name
          example: TESTCOMPANY
        partner_name:
          type: string
          description: Partner name
          example: TESTPARTNER
        assets:
          type: array
          description: List of assets and their enrollment status
          items:
            type: object
            properties:
              ingestion_time:
                type: string
                description: Time of data ingestion
                format: date-time
                nullable: true
              contract_id:
                type: string
                description: Contract ID
                example: Contract-C1
              serial_number:
                type: string
                description: Device serial number
                example: "12345678"
              device_type:
                type: string
                description: Device type
                example: MOBILE COMPUTER
              device_manufacturer:
                type: string
                description: Device manufacturer
                example: ZEBRA
              site_name:
                type: string
                description: Site name
                example: SITE1
              site_hierarchy:
                type: string
                description: Site hierarchy
                example: SITE1
              device_name:
                type: string
                description: Device name
                example: "12345678"
              model:
                type: string
                description: Device model
                example: TC55
              enroll_status:
                type: string
                description: Enrollment status
                example: Ebrolled
    ApiResponseMonthlyAverageDevice:
      required:
      - customer -partnerName -companyName -companyDisplayName
      - message
      type: object
      properties:
        companyName:
          type: string
          description: Company Name
          example: Test Company
        deviceType:
          type: string
          description: Device Type
          example: '["MOBILE","PRINTER","SCANNER"]'
        monthlyAverageDeviceCount:
          type: array
          example:
          - monthYear: 06-2023
            count: 10
          - monthYear: 07-2023
            count: 10
          items:
            type: string
    ApiError:
      required:
      - data
      - status
      type: object
      properties:
        data:
          type: string
          example: request unsuccessfull
        status:
          type: string
          example: failed
    ApiErrorN:
      required:
      - detail
      - status
      type: object
      properties:
        detail:
          type: string
          example: INTERNAL SERVER ERROR
        status:
          type: string
          example: "500"
    ApiErrorForbidden:
      required:
      - code
      - detail
      - id
      - status
      - title
      type: object
      properties:
        detail:
          type: string
          example: User does not have access to company-partner data
        status:
          type: string
          example: "403"
        code:
          type: string
          example: 1.1.5
        id:
          type: string
          example: adf131j123
  responses:
    Response400:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Response401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Response500:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorN'
  parameters:
    sort:
      name: sort
      in: header
      description: Sort order for the results. Specified as a JSON object. Currently,
        only one sort case is supported in the criteria even though it is an array.
        Elements other than the first one will be ignored currently.
      required: false
      style: simple
      explode: false
      schema:
        type: object
        properties:
          criteria:
            type: array
            items:
              type: object
              properties:
                a:
                  type: string
                  description: Field to sort by (e.g., ingestion_time).
                  enum:
                  - enroll_status
                  - model
                  - device_name
                  - site_hierarchy
                  - site_name
                  - device_manufacturer
                  - device_type
                  - contract_id
                  - ingestion_time
                o:
                  type: string
                  description: Sort order (asc or desc).
                  enum:
                  - asc
                  - desc
        example:
          criteria:
          - a: ingestion_time
            o: desc
    filter:
      name: filter
      in: header
      description: Filter based on column values. Numeric value will be filtered by
        an exact match. Strings are case insensitive matches. The filter criteria
        are ANDed together.
      required: false
      style: simple
      explode: false
      schema:
        type: object
        properties:
          enroll_status:
            type: string
            description: Filter by enrollment status (e.g., "enrolled", "pending").
          model:
            type: string
            description: Filter by device model (e.g., "TCXXX").
          device_name:
            type: string
            description: Filter by device name.
          site_hierarchy:
            type: string
            description: Filter by site hierarchy.
          site_name:
            type: string
            description: Filter by site name.
          device_manufacturer:
            type: string
            description: Filter by device manufacturer (e.g., "Zebra").
          device_type:
            type: string
            description: Filter by device type (e.g., "Mobile Computer").
          contract_id:
            type: string
            description: Filter by contract ID.
          ingestion_time:
            type: string
            description: Filter by ingestion time.
            format: date-time
        example:
          serialNum: "12312312312329"
          assetName: ABC-TXXXX-12312312312329
    offset:
      name: offset
      in: query
      description: 'Pagination parameter indicating the starting record position for
        returning the results from the result set.  Any positive value is acceptable.
        An offset bigger than the number of available results will result in an error.
        A negative value will be replaced with 0. Normally, value should be 0 or a
        positive multiple of limit. '
      required: false
      style: form
      explode: true
      schema:
        type: integer
        default: 0
    limit:
      name: limit
      in: query
      description: 'Pagination size indicating the maximum number of results to be
        returned in the response. Valid values are 1 to 20000. Values higher than
        20000 will be replaced with 20000. Values less than 1 will be replaced with
        250. '
      required: false
      style: form
      explode: true
      schema:
        type: integer
        default: 250
    companyName:
      name: companyName
      in: header
      description: Company name
      required: true
      style: simple
      explode: false
      schema:
        type: string
    partnerName:
      name: partnerName
      in: header
      description: Partner name
      required: true
      style: simple
      explode: false
      schema:
        type: string
    deviceType:
      name: deviceType
      in: header
      description: Device Type - If no value is selected, by default all 3 are considered.
      required: false
      style: simple
      explode: false
      schema:
        type: string
        enum:
        - MOBILE
        - PRINTER
        - SCANNER
    startMonth:
      name: startMonth
      in: header
      description: Start Month (MM-yyyy)
      required: true
      style: simple
      explode: false
      schema:
        type: string
      example: 06-2023
    endMonth:
      name: endMonth
      in: header
      description: End Month (MM-yyyy)
      required: true
      style: simple
      explode: false
      schema:
        type: string
      example: 07-2023
  requestBodies:
    assetDetails:
      description: Device Enroll
      content:
        application/json:
          schema:
            type: object
            properties:
              assets:
                type: array
                items:
                  type: object
                  properties:
                    serial_number:
                      pattern: ^[a-zA-Z0-9]*$
                      type: string
                      description: Device Serial Number
                      nullable: false
                      example: "123456788"
                    model:
                      pattern: ^[a-zA-Z0-9]*$
                      type: string
                      description: Device Model
                      nullable: false
                      example: TCXXX
                    site_name:
                      type: string
                      description: Site name assigned for the device
                      nullable: true
                      example: test_site8
                    site_hierarchy:
                      type: string
                      description: Site hierarchy assigned for the device
                      nullable: true
                      example: test_site8
                    device_name:
                      type: string
                      description: Device name
                      nullable: true
                      example: "123456788"
                    device_type:
                      type: string
                      description: Device Type
                      nullable: false
                      example: Mobile Computer
                      enum:
                      - Mobile Computer
                      - Printer
                      - Scanner
                    device_manufacturer:
                      type: string
                      description: Device Manufacturer
                      nullable: false
                      example: Panasonic
                      enum:
                      - Zebra
                      - Honeywell
                      - Panasonic
                    contract_id:
                      pattern: ^[a-zA-Z0-9-]*$
                      type: string
                      description: Valid Zebra Contract Id for the device
                      nullable: true
                      example: Contract-1234
                    account_number:
                      type: string
                      description: |
                        Account number for VIQSP customers, serving two purposes:
                        1. When clubbed with a contract-id, it imports all devices under this account number.
                        2. When used with a serial number, it validates the device for enrollment.
                        This field is not available for regular customers.
                      nullable: true
                      example: ACC-987654
                      x-conditional-visibility: Only available for VIQSP customers
              event_id:
                type: string
                description: Unique Id for the event(UUID).
                nullable: false
                example: acsad35d114
              event_time:
                type: string
                description: Time when the enroll request comes. It cannot be less
                  than UTC {{current_date_time}}-1hour
                nullable: false
                example: 2023-01-03 12:10:00
      required: true
    assetInfo:
      description: Asset information for unenrollment
      content:
        application/json:
          schema:
            type: object
            properties:
              assets:
                type: array
                items:
                  type: object
                  properties:
                    serial_number:
                      pattern: ^[a-zA-Z0-9]*$
                      type: string
                      description: Device Serial Number
                      nullable: false
                      example: "123456788"
                    model:
                      pattern: ^[a-zA-Z0-9]*$
                      type: string
                      description: Device Model
                      nullable: false
                      example: TCXXX
                    contract_id:
                      pattern: ^[a-zA-Z0-9-]*$
                      type: string
                      description: Valid Zebra Contract Id for the device
                      nullable: true
                      example: Contract-1234
              event_id:
                type: string
                description: Unique Id for the event(UUID).
                nullable: false
                example: acsad35d114
              event_time:
                type: string
                description: Time when the unenroll request comes. It cannot be less
                  than UTC {{current_date_time}}-1hour
                nullable: false
                example: 2023-01-03 12:10:00
      required: true
    assetsInfo:
      description: List of assets
      content:
        application/json:
          schema:
            type: object
            properties:
              serial_number:
                type: array
                description: Device Serial Number
                nullable: true
                items:
                  type: string
                  example: '["123456","789456"]'
              event_id:
                type: string
                description: Searh with unique Id for the event(UUID)
                nullable: false
                example: acsad35d114
              event_time:
                type: string
                description: Search Time when the unenroll request comes. It cannot
                  be less than UTC {{current_date_time}}-1hour
                format: date-time
                nullable: false
      required: true
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      name: X-APIKey
      in: header