> This page is for API, version 2026-01-01 (Stable) (default). > For other versions, use one of these documentation indexes: > - 2026-01-01 (Stable) (default): https://developer.deel.com/api/stable/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.deel.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server. # Retrieving a device from a worker > Collect a device back to your own warehouse, hand it to Deel for reuse, or start a clearance request. 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. > **Some endpoints in this guide are in Beta** > > The `GET /rest/it/assets` and `GET /rest/it/assets/{asset_id}` endpoints are stable. Other Deel IT endpoints in this guide are in Beta and may have changes to their request and response shapes. See [API versioning](/api/api-versioning) for details on endpoint lifecycle states. ## 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 #### A Deel account with Deel IT enabled Your organization must be onboarded to Deel IT. Clearance is a separate service that must be enabled for your organization before `POST /rest/it/assets/{asset_id}/clear` will succeed. See [Getting Started with Deel IT](https://help.letsdeel.com/hc/en-gb/articles/28400594460305-Getting-Started-with-Deel-IT) for the account setup steps, and [Deel IT Device Clearance Service](https://help.letsdeel.com/hc/en-gb/articles/28495986322321-Deel-IT-Device-Clearance-Service) for details on the clearance service. #### An API token with the required scopes Three scopes cover all three destinations: * `it-assets:read` to list the assets currently with a worker. * `it-service-requests:write` to trigger a collect or clearance request. * `people:read` to resolve a worker or manager to an `hris_profile_id`. #### A destination for the device Each path needs one of the following: * A warehouse `id` from your organization when collecting to your own warehouse. * Nothing extra to collect to a Deel-managed hub — you pass `store_and_reuse_location: "DEEL_HUB"` or `"LOCAL_HUB"`. * A manager `hris_profile_id` when starting a clearance request; this manager is recorded as the requester and receives lifecycle notifications. ## 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](/api/deel-it/endpoints/assets/list-it-assets) reference. ```bash 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:** ```json focus={4,7,11-16} { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "public_id": "ITM-550E8400", "grade": "B", "status": "ACTIVE", "location": "WITH_USER", "ownership": { "type": "ORGANIZATION", "name": "Acme Corporation" }, "product": { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "MacBook Pro 14", "brand": "Apple", "category": "LAPTOP" } } ], "has_more": false, "next_cursor": null, "total_count": 1 } ``` 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 #### Collect to your own warehouse Use this path to bring the device back into an organization-owned warehouse. Requires `it-service-requests:write` scope. The `warehouse_id` must reference a warehouse your organization owns; passing a Deel-managed warehouse ID fails. The `country` field on `collection_address` overrides the country Deel derives from the asset's current state — useful when the worker is picking up from an address different from what Deel has on file. See the [Create a collection for an IT asset](/api/deel-it/endpoints/assets/collect-it-asset) reference. ```bash 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" } } }' ``` If you would rather ship without insurance, set `shipment_insurance.is_waived` to `true` and omit `purchase_details`. Use `not_before` to schedule the pickup for a later date. #### Collect to a Deel warehouse for reuse Use this path to hand the device to Deel so it can be reused for another worker in your organization later, without you receiving the hardware in between. Requires `it-service-requests:write` scope. See the [Create a collection for an IT asset](/api/deel-it/endpoints/assets/collect-it-asset) reference. Instead of a warehouse ID, pass `store_and_reuse_location` with one of two values: * `LOCAL_HUB` — Deel stores the device in the same region as the current holder. * `DEEL_HUB` — Deel stores the device in a central Deel hub. ```bash 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 '{ "store_and_reuse_location": "LOCAL_HUB", "collection_address": { "country": "GB" }, "shipment_insurance": { "is_waived": false, "purchase_details": { "price": { "amount": "1999.99", "currency": "EUR" }, "date": "2024-05-01" } } }' ``` Once the device is received and processed, it becomes available for reassignment via the store-and-reuse rental flow. See [Storing and Reusing Devices with Deel IT](https://help.letsdeel.com/hc/en-gb/articles/28397372249361-Storing-and-Reusing-Devices-with-Deel-IT) for the details of that lifecycle. #### Clear the asset Use this path when the device is at end of life and you want Deel to retire it for resale value or certified data erasure. Requires `it-service-requests:write` scope. Clearance must be enabled for your organization. See the [Create a clearance request for an asset](/api/deel-it/endpoints/clearance-requests/clear-it-asset) reference. The endpoint takes a single required field: `manager_hris_profile_id`, the HRIS profile of a manager in your organization who is recorded as the requester and receives lifecycle notifications on the resulting clearance request. ```bash curl --request POST 'https://api.letsdeel.com/rest/it/assets/{asset_id}/clear' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "manager_hris_profile_id": "0f2a1c8d-3b4e-4a5f-9c6d-7e8f9a0b1c2d" }' ``` **Example response:** ```json focus={4,6,17-21} { "data": { "id": "7c3e0a12-9b4f-4d21-8e5a-1b6c3d0f7a92", "public_id": "CLR-7C3E0A12", "status": "PENDING_QUOTE", "cancelled_reason": null, "created_at": "2026-08-08T09:49:01.000Z", "expires_at": "2026-08-22T09:49:01.000Z", "request_items": [ { "id": "b2f4d5a1-0e6c-4f89-9a3b-5c7d1e0f8b34", "status": "PENDING_QUOTE", "asset": { "id": "550e8400-e29b-41d4-a716-446655440000", "public_id": "ITM-550E8400", "serial_number": "C02XL0AAAAAA", "product": { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "MacBook Pro 14", "brand": "Apple", "category": "LAPTOP" } }, "quote_price": null } ] } } ``` Do not poll the asset to detect progress — the asset stays where it is until the clearance completes. Instead, follow the `status` on the clearance request itself, which you can read via [`GET /rest/it/clearance-requests/{clearance_request_id}`](/api/deel-it/endpoints/clearance-requests/get-clearance-request-by-id): | `status` | Meaning | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PENDING_QUOTE` | Waiting for a quote from the clearance partner. | | `PENDING_DECISION` | A quote has been offered. Decide it via [`POST /rest/it/clearance-requests/{clearance_request_id}/decide`](/api/deel-it/endpoints/clearance-requests/decide-clearance-request). | | `DECIDED` | The decision is recorded. Deel is executing the resulting action. | | `COMPLETED` | The clearance request is fully processed. | | `CANCELLED` | The request was cancelled. `cancelled_reason` explains why. | > **Info** > > Clearance requests have a deadline. If the manager does not decide a quote before `expires_at`, the request is cancelled with `cancelled_reason: DEADLINE_EXCEEDED`. ## 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}`](/api/deel-it/endpoints/assets/get-it-asset-by-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](/api/webhooks/introduction) for how to register an endpoint and verify signatures, and [Discovering available events](/api/webhooks/events) for the full event catalogue. > **Info** > > Clearance requests do not currently emit webhook events — poll [`GET /rest/it/clearance-requests/{clearance_request_id}`](/api/deel-it/endpoints/clearance-requests/get-clearance-request-by-id) to track the clearance status through to `COMPLETED`. ## 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. #### Resolve the worker's HRIS profile Look up or receive the worker's `hris_profile_id`. #### List the worker's active devices Call `GET /rest/it/assets?hris_profile_id={worker_id}&location=WITH_USER&status=ACTIVE` to get every device currently with them. #### Choose a destination for each device Apply your own policy — for example, laptops in good condition go to a Deel hub for reuse, laptops at end of life go to clearance, and everything else goes back to your own warehouse. #### Trigger the right request per device Call `POST /rest/it/assets/{asset_id}/collect` for a collect, or `POST /rest/it/assets/{asset_id}/clear` for a clearance. #### Confirm the outcome For collect, watch for `location=AT_WAREHOUSE` on the resulting asset — either by polling `GET /rest/it/assets/{asset_id}` or by subscribing to `it-asset.location-updated`. For clear, poll the clearance request `status` until it reaches `COMPLETED`. Then close out the task in your internal system.