Use cases

Equipping a worker

When a new hire joins your organization, or an existing worker wants a device refresh, IT needs to get them a laptop. This is one of the most common workflows to build on the Deel IT Public API. The API supports two paths to the same outcome — a laptop in the worker’s hands — and the right choice depends on the state of your inventory and the rental agreements Deel manages for you.

This guide covers both paths on one page so you can implement the decision logic in your own service and route each request to whichever option fits your policy and current stock.

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 for details on endpoint lifecycle states.

Choosing an approach

Every path starts the same way: resolve the worker to an HRIS profile. Then check whether you can equip them from stock you already own, or from a rental Deel is holding for reuse.

Shipping from your own inventory sends a device your organization already owns from a warehouse to the worker, using Deel logistics. Reassigning a stored rental continues an existing rental agreement by sending a returned device on to the next holder. Which one to prefer, and in what order, depends on your existing agreements, stock levels, and internal policy — this guide describes both mechanisms and leaves the choice to you.

Prerequisites

Your organization must be onboarded to Deel IT and have at least one warehouse or rental agreement to draw from. See Getting Started with Deel IT for the account setup steps, and How Deel IT Device Lifecycle Management Works for background on what the API automates.

Four scopes cover both paths and the HRIS profile lookup:

  • it-assets:read to search your inventory for available devices.
  • it-agreements:read to search Deel-held rentals available for reuse.
  • it-service-requests:write to trigger delivery or reassignment.
  • people:read to resolve a worker to an hris_profile_id.

Every path ends in a shipment. Collect the worker’s shipping address if it is not already recorded in Deel. See Delivery Coverage, Delivery Times, and Express Shipping for the countries Deel logistics operates in and available service tiers.

Step 1: Resolve the worker’s HRIS profile

The Deel IT Public API identifies people by hris_profile_id. If your event does not carry it, look it up via the List people endpoint on the Deel core Public API.

$curl --request GET 'https://api.letsdeel.com/rest/people?email=nina.roth@example.com' \
>  --header 'Authorization: Bearer YOUR_API_TOKEN'

Example response:

1{
2  "data": [
3    {
4      "id": "9b9fc43a-a90c-4615-ac50-baf1e314b53e",
5      "first_name": "Nina",
6      "last_name": "Roth",
7      "full_name": "Nina Roth",
8      "emails": [
9        {
10          "type": "work",
11          "value": "nina.roth@example.com"
12        }
13      ],
14      "job_title": "Product Manager",
15      "department": {
16        "id": "5f8a2c1e-3b47-4e89-9f2c-8d1e3a4b5c6f",
17        "name": "Product"
18      },
19      "hiring_status": "onboarding"
20    }
21  ]
22}

The id field is the person’s hris_profile_id. The rest of the workflow uses it as the hris_profile_id in every request body.

Step 2: Ship the device

The API supports two paths. Pick one based on your policy and current stock; the API does not prescribe an order.

Use this path to send a device your organization already owns from a warehouse to the worker. Deel arranges the shipment. Requires it-assets:read and it-service-requests:write scopes.

First, list assets at a warehouse, filtered by the category the worker needs. status=ACTIVE excludes archived devices; location=AT_WAREHOUSE scopes to stock available for shipment. See the List IT assets reference.

$curl --request GET 'https://api.letsdeel.com/rest/it/assets?location=AT_WAREHOUSE&category=LAPTOP&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": "A",
7      "status": "ACTIVE",
8      "location": "AT_WAREHOUSE",
9      "product": {
10        "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
11        "name": "MacBook Pro 14",
12        "brand": "Apple",
13        "category": "LAPTOP"
14      },
15      "assigned_user": null
16    },
17    {
18      "id": "3f8b1c0d-6a4e-4c99-8b7d-2f9e3a1b4c5d",
19      "public_id": "ITM-3F8B1C0D",
20      "grade": "A",
21      "status": "ACTIVE",
22      "location": "AT_WAREHOUSE",
23      "product": {
24        "id": "8ac7b820-9dad-11d1-80b4-00c04fd430c8",
25        "name": "ThinkPad X1 Carbon",
26        "brand": "Lenovo",
27        "category": "LAPTOP"
28      },
29      "assigned_user": null
30    }
31  ],
32  "has_more": true,
33  "next_cursor": "eyJvZmZzZXQiOjIsImxpbWl0IjoyMH0",
34  "total_count": 47
35}

Each asset carries an id — this is the asset_id you pass to /deliver in the next step. The product block describes what the hardware actually is. Pick an asset from the response. If you need to filter further on specifications, see the Retrieve an IT asset reference.

When has_more is true, pass the next_cursor value as the cursor query parameter on the next request to page through the rest of the inventory.

Then, submit a delivery service request. Deel schedules and arranges the shipment. See the Create a delivery request for an IT asset reference.

$curl --request POST 'https://api.letsdeel.com/rest/it/assets/{asset_id}/deliver' \
>  --header 'Authorization: Bearer YOUR_API_TOKEN' \
>  --header 'Content-Type: application/json' \
>  --data '{
>    "hris_profile_id": "prof_9f2c",
>    "delivery_address": {
>      "country": "GB",
>      "city": "London",
>      "postal_code": "EC1A 1BB",
>      "address_line_1": "10 Onboarding Street"
>    },
>    "is_express_delivery": false
>  }'

Once the shipment is delivered, the asset’s location transitions to WITH_USER and assigned_user reflects the worker.

Step 3: Track the shipment to delivery

Both paths result in a shipment that Deel logistics fulfils asynchronously. POST /rest/it/assets/{asset_id}/deliver and POST /rest/it/agreements/{agreement_id}/reassign return 200 OK with the current asset state. That response confirms the delivery service request was created, not that the device is on the worker’s desk. Immediately after the call, the asset is still at the warehouse: location is AT_WAREHOUSE and assigned_user is null.

As Deel logistics processes the shipment, the asset moves through two more location states:

  • WITH_COURIER — the courier has picked up the device and it is in transit. assigned_user is still null at this stage.
  • WITH_USER — the shipment has been delivered. assigned_user is now populated with the worker’s HRIS profile.

Polling for the terminal state

Poll GET /rest/it/assets/{asset_id} and watch for location to become WITH_USER and assigned_user to be populated.

$curl --request GET 'https://api.letsdeel.com/rest/it/assets/{asset_id}' \
>  --header 'Authorization: Bearer YOUR_API_TOKEN'

Example response after delivery:

1{
2  "data": {
3    "id": "550e8400-e29b-41d4-a716-446655440000",
4    "public_id": "ITM-550E8400",
5    "created_at": "2025-01-15T10:30:00.000Z",
6    "updated_at": "2025-02-01T14:22:00.000Z",
7    "serial_number": "C02XL0AAAAAA",
8    "grade": "A",
9    "status": "ACTIVE",
10    "location": "WITH_USER",
11    "ownership": {
12      "type": "ORGANIZATION",
13      "name": "Acme Corporation"
14    },
15    "assigned_user": {
16      "hris_profile_id": "9b9fc43a-a90c-4615-ac50-baf1e314b53e",
17      "first_name": "Nina",
18      "last_name": "Roth",
19      "emails": ["nina.roth@example.com"],
20      "address": {
21        "id": "aabbccdd-eeff-0011-2233-445566778899",
22        "type": "DELIVERY",
23        "line1": "10 Onboarding Street",
24        "city": "London",
25        "post_code": "EC1A 1BB",
26        "country": "GB",
27        "is_valid": true
28      }
29    },
30    "assigned_warehouse": null,
31    "product": {
32      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
33      "name": "MacBook Pro 14",
34      "brand": "Apple",
35      "category": "LAPTOP"
36    }
37  }
38}

The example above shows the terminal state: location is WITH_USER and assigned_user is populated with the worker’s HRIS profile. That is the signal to close out the onboarding or refresh task in your internal system.

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 moves to WITH_USER. Filter incoming events on the asset ID you started the delivery 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.

When you reassign a rental, the previous asset record is archived and a new asset is created for the worker. Track continuity through the agreement_id, not the asset_id.

Example automated flow

If you are building this as an automated service, here is one example of how the steps can be sequenced end to end. This is illustrative — the API does not prescribe any particular order, and you can adapt or reorder these steps to fit your own policy.

1

Resolve the HRIS profile

Look up or receive the worker’s hris_profile_id.

2

Check your inventory

Call GET /rest/it/assets?location=AT_WAREHOUSE&status=ACTIVE&category={category} to see which owned devices are available in your warehouses.

3

Check for stored rentals

Call GET /rest/it/agreements?type=RENTAL&store_and_reuse_status=READY to see which rented devices are available for reassignment.

4

Pick a candidate and ship it

Apply your own selection logic across the two result sets. Call POST /rest/it/assets/{asset_id}/deliver for an owned device or POST /rest/it/agreements/{agreement_id}/reassign for a rental, and stop.

5

Confirm delivery

Watch for location=WITH_USER on the resulting asset — either by polling GET /rest/it/assets/{asset_id} or by subscribing to it-asset.location-updated — then close out the task in your internal system.