Import items from another system

For a one-off move from a spreadsheet, the app’s CSV import is quicker: it maps columns, shows a dry run and can re-import later. Use the API when the list lives in another system and you want to push it in code, or keep pushing new items as they appear. You need a read and write key.

1. Get your folder ids

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

[
  {
    "id": "01a143ac-c194-779f-9fc3-63562e38237d",
    "name": "Warehouse",
    "kind": "folder",
    "children": [
      { "id": "01a143ac-c1a6-71be-af84-01e7d8613eff", "name": "Bin 12", "kind": "folder", "children": [] }
    ]
  },
  { "id": "01a143ac-c1a9-702d-8e1e-be84cb15d910", "name": "Van 1", "kind": "vehicle", "children": [] }
]

Missing a place? Create it with POST /folders ({"name": "Van 3", "kind": "vehicle"}).

2. Create each item

curl -X POST https://api.itemtally.com/v1/items \
  -H "Authorization: Bearer $ITEMTALLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "7f1c2a4e-0b7d-4c55-9a51-2f0e8d3c6b10",
    "mode": "quantity",
    "name": "AA batteries",
    "quantity": 48,
    "minQuantity": 24,
    "unit": "pcs",
    "tags": ["consumable"]
  }'

{ "id": "7f1c2a4e-0b7d-4c55-9a51-2f0e8d3c6b10", "qr": "IT-000016" }

• mode is quantity for counted stock or unique for one physical thing (add its serial).
• The opening quantity becomes the item’s first logbook line.
• tags are names; new ones are created.
• customFields takes your custom field keys, from GET /custom-fields.
• The answer carries the item’s ItemTally QR value, ready for printing labels.

3. Attach the barcodes it already has

curl -X POST https://api.itemtally.com/v1/items/01a143af-c3af-75bc-9e6e-6ffb54a28485/codes \
  -H "Authorization: Bearer $ITEMTALLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "ean", "value": "3165140980227"}'

{ "id": "01a143b1-8388-716e-b9fa-bab018fdd9e6", "kind": "ean", "value": "3165140980227" }

A code can belong to one item only. A second attach answers 409 with the item that has it.

In JavaScript

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

// Your rows, each with a UUID you keep on your side as the link.
const rows = [
  { id: "0b6f3d2c-1a9e-4f87-b5c4-7d8e9f0a1b2c", mode: "quantity", name: "Nitrile gloves L", quantity: 200, minQuantity: 50, unit: "pcs" },
  { id: "5e4d3c2b-1a0f-4e9d-8c7b-6a5f4e3d2c1b", mode: "unique", name: "Hilti TE 30 hammer drill", serial: "HT30-55120", ean: "4058546230118" },
];

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

for (const { ean, ...item } of rows) {
  const res = await fetch(`${API}/items`, { method: "POST", headers, body: JSON.stringify(item) });
  const body = await res.json();
  if (!res.ok) {
    console.error(item.name, body.message);
    continue;
  }
  if (ean) {
    await fetch(`${API}/items/${body.id}/codes`, {
      method: "POST",
      headers,
      body: JSON.stringify({ kind: "ean", value: ean }),
    });
  }
  console.log(body.qr, item.name);
  await sleep(600); // stays under 120 writes a minute
}

Safe to re-run

Give every item an id (a UUID) and keep it next to the row in your system. If the import stops halfway and you run it again, items that already exist answer with what was created the first time, and nothing is duplicated. Attaching a barcode that’s already on the same item answers 409; you can ignore that one.

To change items later, PATCH /items/{id} with the fields that changed. Stock changes go through adjust, never the import.