Hand things over from your own tool

You run a helpdesk or an internal booking page, and when it approves a loan you want ItemTally to record it: who has the laser measure, and when it’s due back. You need a read and write key.

1. Find or add the person

curl https://api.itemtally.com/v1/people \
  -H "Authorization: Bearer $ITEMTALLY_KEY"

[
  { "id": "01a143ac-c1c8-7484-847b-683b064f7707", "name": "Petra S.", "email": null, "holdingCount": 1, "overdueCount": 0 }
]

Not there yet? Add them. With an email they get a receipt and reminders.

curl -X POST https://api.itemtally.com/v1/people \
  -H "Authorization: Bearer $ITEMTALLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sam Ortiz", "email": "[email protected]"}'

{ "email": "[email protected]", "id": "01a143b1-8312-763f-b9d9-d02ff83da2d1", "name": "Sam Ortiz" }

2. Hand it over

Pass one or more items, the person and an optional due date:

curl -X POST https://api.itemtally.com/v1/items/check-out \
  -H "Authorization: Bearer $ITEMTALLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personId": "01a143ac-c1c8-7484-847b-683b064f7707",
    "items": [{ "itemId": "01a143af-c3af-75bc-9e6e-6ffb54a28485" }],
    "dueAt": "2026-10-23T15:00:00Z",
    "note": "Kitchen survey"
  }'

{ "batchId": "4d20cdd3-a985-4a78-879c-8a3faf2188c7", "count": 1 }

If anything in the list is already out or reserved for those dates, nothing is handed over and you get a 409 that names it. Show the message to your user as it is:

{
  "code": "CONFLICT",
  "status": 409,
  "message": "Bosch GLM 50 laser measure is already with Petra S. Return it first.",
  "data": { "itemId": "01a143af-c3af-75bc-9e6e-6ffb54a28485" }
}

For quantity items, add qty: { "itemId": "…", "qty": 4 }.

3. Extend the due date

curl -X POST https://api.itemtally.com/v1/items/extend \
  -H "Authorization: Bearer $ITEMTALLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"itemId": "01a143af-c3af-75bc-9e6e-6ffb54a28485", "dueAt": "2026-10-30T15:00:00Z"}'

{ "dueAt": "2026-10-30T15:00:00.000Z", "itemId": "01a143af-c3af-75bc-9e6e-6ffb54a28485" }

4. Take it back

curl -X POST https://api.itemtally.com/v1/items/check-in \
  -H "Authorization: Bearer $ITEMTALLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"itemId": "01a143af-c3af-75bc-9e6e-6ffb54a28485", "note": "Back from site"}'

{ "ok": true }

Add "problem": "Lens cracked" to flag damage on the return line.

In JavaScript

const API = "https://api.itemtally.com/v1";
const headers = {
  Authorization: `Bearer ${process.env.ITEMTALLY_KEY}`,
  "Content-Type": "application/json",
};

// Hand items to a person. Returns null on success, or the sentence to show.
async function handOver(personId, itemIds, dueAt) {
  const res = await fetch(`${API}/items/check-out`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      personId,
      dueAt,
      items: itemIds.map((itemId) => ({ itemId, movementId: crypto.randomUUID() })),
    }),
  });
  if (res.ok) return null;
  const error = await res.json();
  if (res.status === 409) return error.message; // already out or reserved
  throw new Error(`${res.status} ${error.code}: ${error.message}`);
}

const problem = await handOver(
  "01a143ac-c1c8-7484-847b-683b064f7707",
  ["01a143af-c3af-75bc-9e6e-6ffb54a28485"],
  "2026-10-23T15:00:00Z"
);
console.log(problem ?? "Handed over");

Good to know

• Scan to pick. If your tool scans labels, turn the scanned value into an item id with GET /items/lookup?value=….
• Who’s holding what. GET /movements/out-now lists everything that’s out, soonest due first. GET /people/{id} shows one person’s things.
• Signatures. Items in a folder that requires a signature can’t be handed over by the API: the call answers 400 with data.reason set to signature_required. Hand those over in the app, where the person signs on screen.
• Whose name. An API hand-over is recorded in the logbook as done by the person who created the key.
• Hear about it. Subscribe to item.checked_out, item.checked_in and custody.overdue webhooks to update your tool when things change in the app.