# Create

Creates a new item or folder.

- type is "item" for a trackable inventory object, or "folder" for a container.
- parent_id places it inside a folder. Omit it or pass null for the root level.
- To attach custom field values, call GET /custom_fields first to discover valid
  custom_attribute_id values.

Endpoint: POST /api/v1/items
Security: BearerAuth

## Request fields (application/json):

  - `name` (string, required)
    Name of the item or folder. Max 190 characters.
    Example: "Standing Desk"

  - `price` (number,null)
    Unit price.
    Example: 599

  - `quantity` (number,null)
    How many you have. For items measured in something other than units, see measured_quantity.
    Example: 4

  - `min_quantity` (number,null)
    Minimum level. When quantity reaches this, a Quantity alert on the item can notify your team. See [Track Stock Levels](/track-stock-levels).
    Example: 2

  - `notes` (string,null)
    Free-text notes.

  - `parent_id` (number,null)
    ID of the folder this lives in. Pass null (or omit) to place it at the top level.
    Example: 10

  - `type` (string, required)
    Whether this is a trackable item or a folder that contains other things.
    Enum: "item", "folder"

  - `label_url` (string,null)
    Value encoded in the item's primary QR code or barcode.
    Example: "AB123AB45"

  - `label_url_type` (string,null)
    Symbology of the linked QR code or barcode. Use com.sortly.sortlyLabel for labels Sortly generates, or com.sortly.textEntry for a manually typed value.
    Enum: "org.gs1.UPC-E", "org.iso.Code39", "org.iso.Code39Mod43", "org.gs1.EAN-13", "org.gs1.EAN-8", "com.intermec.Code93", "org.iso.Code128", "org.iso.PDF417", "org.iso.Aztec", "org.iso.QRCode", "org.ansi.Interleaved2of5", "org.iso.DataMatrix", "com.sortly.textEntry", null

  - `label_url_extra` (string,null)
    Value encoded in the item's secondary QR code or barcode.
    Example: "9780066620992"

  - `label_url_extra_type` (string,null)
    Symbology of the linked QR code or barcode. Use com.sortly.sortlyLabel for labels Sortly generates, or com.sortly.textEntry for a manually typed value.
    Enum: "org.gs1.UPC-E", "org.iso.Code39", "org.iso.Code39Mod43", "org.gs1.EAN-13", "org.gs1.EAN-8", "com.intermec.Code93", "org.iso.Code128", "org.iso.PDF417", "org.iso.Aztec", "org.iso.QRCode", "org.ansi.Interleaved2of5", "org.iso.DataMatrix", "com.sortly.textEntry", null

  - `tags` (array)
    Tags on this item. Tags organize inventory across folders: by brand, colour, condition or status. Accepted on writes and returned on reads.

  - `tags.name` (string, required)
    Tag name.
    Example: "fragile"

  - `custom_attribute_values` (array)
    Values for your account's custom fields. Call GET /custom_fields first to get each field's custom_attribute_id.

  - `custom_attribute_values.value` (string,null)
    The value to store for this custom field. Send null to clear it.
    Example: "2026-12-31"

  - `custom_attribute_values.custom_attribute_id` (number, required)
    ID of the custom field. Call GET /custom_fields to look these up.
    Example: 363882

  - `custom_attribute_values.scanner_code_type` (string)
    Symbology for a scanner-type custom field value. Required only when the custom field is of scanner type.
    Enum: "org.gs1.UPC-E", "org.iso.Code39", "org.iso.Code39Mod43", "org.gs1.EAN-13", "org.gs1.EAN-8", "com.intermec.Code93", "org.iso.Code128", "org.iso.PDF417", "org.iso.Aztec", "org.iso.QRCode", "org.ansi.Interleaved2of5", "org.iso.DataMatrix"

  - `custom_attribute_values.attribute_value` (string)
    Legacy alias for value. Still accepted; use value instead.

  - `photo_ids` (array)
    IDs of photos that already exist in your account. To upload a new file instead, send it as photos[] with multipart/form-data.

  - `measured_quantity` (object)
    Quantity for things you don't count in units: cable by the foot, paint by the gallon, sand by the pound.

  - `measured_quantity.value` (number)
    The measured amount.
    Example: 1.5

  - `measured_quantity.type` (string)
    Which kind of measurement this is. Settable on create only: on an update it is ignored and the item keeps the unit it was created with.
    Enum: "weight", "length", "volume", "area", "count"

  - `measured_quantity.name` (string)
    The unit itself. Valid values depend on type. Weight: lbs, g, kg, oz; length: yd, cm, ft, in, m; volume: gal, ml, l, ft3, in3; area: sq cm, ft2, in2; count: units. Call GET /units for what your account supports. Like type, this is settable on create only.
    Enum: "lbs", "g", "kg", "oz", "yd", "cm", "ft", "in", "m", "gal", "ml", "l", "ft3", "in3", "ft2", "in2", "units"

  - `option_value_ids` (array)
    For a variant item, the option values that identify which combination this is (for example the Black and XL option IDs). Required together with item_group_id.

  - `item_group_id` (string)
    The item group this variant belongs to. Required together with option_value_ids.

## Response 200 fields (application/json):

  - `data` (object)
    An item or folder as sent to create and as returned by every read. name and type are required.

  - `data.id` (number)
    Sortly's numeric ID for this item or folder. Assigned on creation.

  - `data.name` (string, required)
    Name of the item or folder. Max 190 characters.
    Example: "Standing Desk"

  - `data.price` (number,null)
    Unit price.
    Example: 599

  - `data.quantity` (number,null)
    How many you have. For items measured in something other than units, see measured_quantity.
    Example: 4

  - `data.min_quantity` (number,null)
    Minimum level. When quantity reaches this, a Quantity alert on the item can notify your team. See [Track Stock Levels](/track-stock-levels).
    Example: 2

  - `data.notes` (string,null)
    Free-text notes.

  - `data.parent_id` (number,null)
    ID of the folder this lives in. Pass null (or omit) to place it at the top level.
    Example: 10

  - `data.type` (string, required)
    Whether this is a trackable item or a folder that contains other things.
    Enum: "item", "folder"

  - `data.sid` (string)
    Sortly ID, a short human-readable code such as S01QSR0001 that QR labels and barcodes point at. Assigned by Sortly.
    Example: "S01QSR0001"

  - `data.created_at` (string)
    When this item or folder was created.

  - `data.updated_at` (string)
    When it was last changed. Use this for incremental syncs. See [Sync Inventory](/sync-inventory).

  - `data.label_url` (string,null)
    Value encoded in the item's primary QR code or barcode.
    Example: "AB123AB45"

  - `data.label_url_type` (string,null)
    Symbology of the linked QR code or barcode. Use com.sortly.sortlyLabel for labels Sortly generates, or com.sortly.textEntry for a manually typed value.
    Enum: "org.gs1.UPC-E", "org.iso.Code39", "org.iso.Code39Mod43", "org.gs1.EAN-13", "org.gs1.EAN-8", "com.intermec.Code93", "org.iso.Code128", "org.iso.PDF417", "org.iso.Aztec", "org.iso.QRCode", "org.ansi.Interleaved2of5", "org.iso.DataMatrix", "com.sortly.textEntry", null

  - `data.label_url_extra` (string,null)
    Value encoded in the item's secondary QR code or barcode.
    Example: "9780066620992"

  - `data.label_url_extra_type` (string,null)
    Symbology of the linked QR code or barcode. Use com.sortly.sortlyLabel for labels Sortly generates, or com.sortly.textEntry for a manually typed value.
    Enum: "org.gs1.UPC-E", "org.iso.Code39", "org.iso.Code39Mod43", "org.gs1.EAN-13", "org.gs1.EAN-8", "com.intermec.Code93", "org.iso.Code128", "org.iso.PDF417", "org.iso.Aztec", "org.iso.QRCode", "org.ansi.Interleaved2of5", "org.iso.DataMatrix", "com.sortly.textEntry", null

  - `data.tag_names` (array)
    Tag names as plain strings. Returned on reads for convenience; prefer tags when writing.
    Example: ["fragile"]

  - `data.tags` (array)
    Tags on this item. Tags organize inventory across folders: by brand, colour, condition or status. Accepted on writes and returned on reads.

  - `data.tags.name` (string, required)
    Tag name.
    Example: "fragile"

  - `data.custom_attribute_values` (array)
    Values for your account's custom fields. Call GET /custom_fields first to get each field's custom_attribute_id.

  - `data.custom_attribute_values.value` (string,null)
    The value to store for this custom field. Send null to clear it.
    Example: "2026-12-31"

  - `data.custom_attribute_values.custom_attribute_name` (string)
    Name of the custom field. Returned on reads for convenience.

  - `data.custom_attribute_values.custom_attribute_id` (number, required)
    ID of the custom field. Call GET /custom_fields to look these up.
    Example: 363882

  - `data.custom_attribute_values.scanner_code_type` (string)
    Symbology for a scanner-type custom field value. Required only when the custom field is of scanner type.
    Enum: "org.gs1.UPC-E", "org.iso.Code39", "org.iso.Code39Mod43", "org.gs1.EAN-13", "org.gs1.EAN-8", "com.intermec.Code93", "org.iso.Code128", "org.iso.PDF417", "org.iso.Aztec", "org.iso.QRCode", "org.ansi.Interleaved2of5", "org.iso.DataMatrix"

  - `data.custom_attribute_values.attribute_value` (string)
    Legacy alias for value. Still accepted; use value instead.

  - `data.photo_ids` (array)
    IDs of photos that already exist in your account. To upload a new file instead, send it as photos[] with multipart/form-data.

  - `data.photos` (array)
    Photos attached to this item. Attach one that already exists with photo_ids, or upload a new file as photos[] with multipart/form-data.

  - `data.photos.id` (number)
    Photo ID. Pass this in photo_ids to attach the photo.

  - `data.photos.name` (string)
    Original filename.

  - `data.photos.url` (string)
    Publicly accessible image URL.

  - `data.measured_quantity` (object)
    Quantity for things you don't count in units: cable by the foot, paint by the gallon, sand by the pound.

  - `data.measured_quantity.value` (number)
    The measured amount.
    Example: 1.5

  - `data.measured_quantity.type` (string)
    Which kind of measurement this is. Settable on create only: on an update it is ignored and the item keeps the unit it was created with.
    Enum: "weight", "length", "volume", "area", "count"

  - `data.measured_quantity.name` (string)
    The unit itself. Valid values depend on type. Weight: lbs, g, kg, oz; length: yd, cm, ft, in, m; volume: gal, ml, l, ft3, in3; area: sq cm, ft2, in2; count: units. Call GET /units for what your account supports. Like type, this is settable on create only.
    Enum: "lbs", "g", "kg", "oz", "yd", "cm", "ft", "in", "m", "gal", "ml", "l", "ft3", "in3", "ft2", "in2", "units"

  - `data.measured_quantity.scale` (number)
    Decimal places used when displaying the value. Sortly takes this from the unit itself and ignores anything you send, on create and on update, so treat it as read-only. GET /units reports the scale each unit uses.
    Example: 4

  - `data.option_value_ids` (array)
    For a variant item, the option values that identify which combination this is (for example the Black and XL option IDs). Required together with item_group_id.

  - `data.item_group_id` (string)
    The item group this variant belongs to. Required together with option_value_ids.

## Response 400 fields (application/json):

  - `message` (string)

## Response 401 fields (application/json):

  - `message` (string)

## Response 422 fields (application/json):

  - `message` (string)

## Response 429 fields (application/json):

  - `message` (string)