Create a device handling intent

curl --request POST \
  --url https://api.getprimo.com/device-handling-intents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "offboardingId": "<string>",
  "devices": [
    {
      "deviceId": "<string>",
      "deviceName": "<string>",
      "notes": "<string>",
      "owner": "<string>"
    }
  ],
  "accessories": [
    {
      "accessoryId": "<string>",
      "accessoryName": "<string>",
      "owner": "<string>"
    }
  ],
  "returnShipmentRequested": true,
  "parentTicketId": "<string>"
}
'

import requests

url = "https://api.getprimo.com/device-handling-intents"

payload = {
    "offboardingId": "<string>",
    "devices": [
        {
            "deviceId": "<string>",
            "deviceName": "<string>",
            "notes": "<string>",
            "owner": "<string>"
        }
    ],
    "accessories": [
        {
            "accessoryId": "<string>",
            "accessoryName": "<string>",
            "owner": "<string>"
        }
    ],
    "returnShipmentRequested": True,
    "parentTicketId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    offboardingId: '<string>',
    devices: [
      {
        deviceId: '<string>',
        deviceName: '<string>',
        notes: '<string>',
        owner: '<string>'
      }
    ],
    accessories: [{accessoryId: '<string>', accessoryName: '<string>', owner: '<string>'}],
    returnShipmentRequested: true,
    parentTicketId: '<string>'
  })
};

fetch('https://api.getprimo.com/device-handling-intents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getprimo.com/device-handling-intents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'offboardingId' => '<string>',
    'devices' => [
        [
                'deviceId' => '<string>',
                'deviceName' => '<string>',
                'notes' => '<string>',
                'owner' => '<string>'
        ]
    ],
    'accessories' => [
        [
                'accessoryId' => '<string>',
                'accessoryName' => '<string>',
                'owner' => '<string>'
        ]
    ],
    'returnShipmentRequested' => true,
    'parentTicketId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getprimo.com/device-handling-intents"

	payload := strings.NewReader("{\n  \"offboardingId\": \"<string>\",\n  \"devices\": [\n    {\n      \"deviceId\": \"<string>\",\n      \"deviceName\": \"<string>\",\n      \"notes\": \"<string>\",\n      \"owner\": \"<string>\"\n    }\n  ],\n  \"accessories\": [\n    {\n      \"accessoryId\": \"<string>\",\n      \"accessoryName\": \"<string>\",\n      \"owner\": \"<string>\"\n    }\n  ],\n  \"returnShipmentRequested\": true,\n  \"parentTicketId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getprimo.com/device-handling-intents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"offboardingId\": \"<string>\",\n  \"devices\": [\n    {\n      \"deviceId\": \"<string>\",\n      \"deviceName\": \"<string>\",\n      \"notes\": \"<string>\",\n      \"owner\": \"<string>\"\n    }\n  ],\n  \"accessories\": [\n    {\n      \"accessoryId\": \"<string>\",\n      \"accessoryName\": \"<string>\",\n      \"owner\": \"<string>\"\n    }\n  ],\n  \"returnShipmentRequested\": true,\n  \"parentTicketId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getprimo.com/device-handling-intents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"offboardingId\": \"<string>\",\n  \"devices\": [\n    {\n      \"deviceId\": \"<string>\",\n      \"deviceName\": \"<string>\",\n      \"notes\": \"<string>\",\n      \"owner\": \"<string>\"\n    }\n  ],\n  \"accessories\": [\n    {\n      \"accessoryId\": \"<string>\",\n      \"accessoryName\": \"<string>\",\n      \"owner\": \"<string>\"\n    }\n  ],\n  \"returnShipmentRequested\": true,\n  \"parentTicketId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "taskId": "<string>",
  "ticketId": "<string>",
  "offboardingId": "<string>",
  "executedAt": "2023-11-07T05:31:56Z",
  "devices": [
    {
      "deviceId": "<string>",
      "deviceName": "<string>",
      "recycle": "PUT_BACK_IN_STOCK",
      "data": "SOFT_WIPE",
      "condition": "BROKEN",
      "notes": "<string>",
      "owner": "<string>"
    }
  ],
  "accessories": [
    {
      "accessoryId": "<string>",
      "accessoryName": "<string>",
      "recycle": "PUT_BACK_IN_STOCK",
      "owner": "<string>"
    }
  ],
  "returnShipmentRequested": true
}

Offboardings

Create a device handling intent

Create the DEVICE_HANDLING task of an offboarding: what happens to the leaver devices and accessories, and whether a return shipment is wanted. Left out, the lists hold every item of the leaver with the defaults of the offboarding settings. Each device and accessory of the leaver goes back in stock (PUT_BACK_IN_STOCK), to a new owner (REASSIGN) or out of the fleet (DECOMISSION), with an optional MDM action on its data (data: WIPE, LOCK…). Item ids come from getEmployee of the leaver (deviceIds, accessoryIds). Returns the intent id, its taskId and the ticketId holding it. The task cannot be marked done by hand: updateTaskStatus refuses it with TaskLockedByTypeError, and it completes when the intent executes. The offboarding opens this task itself (createOffboarding); its intentId is on the task (getTicket). Create one only for a step the offboarding did not open. createTicket and createTask cannot make a typed task. Refused with OFFBOARDING_NOT_FOUND, PARENT_TICKET_NOT_FOUND, PARENT_TICKET_IS_TYPED or PARENT_TICKET_IS_A_TASK (pass the untyped ticket instead), OFFBOARDING_NOT_OPEN, DEVICE_NOT_OWNED_BY_EMPLOYEE, ACCESSORY_NOT_OWNED_BY_EMPLOYEE, REASSIGN_OWNER_REQUIRED, REASSIGN_OWNER_IS_LEAVER, REASSIGN_OWNER_NOT_FOUND.

POST

device-handling-intents

curl --request POST \
  --url https://api.getprimo.com/device-handling-intents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "offboardingId": "<string>",
  "devices": [
    {
      "deviceId": "<string>",
      "deviceName": "<string>",
      "notes": "<string>",
      "owner": "<string>"
    }
  ],
  "accessories": [
    {
      "accessoryId": "<string>",
      "accessoryName": "<string>",
      "owner": "<string>"
    }
  ],
  "returnShipmentRequested": true,
  "parentTicketId": "<string>"
}
'

import requests

url = "https://api.getprimo.com/device-handling-intents"

payload = {
    "offboardingId": "<string>",
    "devices": [
        {
            "deviceId": "<string>",
            "deviceName": "<string>",
            "notes": "<string>",
            "owner": "<string>"
        }
    ],
    "accessories": [
        {
            "accessoryId": "<string>",
            "accessoryName": "<string>",
            "owner": "<string>"
        }
    ],
    "returnShipmentRequested": True,
    "parentTicketId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    offboardingId: '<string>',
    devices: [
      {
        deviceId: '<string>',
        deviceName: '<string>',
        notes: '<string>',
        owner: '<string>'
      }
    ],
    accessories: [{accessoryId: '<string>', accessoryName: '<string>', owner: '<string>'}],
    returnShipmentRequested: true,
    parentTicketId: '<string>'
  })
};

fetch('https://api.getprimo.com/device-handling-intents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getprimo.com/device-handling-intents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'offboardingId' => '<string>',
    'devices' => [
        [
                'deviceId' => '<string>',
                'deviceName' => '<string>',
                'notes' => '<string>',
                'owner' => '<string>'
        ]
    ],
    'accessories' => [
        [
                'accessoryId' => '<string>',
                'accessoryName' => '<string>',
                'owner' => '<string>'
        ]
    ],
    'returnShipmentRequested' => true,
    'parentTicketId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getprimo.com/device-handling-intents"

	payload := strings.NewReader("{\n  \"offboardingId\": \"<string>\",\n  \"devices\": [\n    {\n      \"deviceId\": \"<string>\",\n      \"deviceName\": \"<string>\",\n      \"notes\": \"<string>\",\n      \"owner\": \"<string>\"\n    }\n  ],\n  \"accessories\": [\n    {\n      \"accessoryId\": \"<string>\",\n      \"accessoryName\": \"<string>\",\n      \"owner\": \"<string>\"\n    }\n  ],\n  \"returnShipmentRequested\": true,\n  \"parentTicketId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getprimo.com/device-handling-intents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"offboardingId\": \"<string>\",\n  \"devices\": [\n    {\n      \"deviceId\": \"<string>\",\n      \"deviceName\": \"<string>\",\n      \"notes\": \"<string>\",\n      \"owner\": \"<string>\"\n    }\n  ],\n  \"accessories\": [\n    {\n      \"accessoryId\": \"<string>\",\n      \"accessoryName\": \"<string>\",\n      \"owner\": \"<string>\"\n    }\n  ],\n  \"returnShipmentRequested\": true,\n  \"parentTicketId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getprimo.com/device-handling-intents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"offboardingId\": \"<string>\",\n  \"devices\": [\n    {\n      \"deviceId\": \"<string>\",\n      \"deviceName\": \"<string>\",\n      \"notes\": \"<string>\",\n      \"owner\": \"<string>\"\n    }\n  ],\n  \"accessories\": [\n    {\n      \"accessoryId\": \"<string>\",\n      \"accessoryName\": \"<string>\",\n      \"owner\": \"<string>\"\n    }\n  ],\n  \"returnShipmentRequested\": true,\n  \"parentTicketId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "taskId": "<string>",
  "ticketId": "<string>",
  "offboardingId": "<string>",
  "executedAt": "2023-11-07T05:31:56Z",
  "devices": [
    {
      "deviceId": "<string>",
      "deviceName": "<string>",
      "recycle": "PUT_BACK_IN_STOCK",
      "data": "SOFT_WIPE",
      "condition": "BROKEN",
      "notes": "<string>",
      "owner": "<string>"
    }
  ],
  "accessories": [
    {
      "accessoryId": "<string>",
      "accessoryName": "<string>",
      "recycle": "PUT_BACK_IN_STOCK",
      "owner": "<string>"
    }
  ],
  "returnShipmentRequested": true
}

Key: Write Scope: Company

Authorizations

Authorization

string

header

required

Use your Primo API key in the Authorization header as Bearer <API_KEY>.

Body

application/json

offboardingId

string

required

The offboarding this step belongs to, from getOffboardings

Pattern: ^[a-f\d]{24}$

devices

object[] | null

What happens to each device; replaced whole

Show child attributes

accessories

object[] | null

What happens to each accessory; replaced whole

Show child attributes

returnShipmentRequested

boolean | null

Ask for a return shipment once the devices are handled, when the settings leave it to each offboarding

parentTicketId

string | null

The ticket to hold the task. Defaults to the offboarding ticket; never a typed task.

Pattern: ^[a-f\d]{24}$

Response

default - application/json

string

required

Intent id, to pass to its update and execute tools

taskId

string | null

required

The typed task that tracks this step

ticketId

string | null

required

The ticket holding that task, usually the offboarding ticket. Null if it could not be read back.

offboardingId

string

required

executedAt

string<date-time> | null

required

When the intent executed; null until then

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))$

devices

object[]

required

Show child attributes

accessories

object[]

required

Show child attributes

returnShipmentRequested

boolean

required

Get started

API Reference

Create a device handling intent

Authorizations

Body

Response