Returns the serial numbers that match the given filters.

POST /inventory/serial-numbers/search

Group: Inventory › Serial Numbers · Operation ID: searchSerialNumbers

Every criterion is exact and criteria combine with AND. Send an empty filters object to return every serial number.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "v1" yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.

Request body

Required, application/json: searchSerialNumbersInput.

Field Type Required Description
filters object yes The filters to apply. A serial number must match every filter you send. Send an empty object to return all serial numbers.
filters.serialNumber string no Limits results to the serial number with this value. The match is exact.
filters.manufacturerSerialNumber string no Limits results to serial numbers with this manufacturer serial number. The match is exact.
filters.itemId string no Limits results to serial numbers of this item. An identifier that is not an item's matches no serial number.
filters.locationId string no Limits results to serial numbers in this warehouse.
filters.active boolean no Limits results to serial numbers with the given active value.
filters.inStock boolean no Limits results to serial numbers on hand when true, and to those already gone when false.
filters.isSold boolean no Limits results to serial numbers with the given isSold value.
filters.expiringBefore string (date) no Limits results to serial numbers expiring on or before this date. Format YYYY-MM-DD.
filters.expiringAfter string (date) no Limits results to serial numbers expiring on or after this date. Format YYYY-MM-DD.
filters.modifiedSince string (date-time) no Limits results to serial numbers changed on or after this time. Format YYYY-MM-DDTHH:mm:ss.sssZ.
page object no The pagination controls. Omit for the first page.
page.cursor string no The cursor from the previous response's pagination.nextCursor. Omit for the first page.
page.size number no The number of serial numbers per page. Defaults to 50. A value above 200 is treated as 200, not rejected.

Example:

{
  "filters": {
    "itemId": "afb4492d-52fc-44c5-ab10-71ad4a615496",
    "inStock": true
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}

Response

200 Success

Under data (searchSerialNumbersOutput):

Field Type Required Description
items array of object yes The serial numbers on this page, oldest first. An empty array when nothing matches.
items[].id string yes The unique identifier for the serial number.
items[].serialNumber string no The serial number assigned to the unit when it was received. It cannot be changed.
items[].manufacturerSerialNumber string no The manufacturer's own serial number for the unit, where it differs from the assigned serial number.
items[].itemId string no The unique identifier for the item this unit is of. See id on GET inventory/items/:id.
items[].itemCode string no The code of that item.
items[].itemName string no The display name of that item.
items[].locationId string no The unique identifier for the warehouse holding the unit. See id on GET inventory/warehouses/:id.
items[].locationCode string no The code of that warehouse.
items[].locationName string no The display name of that warehouse.
items[].entityId string no The unique identifier for the legal entity the unit belongs to. See id on GET base/entities.
items[].inStock string (decimal) no 1 while the unit is on hand, 0 once it has gone.
items[].isSold boolean no Whether the unit has been sold.
items[].cost string (decimal) no The value the unit is carried at, in the currency named by currency.
items[].originalCost string (decimal) no The value the unit was carried at when it arrived, in the currency named by currency.
items[].afterSaleCost string (decimal) no The value of the unit after it was sold, in the currency named by currency.
items[].currency string no The currency the cost fields are stated in. Format ISO 4217, for example 'USD'.
items[].lastCostChangeDate string (date) no The date the unit's cost last changed. Format YYYY-MM-DD.
items[].expirationDate string (date) no The date the unit expires. Format YYYY-MM-DD.
items[].entryDate string (date) no The date the unit entered the warehouse. Format YYYY-MM-DD.
items[].active boolean no Whether the serial number can be selected on new documents.
items[].createdDate string (date-time) no The date and time the serial number record was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lastModifiedDate string (date-time) no The date and time the serial number record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
pagination object yes The pagination cursor for this page.
pagination.nextCursor string no The cursor for the next page. Pass it as page.cursor. Absent on the last page.
pagination.hasMore boolean no True when more serial numbers remain beyond this page.

Statuses