List Items - Circuit Auction API

GET /datatable-items

Query Parameters

Parameter	Type	Description	Example
`range`	integer	Items per page	`?range=50`
`page`	integer	Page number	`?page=0`
`sort`	string	Sort field and direction	`?sort=lot`
`filter[sale]`	string	Sale ID	`?filter[sale]=456`
`filter[consignment]`	string	Consignment ID	`?filter[consignment]=234`
`filter[category]`	string	Category ID	`?filter[category]=10`
`filter[status]`	string	Item status (available, sold, unsold, passed, withdrawn)	`?filter[status]=sold`
`filter[lot]`	string	Lot number search	`?filter[lot]=1234`
`filter[description]`	string	Description search (regex)	`?filter[description]=vase`
`filter[estimate_low][value][from]`	number	Min low estimate	`?filter[estimate_low][value][from]=100`
`filter[estimate_low][value][to]`	number	Max low estimate	`?filter[estimate_low][value][to]=200`
`filter[estimate_high][value][from]`	number	Min high estimate	`?filter[estimate_high][value][from]=200`
`filter[estimate_high][value][to]`	number	Max high estimate	`?filter[estimate_high][value][to]=300`
`filter[hammer_price][value][from]`	number	Min hammer price	`?filter[hammer_price][value][from]=100`
`filter[hammer_price][value][to]`	number	Max hammer price	`?filter[hammer_price][value][to]=1000`
`filter[consignor_symbol]`	string	Consignment symbol search	`?filter[consignor_symbol]=A`
`fields`	string	Specific fields	`?fields=id,lot,description`

Fields Parameter

The fields parameter allows you to specify which fields should be returned in the response. This helps reduce response size and improve performance by only returning the data you need.

Default Response (No Fields Parameter)

If no fields parameter is provided, only basic information will be returned:

GET /api/v1.0/items-list?page=1&range=10&sale_id=309&sort=-lot

Default fields returned: display_id, lot, status

{
  "data": [
    {
      "display_id": "736620000191",
      "lot": "9191",
      "status": {
        "value": "new",
        "label": "New"
      }
    },
    {
      "display_id": "736620000190",
      "lot": "9190",
      "status": {
        "value": "new",
        "label": "New"
      }
    }
  ],
  "count": 6820,
  "self": {
    "title": "Self",
    "href": "https://test-hk.circuit.auction/en/api/v1.0/items-list"
  },
  "next": {
    "title": "Next",
    "href": "https://test-hk.circuit.auction/en/api/v1.0/items-list?page=2&range=10&sale_id=309&sort=-lot_number%2C-lot_letter"
  }
}

Custom Fields

To get additional data, pass a comma-separated list of field names using the fields parameter:

GET /api/v1.0/items-list?fields=id,lot,description,status,images&range=10&sale_id=309

Tip: Use the fields parameter to request only the data you need for better performance.

Available Fields

Field Name	Description
`id`	Item node ID
`display_id`	Display ID (configured in system settings)
`lot`	Combined lot number and letter
`lot_number`	Lot number only
`lot_letter`	Lot letter only
`temp_lot_number`	Temporary lot number
`description`	Item description/title
`opening_price`	Opening/starting price
`responsible_user`	Responsible clerk/user name
`item_type`	Type of item
`categories`	Category names (comma-separated)
`main_category_tid`	Main category term ID
`catalogue_part_name`	Catalogue part name
`tree_name`	Category tree name
`heading`	Heading level in catalog
`images`	Item images information
`status`	Item status (available, sold, unsold, etc.)
`sold_for`	Final selling price
`sold_status`	Sold status
`sale_title`	Sale title
`under_extension_status`	Extension status
`created`	Creation timestamp
`updated`	Last update timestamp
`consignment`	Consignment ID
`consignor_name`	Consignor full name
`consignment_owner_id`	Consignment owner ID
`consignment_id`	Consignment identifier
`consignor_reference_number`	Consignor reference number
`position_of_consignment`	Position within consignment
`catalogs`	Catalog information
`grouping_categories`	Grouping category names
`main_grouping_category_tid`	Main grouping category term ID
`symbols`	Item symbols (for philately)
`item_tags`	Item tags
`uuid`	Universal unique identifier

Example with Multiple Fields

GET /api/v1.0/datatable-items?fields=id,catalogue_part_name,display_id,lot,opening_price,responsible_user,tree_name,catalogs,item_type,description,images,status,sold_for,under_extension_status,created,updated&page=1&range=10&sale_id=309

Example Requests

GET /api/v1.0/datatable-items?filter[sale]=456&filter[status]=available&range=50&sort=lot

GET /api/v1.0/datatable-items?filter[sale]=456&filter[status]=sold&filter[hammer_price][value][from]=100&filter[hammer_price][value][to]=1000&sort=-hammer_price

GET /api/v1.0/datatable-items?filter[sale]=456&filter[category]=10&range=100

Response

{
  "data": [
    {
      "id": "345",
      "label": "Item #1234",
      "lot": "1234",
      "description": "Beautiful antique vase from the Ming Dynasty",
      "sale": {
        "id": "456",
        "label": "Summer Auction 2025"
      },
      "consignment": {
        "id": "234",
        "symbol": "A",
        "sub_symbol": "1"
      },
      "category": {
        "id": "10",
        "label": "Ceramics"
      },
      "estimate_low": "100.00",
      "estimate_high": "200.00",
      "reserve_price": "80.00",
      "hammer_price": "250.00",
      "status": "sold",
      "winner": {
        "id": "123",
        "label": "John Doe",
        "bidder_number": "12345"
      },
      "images": [
        {
          "id": "1001",
          "url": "https://.../files/item-images/vase-1.jpg",
          "thumbnail": "https://.../files/item-images/vase-1-thumb.jpg"
        }
      ],
      "dimensions": {
        "height": "30cm",
        "width": "15cm",
        "depth": "15cm"
      },
      "created": "2025-09-01T10:00:00Z",
      "updated": "2025-10-15T14:30:00Z"
    }
  ],
  "count": 250
}

List Items (DataTable)