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

# Execute a device handling intent

> Carry out a device handling: sends the MDM actions (a wipe erases the device for good), puts items back in stock, reassigns or retires them, opens the RETURN_SHIPMENT task when the settings or `returnShipmentRequested` ask for one, and completes the DEVICE_HANDLING task. This is the only way to complete that task: `updateTaskStatus` refuses it. Safe to retry: an intent executed earlier answers `outcome: ALREADY_EXECUTED` and does nothing again. Refused with `INTENT_NOT_FOUND`, `TICKET_CLOSED`, `TICKET_SCHEDULED` before a scheduled task wakes up, `EXECUTION_IN_PROGRESS`, `OFFBOARDING_NOT_OPEN`, `DEVICE_NOT_OWNED_BY_EMPLOYEE`, `REASSIGN_OWNER_REQUIRED`, `DEVICES_NOT_HANDLED` (502: execute again to retry the items that failed).

Key: WriteScope: Company


## OpenAPI

````yaml https://api.getprimo.com/openapi.json post /device-handling-intents/{intentId}/execute
openapi: 3.1.1
info:
  title: Public API - BETA
  description: Read docs on https://docs.getprimo.com/
  version: '1.0'
  contact: {}
servers:
  - url: https://api.getprimo.com
security:
  - apikey: []
tags: []
paths:
  /device-handling-intents/{intentId}/execute:
    post:
      tags:
        - Offboardings
      summary: Execute a device handling intent
      description: >-
        Carry out a device handling: sends the MDM actions (a wipe erases the
        device for good), puts items back in stock, reassigns or retires them,
        opens the RETURN_SHIPMENT task when the settings or
        `returnShipmentRequested` ask for one, and completes the DEVICE_HANDLING
        task. This is the only way to complete that task: `updateTaskStatus`
        refuses it. Safe to retry: an intent executed earlier answers `outcome:
        ALREADY_EXECUTED` and does nothing again. Refused with
        `INTENT_NOT_FOUND`, `TICKET_CLOSED`, `TICKET_SCHEDULED` before a
        scheduled task wakes up, `EXECUTION_IN_PROGRESS`,
        `OFFBOARDING_NOT_OPEN`, `DEVICE_NOT_OWNED_BY_EMPLOYEE`,
        `REASSIGN_OWNER_REQUIRED`, `DEVICES_NOT_HANDLED` (502: execute again to
        retry the items that failed).
      operationId: executeDeviceHandlingIntent
      parameters:
        - name: intentId
          required: true
          in: path
          schema:
            type: string
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteDeviceHandlingIntentResult_Output'
components:
  schemas:
    ExecuteDeviceHandlingIntentResult_Output:
      type: object
      properties:
        outcome:
          type: string
          description: >-
            ALREADY_EXECUTED: an earlier call did the work, nothing was done
            again
          enum:
            - EXECUTED
            - ALREADY_EXECUTED
        intent:
          type: object
          properties:
            id:
              type: string
              description: Intent id, to pass to its update and execute tools
            taskId:
              description: The typed task that tracks this step
              anyOf:
                - type: string
                - type: 'null'
            ticketId:
              description: >-
                The ticket holding that task, usually the offboarding ticket.
                Null if it could not be read back.
              anyOf:
                - type: string
                - type: 'null'
            offboardingId:
              type: string
            executedAt:
              description: When the intent executed; null until then
              anyOf:
                - type: string
                  format: date-time
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                - type: 'null'
            devices:
              type: array
              items:
                type: object
                properties:
                  deviceId:
                    type: string
                  deviceName:
                    anyOf:
                      - type: string
                      - type: 'null'
                  recycle:
                    type: string
                    enum:
                      - PUT_BACK_IN_STOCK
                      - REASSIGN
                      - DECOMISSION
                  data:
                    anyOf:
                      - type: string
                        enum:
                          - SOFT_WIPE
                          - HARD_WIPE
                          - WIPE
                          - LOCK
                          - NOTHING
                      - type: 'null'
                  condition:
                    anyOf:
                      - type: string
                        enum:
                          - BROKEN
                          - FAIR
                          - GOOD
                          - EXCELLENT
                      - type: 'null'
                  notes:
                    anyOf:
                      - type: string
                      - type: 'null'
                  owner:
                    anyOf:
                      - type: string
                      - type: 'null'
                required:
                  - deviceId
                  - deviceName
                  - recycle
                  - data
                  - condition
                  - notes
                  - owner
                additionalProperties: false
            accessories:
              type: array
              items:
                type: object
                properties:
                  accessoryId:
                    type: string
                  accessoryName:
                    anyOf:
                      - type: string
                      - type: 'null'
                  recycle:
                    type: string
                    enum:
                      - PUT_BACK_IN_STOCK
                      - REASSIGN
                      - DECOMISSION
                  owner:
                    anyOf:
                      - type: string
                      - type: 'null'
                required:
                  - accessoryId
                  - accessoryName
                  - recycle
                  - owner
                additionalProperties: false
            returnShipmentRequested:
              type: boolean
          required:
            - id
            - taskId
            - ticketId
            - offboardingId
            - executedAt
            - devices
            - accessories
            - returnShipmentRequested
          additionalProperties: false
      required:
        - outcome
        - intent
      additionalProperties: false
  securitySchemes:
    apikey:
      scheme: bearer
      bearerFormat: API key
      type: http
      description: >-
        Use your Primo API key in the Authorization header as `Bearer
        <API_KEY>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.