Chain of Custody Timeline

Fetch the custody timeline for a device by IMEI and/or serial.

GET

/api/v1/chain-of-custody/timeline

Description

Returns merged custody timelines for the device across repair, ITAD, remote recovery, and deployment orders (same information as the platform Chain of Custody sidebar). Provide at least one of imei or serial. Requires permission chain-of-custody.read. Order types: repair, itad, recovery, deployment. On recovery timelines, order_number is the linked remote recovery order number and recovery_number is the campaign employee recovery number. itad timelines are ITAD orders not linked to a recovery. On ITAD/recovery timelines, the "Assessment in Progress" event may include a sub_events array with a "DLR SENT" entry when a Device Locked Report was sent for that order.

Request

Headers

Header	Value	Required
Authorization	Bearer <access_token>	Yes
Content-Type	application/json	Yes

Query Parameters

Parameter	Type	Required	Description
imei	string	Conditional	Device IMEI. Provide imei and/or serial (at least one required).
serial	string	Conditional	Device serial number. Provide imei and/or serial (at least one required).

Response

Field	Type	Description
serial	string	Resolved serial number.
imei	string	Resolved IMEI.
timelines	array	Custody timelines across related orders.
timelines[].order_type	string	Order type string enum: repair, itad, recovery, deployment.
timelines[].recovery_number	string	Present on recovery timelines: campaign employee recovery number. Omitted for repair, ITAD, and deployment. Distinct from order_number (the linked remote recovery order).
timelines[].order_number	string	Order number for this timeline. For recovery, the linked remote recovery order number; for itad, the ITAD order number; for repair / deployment, the repair or deployment order number.
timelines[].events	array	Chronological custody events.
timelines[].events[].occurred_at	string	Event timestamp (ISO-8601 UTC).
timelines[].events[].status	string	Event status label.
timelines[].events[].order_number	string	Order number for this event when applicable.
timelines[].events[].performed_by	string	Who performed the action (order placer, warehouse, QA user, etc.). Omitted when not applicable.
timelines[].events[].received_from	string	Who the device was received from (e.g. employee or order contact).
timelines[].events[].delivered_to	string	Deployment: recipient name when the device was delivered.
timelines[].events[].recovery_number	string	Recovery Initiated: campaign employee recovery number.
timelines[].events[].services	array	Repair: service names performed on the device.
timelines[].events[].approved_price	number	Assessment Completed: approved device value.
timelines[].events[].asset_disposition	string	Assessment Completed: disposition / device status label.
timelines[].events[].erasure_started_at	string	Data Erasure: erase start time (ISO-8601 UTC).
timelines[].events[].erasure_ended_at	string	Data Erasure: erase end time (ISO-8601 UTC).
timelines[].events[].erasure_type	string	Data Erasure: erase method label (e.g. Secure Erase (NIST)).
timelines[].events[].erasure_total_time	string	Data Erasure: total erase duration (e.g. 00:30:00).
timelines[].events[].sub_events	array	Nested sub-events under a parent status. Today only on ITAD/recovery "Assessment in Progress": when a Device Locked Report (DLR) was sent, contains one event with status "DLR SENT". Otherwise omitted or an empty array.
timelines[].events[].sub_events[].occurred_at	string	Sub-event timestamp (ISO-8601 UTC). For DLR SENT, when the DLR was recorded.
timelines[].events[].sub_events[].status	string	Sub-event status label (currently "DLR SENT").

Related Endpoints

Chain of Custody List

List custody device records

Did this page help you?

Request

curl -X GET https://uat.unduit.com/api-exposed/api/v1/chain-of-custody/timeline \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Success Response

{
  "serial": "C02XK1ABCDEF",
  "imei": "356938035643809",
  "timelines": [
    {
      "order_type": "recovery",
      "recovery_number": "1757235600374477",
      "order_number": "174859997627703",
      "events": [
        {
          "occurred_at": "2025-09-07T09:00:00.000Z",
          "status": "Recovery Initiated",
          "recovery_number": "1757235600374477"
        },
        {
          "occurred_at": "2025-09-10T14:22:00.000Z",
          "status": "Device Received",
          "received_from": "Alex Rivera",
          "performed_by": "Unduit Warehouse"
        },
        {
          "occurred_at": "2025-09-12T09:00:00.000Z",
          "status": "Assessment in Progress",
          "order_number": "174859997627703"
        },
        {
          "occurred_at": "2025-09-14T16:45:00.000Z",
          "status": "Assessment Completed",
          "asset_disposition": "Reuse"
        }
      ]
    },
    {
      "order_type": "deployment",
      "order_number": "17829016188421",
      "events": [
        {
          "occurred_at": "2025-11-03T10:15:00.000Z",
          "status": "Deployment Order Placed",
          "order_number": "17829016188421",
          "performed_by": "Jane Doe"
        },
        {
          "occurred_at": "2025-11-05T16:30:00.000Z",
          "status": "On the Way",
          "order_number": "17829016188421"
        },
        {
          "occurred_at": "2025-11-07T18:05:00.000Z",
          "status": "Device Delivered",
          "delivered_to": "Jordan Lee"
        }
      ]
    },
    {
      "order_type": "itad",
      "order_number": "17829016177210",
      "events": [
        {
          "occurred_at": "2026-06-01T10:00:00.000Z",
          "status": "ITAD Order Placed",
          "order_number": "17829016177210",
          "performed_by": "Jane Doe"
        },
        {
          "occurred_at": "2026-06-03T13:20:00.000Z",
          "status": "Device Received",
          "performed_by": "Unduit Warehouse"
        },
        {
          "occurred_at": "2026-06-05T14:00:00.000Z",
          "status": "Assessment in Progress",
          "order_number": "17829016177210",
          "sub_events": [
            {
              "occurred_at": "2026-06-06T09:15:00.000Z",
              "status": "DLR SENT"
            }
          ]
        },
        {
          "occurred_at": "2026-06-07T11:00:00.000Z",
          "status": "Data Erasure",
          "erasure_started_at": "2026-06-07T11:00:00.000Z",
          "erasure_ended_at": "2026-06-07T11:30:00.000Z",
          "erasure_type": "Secure Erase (NIST 800-88 rev1 Purge)",
          "erasure_total_time": "30 Minutes"
        },
        {
          "occurred_at": "2026-06-08T16:00:00.000Z",
          "status": "Assessment Completed",
          "approved_price": 120,
          "asset_disposition": "Recycle"
        }
      ]
    }
  ]
}

Error Responses

400 Missing Identifier

{
  "success": false,
  "message": "Provide at least one of imei or serial to look up the device timeline."
}

404 Not Found

{
  "success": false,
  "message": "No custody timeline found for the given imei/serial."
}

401 Unauthorized

{
  "message": "Access denied: No token provided."
}