Documentation > Resources > Sales

Sales API

Sales and Auctions are available at the sales endpoint.

Retrieving Sales

Users can retrieve sales by following the sales link from root.

curl -v "" -H "X-Access-Token:..."

This endpoint accepts the following parameters.

Name Value
live Boolean- filter live auctions only
is_auction Boolean- filter auctions only
published Boolean- limit to published sales

Only authorized users/applications may access unpublished sales=

The response is a paginated result with embedded sales.

  "total_count" : 1,
  "_links" : {
    "self" : {
      "href" : ""
    "next" : {
      "href" : ""
  "_embedded" : {
    "sales" : [

Retrieving a Sale

Users can retrieve a specific sale by ID by rendering the "sale" link template from root.

curl -v "{id}" -H "X-XAPP-Token:..."

Sale JSON Format

Key Description
id Unique id.
slug Unique slug.
auction_state The state of the sale if it is an auction (otherwise nil)
name The name of the sale.
is_preliminary Bidding continues at Sale event after online auction close
is_auction Whether or not the sale is an auction.
is_live_integration Whether auction will continue in live auction integration
start_at When the sale starts.
end_at When the sale ends.
live_start_at When the live sale starts.
registration_ends_at When the sale registration closes
published Whether sale is available for public consumption.
has_buyers_premium Whether sale lots are charged a buyer's premium
created_at Timestamp of when the record was created.
updated_at Timestamp of when the record was last updated.


  "id": "58126d67cd530e21c40002ec",
  "slug": "heritage-auctions-modern-and-contemporary-art-november-2016",
  "auction_state": "closed",
  "name": "Heritage Auctions: Modern & Contemporary Art (November 2016)",
  "is_preliminary": false,
  "is_auction": true,
  "is_live_integration": true,
  "start_at": "2016-10-28T20:00:00.000Z",
  "end_at": "2016-11-11T20:53:00.000Z",
  "live_start_at": "2016-11-11T16:00:00.000Z",
  "registration_ends_at": "2016-11-10T16:00:00.000Z",
  "published": true,
  "has_buyers_premium": true,
  "created_at": "2016-10-27T21:11:03+00:00",
  "updated_at": "2018-06-21T20:09:45+00:00",
  "_links": {
    "self": {
      "href": ""
    "bidders": {
      "href": "{&with_positions}",
      "templated": true
    "artists": {
      "href": "{&sort,size}",
      "templated": true
    "sale_artworks": {
      "href": "{&published}",
      "templated": true
    "permalink": {
      "href": ""