Create Item

Create a new auction item/lot with descriptions, images, pricing, and technical details.

Sale Context Required

Items require a sale context. Include sale_id parameter in the query string.

POST /datatable-items?sale_id={sale_id}
Basic Information
Field Type Description
subtitle string Item subtitle
published boolean Publication status (0 or 1)
type string Item type
collectible_type integer Collectible type term ID
grade string Item grade/condition
consignment integer Consignment node ID (required)
uuid string Unique identifier
year integer Year of item
country integer/string Country term ID or label
Descriptions & Content
Field Type Description
description string Main item description (HTML)
footer string Footer text
caption string Item caption
literature string Literature references
essay string Essay/detailed description
provenance string Provenance information
ex string Ex collection information
Organization & Categorization
Field Type Description
categories array Array of category term IDs or labels
destinations array Array of destination term IDs or labels
search_tags array Array of search tag term IDs or labels
catalogue_parts array Array of catalogue part term IDs or labels
postal_thematics array Array of postal thematic term IDs or labels
symbols array Array of symbol term IDs or labels
sub_symbol array Array of sub-symbol term IDs or labels
grouping_category array Array of grouping category term IDs or labels
topics array Array of topic term IDs or labels
tags array Array of tag term IDs or labels
mediums array Array of medium term IDs or labels
Pricing & Bidding
Field Type Description
opening_price integer Opening bid price (in cents)
minimum_price integer Minimum acceptable price (in cents)
buy_now_price integer Buy now price (in cents)
buy_now_setting string Buy now configuration
estimate_low integer Low estimate (in cents)
estimate_high integer High estimate (in cents)
estimate_internal integer Internal estimate (in cents)
retail_price integer Retail price (in cents)
reserve_price integer Reserve price (in cents)
reserve_type string Reserve type setting
Images & Media
Field Type Description
images array Array of file IDs (optimized - doesn't resave if unchanged)
video_url string Video URL
pdf_url string PDF document URL
certificate_link string Certificate/authentication link
reference_link string Reference link
Technical Details
Field Type Description
catalogs array Catalog references (multifield). See structure below.
dimensions array Dimensions and packaging (multifield). See structure below.
product_tax_code string Product tax code
harmonized_code string Harmonized tariff code
signed_locations string Signature locations
art_work_type string Artwork type classification
Lot & Positioning
Field Type Description
lot_number integer Lot number
lot_letter string Lot letter suffix
position_of_consignment integer Position within consignment (unsigned)
start_lot_numbering_at integer Starting lot number
Additional Information
Field Type Description
shipping_id integer Shipping ID
post_sale boolean Include in post-sale processing
consignor_reference_number string Consignor's reference number
responsible_user array Array of responsible user IDs
public_message string Public message about item
auctioneer_notes string Internal auctioneer notes
additional_charges array Additional charges (multifield)
dont_pay_consignor_note string Note for not paying consignor
hide_sold_information boolean Hide sold information from public
printing_options string Printing options for catalog
Item History Fields (Creates Item History Records)

The following fields create or update Item History records rather than directly updating the item:

Field Type Description
field_consignor_price integer Price to pay consignor (in cents)
field_dont_pay_consignor boolean Don't pay consignor flag
field_sold_agent integer Selling agent user ID
field_sold_for_amount integer Sold for amount (in cents)
field_sold_to_bidder_id integer Bidder ID who purchased
field_bidder_alias string Bidder alias/paddle number
field_sold_status string Sold status
field_under_extension_status string Extension status
field_winner_bidder integer Winning bidder ID
field_withdrawn boolean Withdrawn from auction
Catalogs Structure (Multifield)
{
  "catalogs": [
    {
      "catalog_number": "S-123",
      "catalog_name": "Scott Standard Postage Stamp Catalogue",
      "ordering_number": 1,
      "catalog_value": 15000
    }
  ]
}
Dimensions Structure (Multifield)
{
  "dimensions": [
    {
      "number_on_box": "BOX-001",
      "height": 12.5,
      "width": 10.0,
      "depth": 3.5,
      "weight": 2.5,
      "type": "framed",
      "packed_date": 1695945600000
    }
  ]
}
Example Request - Basic Item
POST /api/v1.0/datatable-items?sale_id=123
{
  "subtitle": "Rare 1920s Vintage Stamp Collection",
  "consignment": 789,
  "published": 1,
  "description": "
Exceptional collection of 1920s European stamps in mint condition.
",
  "categories": ["Stamps", "European"],
  "opening_price": 50000,
  "estimate_low": 75000,
  "estimate_high": 125000,
  "lot_number": 45
}
Example Request - Complete Item with Details
{
  "subtitle": "Original Picasso Lithograph - Signed",
  "consignment": 999,
  "published": 1,
  "type": "artwork",
  "collectible_type": 5,
  "grade": "Excellent",
  "year": 1965,
  "country": "France",
  "description": "
Authentic Picasso lithograph from the Blue Period series.
",
  "provenance": "Private collection, Paris. Acquired 1967.",
  "ex": "Ex collection: Museum of Modern Art",
  "literature": "Catalogued in Bloch 1234",
  "categories": ["Art", "Prints"],
  "mediums": ["Lithograph"],
  "opening_price": 500000,
  "minimum_price": 450000,
  "estimate_low": 750000,
  "estimate_high": 1000000,
  "reserve_price": 600000,
  "reserve_type": "fixed",
  "lot_number": 150,
  "images": [12345, 12346, 12347],
  "certificate_link": "https://example.com/cert/12345",
  "dimensions": [
    {
      "height": 24.0,
      "width": 18.0,
      "type": "framed",
      "weight": 5.5
    }
  ],
  "catalogs": [
    {
      "catalog_number": "B-1234",
      "catalog_name": "Bloch Catalogue Raisonné",
      "catalog_value": 1200000
    }
  ],
  "signed_locations": "Lower right corner",
  "art_work_type": "print",
  "responsible_user": [10],
  "auctioneer_notes": "Handle with white gloves only"
}
Response
{
  "data": [{
    "id": "5678",
    "display_id": "150",
    "subtitle": "Rare 1920s Vintage Stamp Collection",
    "published": true,
    "lot": "45",
    "consignment": {
      "id": "789",
      "label": "CON-2025-001"
    },
    "opening_price": 50000,
    "estimate_low": 75000,
    "estimate_high": 125000,
    "current_price": 50000,
    "status": {
      "value": "active",
      "label": "Active"
    },
    "created": "2025-12-31T10:00:00Z",
    "updated": "2025-12-31T10:00:00Z"
  }]
}
Notes
  • Items require a sale_id parameter (sale context)
  • All monetary values are in cents
  • Dates are in milliseconds (JavaScript timestamps)
  • Taxonomy terms can be sent as IDs (integers) or labels (strings)
  • images field accepts array of file IDs - optimized to not resave if unchanged
  • Item History fields create separate item_history nodes during POST/PATCH
  • Latest Item History is promoted and values are fetched from it on GET
  • PATCH with only Item History fields skips parent class validation
  • position_of_consignment is cast to unsigned integer
  • Multifield arrays allow multiple entries for catalogs and dimensions
Read-Only Fields

The following fields are calculated and cannot be set during creation:

Back to Items Back to API Home