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 "https://api.artsy.net/api/sales" -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" : "https://api.artsy.net/api/sales?live=..."
    },
    "next" : {
      "href" : "https://api.artsy.net/api/sales?cursor=...&live=..."
    }
  },
  "_embedded" : {
    "sales" : [
      {
        "id":"...",
        ...
      }
    ]
  }
}

Retrieving a Sale

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

curl -v "https://api.artsy.net/api/sales/{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.

Example

{
  "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": "2017-07-13T19:41:01+00:00",
  "_links": {
    "self": {
      "href": "https://api.artsy.net/api/sales/58126d67cd530e21c40002ec"
    },
    "bidders": {
      "href": "https://api.artsy.net/api/bidders?sale_id=58126d67cd530e21c40002ec{&with_positions}",
      "templated": true
    },
    "sale_artworks": {
      "href": "https://api.artsy.net/api/sale_artworks?sale_id=58126d67cd530e21c40002ec{&published}",
      "templated": true
    },
    "permalink": {
      "href": "http://www.artsy.net/auction/heritage-auctions-modern-and-contemporary-art-november-2016"
    }
  }
}