Filtering
Look up an item, narrow a list with filters, and choose its order.
Lists take filters as query parameters. This page uses List items, which has the most. Every list's filters are on its reference page, and they all work the same way.
Look up one item
Use the parameter that matches what you have:
| You have | Send | Matches |
|---|---|---|
| A serial number from a label | serial_number | The whole serial number, ignoring case. |
| An NFC tag scanned by a reader | nfc_tag | The tag's id as scanned, in either byte order, ignoring case. |
| Part of a name or number | q | Text in the serial number, batch number, item name, product name, SKU name, part number or PO number, or a whole NFC tag id. At least 2 characters. |
The answer is always a list. A serial number is unique only within a product, so two items of different products can share one.
curl "https://api.scannable.io/v1/items?serial_number=21h0042871" \
-H "Authorization: Bearer $SCANNABLE_API_KEY"An empty data means no item in your organisation matches. If you already have the item's item_… or serial_… identifier, use Retrieve an item instead.
Archived items are left out of every search unless you send archived=true.
Filter the list
| Filter | Keeps the items… | Several values |
|---|---|---|
status | with any of these safety statuses, such as not_safe_overdue. | Yes |
label_id | with any of these labels. | Yes |
assigned_to | assigned to any of these members (member_…). | Yes |
product_id | of any of these products. | Yes |
sku_id | of any of these SKUs. | Yes |
folder_id | in any of these folders, or a folder inside one. | Yes |
next_inspection_before | due an inspection before this time. | No |
next_inspection_after | due an inspection at or after this time. | No |
expires_before | that expire before this time. | No |
archived | you have archived, with true. Leave it out for the rest. | No |
Send several values comma-separated, or repeat the parameter. These two requests are the same:
curl "https://api.scannable.io/v1/items?status=not_safe_failed,not_safe_overdue" \
-H "Authorization: Bearer $SCANNABLE_API_KEY"
curl "https://api.scannable.io/v1/items?status=not_safe_failed&status=not_safe_overdue" \
-H "Authorization: Bearer $SCANNABLE_API_KEY"A filter takes up to 50 values. Values within one filter widen the list: an item needs only one of them. Different filters narrow it: an item must pass every one. So status=not_safe_failed,not_safe_overdue&folder_id=folder_… lists the failed or overdue items in that folder.
Times are ISO 8601, such as 2026-11-30T23:59:59Z. Items with no due inspection or no expiry are left out of the date filters. To list the items overdue for inspection, send the current time as next_inspection_before.
A folder, label or member of another organisation matches nothing. An identifier with the wrong prefix, such as label_id=folder_…, returns 400. See Errors.
Sort the list
The list comes oldest created_at first. Send sort=next_inspection_at to get the items due soonest first, overdue ones included, and those with no due inspection last. So the first page of sort=next_inspection_at&next_inspection_before=<now> holds the most overdue items.
A next_cursor keeps its order. Send the same sort with it, as with the filters.
Get more with each item
By default an item in the list leaves out what Retrieve an item adds. Send include to add it:
include | Adds |
|---|---|
data_fields | Your organisation's own fields that have a value on the item. File fields are left out. |
inspection_frequencies | The inspection frequencies applied to the item, soonest due first. |
Send both as include=data_fields,inspection_frequencies. A list page with include then holds everything the single item does, which saves a call per item.