Orphan Tracker docs

When a carrier (AT&T being our primary integration) ships a wholesale lot to a refurbisher, they include an xlsx file listing the unlock status for every IMEI. Statuses we've seen:

• UNLOCKED — carrier confirmed the device is permanently unlocked. Ready for resale.
• UNLOCK_NOT_SENT — the carrier's unlock command was queued but never delivered. These are the orphans.
• NOT_ELIGIBLE — fraud / unpaid balance / financing — cannot be unlocked.
• PENDING — request submitted, not yet processed.

Orphans (UNLOCK_NOT_SENT) typically represent 10–30% of a lot. AT&T offers no second-attempt API, so refurbishers have to unlock them on-device or eat the loss.

AT&T sends a 15-column schema. Common filename patterns we've normalized:

<ORDER_ID>_unlocked_imei_data.xlsx
<ORDER_ID>_unlocked_imei_data (1).xlsx
<DATE>_FRM_<LOT>_imei_status.xlsx
<LOT>_imei_unlock_status.xlsx

Column values vary by lot (make/model/invoice fields aren't standardized) but the schema is consistent. Orphan Tracker normalizes on import.

Drag the xlsx onto the upload zone in the dashboard, or POST it to POST /api/orphans/import with multipart/form-data:

curl -X POST https://kakel.io/api/orphans/import \
  -H "Authorization: Bearer <api_key>" \
  -F "file=@300250857_unlocked_imei_data.xlsx" \
  -F "lot_id=300250857"

The server parses, normalizes, deduplicates against existing records (matching on IMEI + order_id), and returns:

{
  "imported": 234,
  "duplicates": 12,
  "by_status": {
    "UNLOCKED": 167,
    "UNLOCK_NOT_SENT": 58,
    "NOT_ELIGIBLE": 9
  }
}

Each orphan gets a row in the queue with: IMEI, model_canonical, lot_id, assigned_tech, status (NEW / IN_PROGRESS / UNLOCKED / BLOCKED / SOLD_AS_LOCKED). Techs claim orphans from the queue; outcomes are timestamped.

When a tech opens a device in PhoneToolkit (with Cloud Sync on Pro Plus), the outcome propagates back to the queue automatically — no double-entry.

Export the current state of a lot back to xlsx for handing to your accounting team or carrier rebate-claim process:

GET /api/orphans/export?lot_id=300250857
→ <302 Redirect to signed S3 URL of reconciled.xlsx>

Output includes the original 15 columns plus 3 new ones: KAKEL_status, KAKEL_unlocked_at, KAKEL_tech.