Skip to navigation
Use cases

Ordering new equipment for a worker

When a new hire joins your organization, or an existing worker needs a device, IT needs to get them the right equipment. With the Deel IT Public API you can reproduce the Deel IT ordering flow from your own onboarding or procurement workflow: browse the catalog, pick a product variant, then place an order for the worker.

In the Deel app, the same flow happens under Equipment > Orders > Create Order.

Some endpoints in this guide are in Beta

The GET /rest/it/orders/{order_id} endpoint is stable. Other Deel IT endpoints in this guide are in Beta, require the X-Beta: true header, and may have changes to their request and response shapes. The examples below include the header where it is required. See API versioning for details on endpoint lifecycle states.

Other ways to equip a worker

You can also equip a worker by shipping a device from your own inventory, or by reassigning a stored rental. See Sending your equipment to a worker for those two paths.

Prerequisites

Your organization must be onboarded to Deel IT. See Getting Started with Deel IT for the account setup steps.

Four scopes cover the full flow:

  • people:read to resolve a worker to an hris_profile_id.
  • it-products:read to browse the catalog and read product variants.
  • it-orders:write to place the order.
  • it-orders:read to track the order.

The order is placed for a worker’s HRIS profile. For workers without an active Deel contract, the profile must include first name, last name, group, country of residence, and email address.

Every order ends in a shipment. Collect the full address the equipment ships to. See Delivery Coverage, Delivery Times, and Express Shipping for the countries Deel logistics operates in and available service tiers.

Resolve the worker’s HRIS profile

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

curl --request GET 'https://api.letsdeel.com/rest/people?search=Nina%20Doe' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

Example response:

{
  "data": [
    {
      "id": "9b9fc43a-a90c-4615-ac50-baf1e314b53e",
      "first_name": "Nina",
      "last_name": "Doe",
      "full_name": "Nina Doe",
      "emails": [
        {
          "type": "work",
          "value": "nina.doe@example.com"
        }
      ],
      "job_title": "Product Manager",
      "department": {
        "id": "5f8a2c1e-3b47-4e89-9f2c-8d1e3a4b5c6f",
        "name": "Product"
      },
      "hiring_status": "onboarding"
    }
  ]
}

Searching by name is one way to find the worker; use whichever filter fits your system. search matches on name, so confirm the match against emails[].value in your own code. The id field is the person’s hris_profile_id. The rest of the workflow uses it as destination.hris_profile_id in the order request.

Query the catalog

List the products available in the Deel IT catalog, filtered by the worker’s delivery country and any other criteria. This is the equivalent of choosing from the available devices for the worker’s country in the Deel app. Requires the it-products:read scope. See the List products in the catalog reference.

curl --request GET 'https://api.letsdeel.com/rest/it/products?country=GB&category=LAPTOP&acquisition_types=RENTAL&limit=20' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'X-Beta: true'

Use the query parameters to narrow the catalog:

  • country: ISO 3166 alpha-2 country code. Restricts results to products whose variants ship to this country.
  • category: Filter by one product category, such as LAPTOP or MONITOR.
  • acquisition_types: Restrict results to products offering at least one of PURCHASE, RENTAL, or REUSE.
  • stock_condition: NEW or REFURBISHED.
  • brands, operating_systems, keyboard_layouts: Filter by manufacturer, operating system, or keyboard layout. Repeat a parameter for OR semantics.
  • search: Case-insensitive match on product name or brand.
  • it_policy_ids: Restrict results to products approved by these IT policies, to see what workers on those policies can order.

Example response:

{
  "data": [
    {
      "id": "8e9a2b4c-1d5f-4c3e-9b7a-2f6d8c1e4a5b",
      "name": "MacBook Pro 16",
      "brand": "Apple",
      "images": [
        {
          "id": "b1c3d5e7-8a9b-4c2d-9e0f-1a2b3c4d5e6f",
          "url": "https://cdn.deel.com/products/mbp16-space-black.png"
        }
      ],
      "category": "LAPTOP"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJvZmZzZXQiOjIwLCJsaW1pdCI6MjB9",
  "total_count": 133
}

The response returns product metadata only: no variants, pricing, taxes, fees, or contract settings. Pick a product and use its id in the next step.

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 catalog.

Choose a variant and addons

Retrieve the product to see its variants and the addons you can attach to it. Pass the same country to restrict the variants to those that ship to the worker. Requires the it-products:read scope. See the Retrieve a product’s catalog details reference.

curl --request GET 'https://api.letsdeel.com/rest/it/products/8e9a2b4c-1d5f-4c3e-9b7a-2f6d8c1e4a5b?country=GB' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'X-Beta: true'

Example response:

{
  "data": {
    "id": "8e9a2b4c-1d5f-4c3e-9b7a-2f6d8c1e4a5b",
    "public_id": "PRD-8E9A2B4C",
    "name": "MacBook Pro 16",
    "brand": "Apple",
    "category": "LAPTOP",
    "description": "16-inch MacBook Pro with Apple M4 Pro chip.",
    "images": [
      {
        "id": "b1c3d5e7-8a9b-4c2d-9e0f-1a2b3c4d5e6f",
        "url": "https://cdn.deel.com/products/mbp16-space-black.png"
      }
    ],
    "variants": [
      {
        "id": "2f4e7ab1-9d3c-4b1f-9e34-6dfb0d6a12ab",
        "public_id": "VAR-2F4E7AB1",
        "sku": "MX2T3B/A",
        "size": null,
        "style": "Space Black",
        "operating_system": "MACOS",
        "keyboard_layout": "UK_ENGLISH_QWERTY",
        "image": {
          "id": "b1c3d5e7-8a9b-4c2d-9e0f-1a2b3c4d5e6f",
          "url": "https://cdn.deel.com/products/mbp16-space-black.png"
        },
        "allowed_acquisition_types": ["PURCHASE", "RENTAL"],
        "allowed_rental_terms": ["MONTH_12", "MONTH_24"],
        "available_countries": ["GB"]
      }
    ],
    "available_addons": [
      {
        "id": "5c1a7d3e-8b2f-4a6c-9e1d-3f5b7a8c9d0e",
        "name": "Device Management",
        "type": "SERVICE",
        "is_premium": false
      },
      {
        "id": "7d2b8e4f-9c3a-4b7d-8f2e-4a6c8b9d0e1f",
        "name": "Accidental Damage Protection",
        "type": "WARRANTY",
        "is_premium": true
      }
    ],
    "product_hardware_spec": {
      "product_category": "LAPTOP",
      "processor": "Apple M4 Pro",
      "memory_gb": 24,
      "storage_gb": 512,
      "storage_type": "SSD",
      "display_size": "16",
      "has_hdmi_port": true,
      "has_display_port": false,
      "has_usb_c_video_input": false,
      "usb_c_connections": 3
    }
  }
}

Pick the variant whose specifications match what the worker needs. Its id is the variant_id you pass in the order. Check allowed_acquisition_types and allowed_rental_terms to see which contract settings the variant supports. Each entry in available_addons has an id you can pass as an addon_id in the order, and a type of SERVICE or WARRANTY. You can attach at most one of each.

Place the order

Create the order for the worker. The order is created pre-approved, so it does not wait on an approval step. Requires the it-orders:write scope. See the Create an IT order reference.

Placing the order commits your organization to the equipment, addons, and fees shown in pricing_details. You can cancel the order only before its shipment is prepared.

Set destination.assign_to to USER and identify the worker with destination.hris_profile_id. For each device, pass the variant_id and its contract_setting:

  • acquisition_type: PURCHASE, RENTAL, or REUSE.
  • rental_term: MONTH_12 or MONTH_24. Required for rentals, ignored otherwise.
  • payment_schema: MONTHLY or UPFRONT. Required for rentals, ignored for purchases, which are always paid upfront.
  • addons: Required. Pass an empty array when you do not attach any addons. Each variant takes at most two addons: one service and one warranty. Each addon can also take its own payment_schema and, for service addons only, a duration_months.
curl --request POST 'https://api.letsdeel.com/rest/it/orders' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Beta: true' \
  --data '{
    "data": {
      "variants": [
        {
          "variant_id": "2f4e7ab1-9d3c-4b1f-9e34-6dfb0d6a12ab",
          "contract_setting": {
            "acquisition_type": "RENTAL",
            "rental_term": "MONTH_12",
            "payment_schema": "MONTHLY",
            "addons": [
              {
                "addon_id": "5c1a7d3e-8b2f-4a6c-9e1d-3f5b7a8c9d0e",
                "payment_schema": "MONTHLY",
                "duration_months": 12
              }
            ]
          }
        }
      ],
      "destination": {
        "assign_to": "USER",
        "hris_profile_id": "9b9fc43a-a90c-4615-ac50-baf1e314b53e",
        "delivery_address": {
          "line1": "10 Onboarding Street",
          "line2": "Floor 2",
          "city": "London",
          "state": "England",
          "post_code": "EC1A 1BB",
          "country": "GB",
          "phone_number": "+447700900123"
        }
      },
      "is_express_delivery_requested": false
    }
  }'

Provide the full delivery address in destination.delivery_address: line1, line2, city, state, post_code, and country, plus phone_number and delivery_instructions where needed. The schema only requires country, but the order needs a full valid address to ship.

is_express_delivery_requested is required. Set it to true to request express shipping, or false otherwise. Shipping costs and delivery times vary by country and by express shipping availability.

Example response:

{
  "data": {
    "id": "3b7e1c9a-4f2d-4e68-a1b5-9c0d2e7f8a43",
    "public_id": "ORD-3B7E1C9A",
    "status": "APPROVED",
    "created_at": "2026-10-12T09:49:01.000Z",
    "updated_at": "2026-10-12T09:49:01.000Z",
    "user": {
      "hris_profile_id": "9b9fc43a-a90c-4615-ac50-baf1e314b53e",
      "first_name": "Nina",
      "last_name": "Doe",
      "emails": ["nina.doe@example.com"]
    },
    "order_items": [
      {
        "id": "d4a8f2b6-1c3e-4795-8b0a-6e2f9d1c7a35",
        "created_at": "2026-10-12T09:49:01.000Z",
        "status": "PROCESSING",
        "is_approved": true,
        "is_express_delivery_requested": false,
        "product": {
          "id": "8e9a2b4c-1d5f-4c3e-9b7a-2f6d8c1e4a5b",
          "name": "MacBook Pro 16",
          "brand": "Apple",
          "category": "LAPTOP"
        },
        "pricing_details": {
          "acquisition_type": "RENTAL",
          "asset_price": {
            "amount": "1999.99",
            "currency": "GBP"
          },
          "storefront_fee": {
            "amount": "40.00",
            "currency": "GBP"
          }
        }
      }
    ],
    "delivery_address": {
      "id": "e8b5d0a3-72c9-4a14-9f6e-3d1c8b40a257",
      "type": "DELIVERY",
      "line1": "10 Onboarding Street",
      "line2": "Floor 2",
      "city": "London",
      "state": "England",
      "post_code": "EC1A 1BB",
      "country": "GB",
      "phone_number": "+447700900123",
      "delivery_instructions": null,
      "date_of_birth": null,
      "tax_id_number": null,
      "passport_number": null,
      "is_valid": true
    }
  }
}

The id is the order_id you use to track the order in the next step. A 201 Created response confirms the order was created, not that the device has been delivered.

Track the order to delivery

Fulfillment happens asynchronously. Track the order through to delivery by polling or by subscribing to webhooks.

Polling for the terminal state

Poll GET /rest/it/orders/{order_id} and watch the order status and each item’s status in order_items. Requires the it-orders:read scope.

curl --request GET 'https://api.letsdeel.com/rest/it/orders/3b7e1c9a-4f2d-4e68-a1b5-9c0d2e7f8a43' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

The response has the same shape as the Create an IT order response, and also includes the worker’s address under user. Item statuses only move forward, in this order: PLACED, PROCESSING, AWAITING_PAYMENT, READY_TO_SHIP, SHIPPED, COMPLETED. An item can also move to CANCELLED. Use this endpoint to check the delivery status of a specific worker’s device.

React to a webhook instead

If you would rather not poll, subscribe to the it-order.created and it-order.updated events. The it-order.updated payload reflects the order’s current state each time it changes. Filter incoming events on the order id you created, and check status and each item’s status in order_items.

Example it-order.updated payload:

{
  "data": {
    "meta": {
      "event_type": "it-order.updated",
      "event_type_id": "5dbb2bee-b647-4aa2-b979-1d646474d0ff",
      "organization_id": "54723d17-f023-4576-9a7c-1750cad66e76",
      "organization_name": "Acme Corporation",
      "tracking_id": "d09a72b0002191b65de3a453d177f1a7"
    },
    "resource": {
      "id": "3b7e1c9a-4f2d-4e68-a1b5-9c0d2e7f8a43",
      "public_id": "ORD-3B7E1C9A",
      "status": "APPROVED",
      "created_at": "2026-10-12T09:49:01.000Z",
      "updated_at": "2026-10-14T16:12:44.000Z",
      "user": {
        "hris_profile_id": "9b9fc43a-a90c-4615-ac50-baf1e314b53e",
        "first_name": "Nina",
        "last_name": "Doe",
        "emails": ["nina.doe@example.com"]
      },
      "order_items": [
        {
          "is_approved": true,
          "is_express_delivery_requested": false,
          "product": {
            "id": "8e9a2b4c-1d5f-4c3e-9b7a-2f6d8c1e4a5b",
            "name": "MacBook Pro 16",
            "brand": "Apple",
            "category": "LAPTOP"
          },
          "pricing_details": {
            "acquisition_type": "RENTAL",
            "asset_price": { "amount": "1999.99", "currency": "GBP" },
            "storefront_fee": { "amount": "40.00", "currency": "GBP" }
          },
          "status": "SHIPPED"
        }
      ]
    }
  },
  "timestamp": "2026-10-14T16:12:44.360Z"
}

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

To cancel an order before its shipment is prepared, see the Cancel an IT order reference.

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. The API does not prescribe any particular order, so 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

Query the catalog

Call GET /rest/it/products?country={country}&category={category} to see which products are available for the worker’s country.

3

Choose a variant

Call GET /rest/it/products/{product_id}?country={country} and apply your own selection logic to pick a variant and any addons.

4

Place the order

Call POST /rest/it/orders with the selected variant_id, its contract_setting, and the worker’s hris_profile_id.

5

Track the order

Watch the order status, either by polling GET /rest/it/orders/{order_id} or by subscribing to it-order.updated, then mark the task complete in your internal system.