Retrieving a device from a worker

When a worker leaves your organization, or when they hand back an old device as part of a refresh, IT needs to get the hardware off the worker’s desk and into the right destination. The Deel IT Public API supports three destinations, and the right choice depends on what you want to do with the device next.

This guide covers all three destinations on one page so you can implement the decision logic in your own service and route each device to whichever destination fits your policy.

Choosing an approach

Sending the device to one of your own warehouses puts the hardware back in your inventory, ready to be redeployed to another worker later. Handing it to Deel for store-and-reuse asks Deel to receive the device into a Deel-managed hub so it can be redeployed on your behalf without a warehouse round-trip. Starting a clearance request retires the device at end of life for resale value or certified data erasure. Which one to prefer, and in what order, depends on the device’s condition, the worker’s location, and your internal policy — this guide describes all three mechanisms and leaves the choice to you.

Prerequisites

Step 1: Find the assets currently with the worker

Every path acts on an asset_id. If your event carries it, skip ahead. If not, list the worker’s active assets to find the ones you want to retrieve. See the List IT assets reference.

$
curl --request GET 'https://api.letsdeel.com/rest/it/assets?hris_profile_id={hris_profile_id}&location=WITH_USER&status=ACTIVE' \
>
  --header 'Authorization: Bearer YOUR_API_TOKEN'

Example response:

1
{
2
  "data": [
3
    {
4
      "id": "550e8400-e29b-41d4-a716-446655440000",
5
      "public_id": "ITM-550E8400",
6
      "grade": "B",
7
      "status": "ACTIVE",
8
      "location": "WITH_USER",
9
      "ownership": {
10
        "type": "ORGANIZATION",
11
        "name": "Acme Corporation"
12
      },
13
      "product": {
14
        "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
15
        "name": "MacBook Pro 14",
16
        "brand": "Apple",
17
        "category": "LAPTOP"
18
      }
19
    }
20
  ],
21
  "has_more": false,
22
  "next_cursor": null,
23
  "total_count": 1
24
}

Each asset carries an id — this is the asset_id you pass to /collect or /clear in the next step. Its grade and product help you decide the right destination for each device.

Step 2: Route each device to a destination

$
curl --request POST 'https://api.letsdeel.com/rest/it/assets/{asset_id}/collect' \
>
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
>
  --header 'Content-Type: application/json' \
>
  --data '{
>
    "warehouse_id": "d0eddf1c-64ac-4f4c-8a3b-6cd6f0f2c0f8",
>
    "collection_address": {
>
      "country": "GB"
>
    },
>
    "shipment_insurance": {
>
      "is_waived": false,
>
      "purchase_details": {
>
        "price": { "amount": "1999.99", "currency": "EUR" },
>
        "date": "2024-05-01"
>
      }
>
    }
>
  }'

Step 3: Track the outcome

POST /rest/it/assets/{asset_id}/collect returns 200 OK. That confirms the request was created, not that the device has moved. The asset then transitions through three location states:

• WITH_USER — the request has been created but the courier has not picked the device up yet.
• WITH_COURIER — the courier has the device in transit. assigned_user becomes null once pickup is registered.
• AT_WAREHOUSE — the device has arrived at the destination. assigned_warehouse is populated with the warehouse that received it.

Polling for the terminal state

Poll GET /rest/it/assets/{asset_id} to detect the final AT_WAREHOUSE state.

React to a webhook instead

If you would rather not poll, subscribe to the it-asset.location-updated event to receive a callback whenever an asset’s location changes. Deel delivers a webhook when the asset moves to WITH_COURIER and again when it arrives at AT_WAREHOUSE. Filter incoming events on the asset ID you started the collect with, and check the location field to detect the terminal state.

See Webhooks for how to register an endpoint and verify signatures, and Discovering available events for the full event catalogue.

Example automated flow

If you are building this as an automated service — for example, an offboarding workflow that runs whenever a worker leaves — here is one example of how the steps can be sequenced. This is illustrative; the API does not prescribe any particular order, and you can adapt these steps to fit your own policy.