How to obtain an item by Slug from the FWS API

Individual items can be retrieved by using the following URL and specifying the item slug.

 

 Method URL
 GET  https://api.fairwarningsoftware.com/v1.1.1/item/slug/[item-slug]

 

 Status Response
 200

{
        "item_id": <item_id>,
        "receipt_id": <receipt_id>,
        "office_id": <office_id>,
        "storage_id": <storage_id>,
        "auction_id": <auction_id>,
        "status_id": <status_id>,
        "category_id_1": <category_id_1>,
        "category_id_2": <category_id_2>,
        "category_id_3": <category_id_3>,
        "web_category_id_1": <web_category_id_1>,
        "web_category_id_2": <web_category_id_2>,
        "web_category_id_3": <web_category_id_3>,
        "item_advertise": <item_advertise>,
        "item_lot": <item_lot>,
        "department_id": <department_id>,
        "item_consignor_numbers": <item_consignor_numbers>,
        "item_lot": <item_lot>,
        "item_lot_suffix": <item_lot_suffix>,
        "item_buy_it_now": <item_buy_it_now>,
        "item_timed_auction_start": <item_timed_auction_start>,
        "item_timed_auction_end": <item_timed_auction_end>,
        "item_low_estimate": <item_low_estimate>,
        "item_high_estimate": <item_high_estimate>,
        "item_start_price": <item_high_estimate>,
        "item_reserve": <item_reserve>,
        "item_hammer_price": <item_hammer_price>,
        "bidder_id": <bidder_id>,
        "item_width": <item_width>,
        "item_height": <item_height>,
        "item_depth": <item_depth>,
        "item_weight": <item_weight>,
        "item_overnight_required": <item_overnight_required>,
        "item_quantity": <item_quantity>,
        "item_shippable": <item_shippable>,
        "item_shelf_location": <item_shelf_location>,
        "item_provenance": <item_provenance>,
        "item_title": <item_title>,
        "item_slug": <item_slug>,
        "item_description": <item_description>,
        "item_condition": <item_condition>,
        "item_comments_to_consignor": <item_comments_to_consignor>,
        "item_lot_index" : <item_lot_index>,
        "previous_lot": <previous_lot>,
        "next_lot": <next_lot>,
        "primary_image": {
            "base" : [url-base],
            "parts" : {
                "full" : [url-addition],
                "large" : [url-addition],
                "medium" : [url-addition],
                "thumb" : [url-addition]
            }
        },
        "bid_info" : {
            "high_bid" : <high_bid>,
            "next_bid" : <next_bid>,
            "bid_increment" : <bid_increment>
        }
}
401  {"error":"The API keys provided are invalid."}
403  {"error":"API keys are missing."}
500  {"error": <custom error>}

 

 Field  Type Description
item_id int The unique identifier for the item
receipt_id int The ID of the receipt this item belongs to
office_id int The ID of the office this location is at
storage_id int The ID of the storage location the item is at
auction_id int The unique identifier for the auction the item is in
status_id int The ID for the status applied to this item
category_id_1 int The primary category ID assigned to this item
category_id_1 int The secondary category ID assigned to this item
category_id_3 int The tertiary category ID assigned to this item
web_category_id_1 int The primary web category ID assigned to this item
web_category_id_2 int The secondary web category ID assigned to this item
web_category_id_3 int The tertiary web category ID assigned to this item
iitem_advertise bool Whether the item was flagged to be advertised
department_id int The ID for the department set for the item
item_consignor_numbers string The consignor numbers associated with the item
item_lot int The lot number given to the item designating it's place in the auction
item_lot_suffix string The lot suffix associated with an item
item_buy_it_now double The buy-it-now price assigned to the item
item_timed_auction_start datetime The date and time bidding for the item starts
item_timed_auction_end datetime The date and time bidding for the item ends
item_low_estimate double The low estimate for the item
item_high_estimate double The high estimate for the item
item_start_price double The price that the first bid must meet or exceed
item_reserve double The price that must be matched or exceeded to win the item
item_hammer_price double The price of the bid placed that won the item
bidder_id int The user's ID who won the item
item_width double The width of the widest part of the item
item_height double The height of the tallest part of the item
item_depth double The depth of the deepest part of the item
item_weight double The weight of the item
item_overnight_required bool Whether the item requires overnight shipping when shipping
item_quantity int The number of pieces which make up the item lot
item_shippable bool Whether the item is allowed to be shipped
item_shelf_location string The location of the item on a shelf
item_provenance string The place of origin or earliest known history of the item
item_title string The title of the item
item_slug string The slug of the item title
item_description string The description of the item
item_condition string The condition of the item
item_comments_to_consignor string Comments only for the consignor to see
item_lot_index int The index of this item in the auction it is contained within according to lot number
previous_lot int The item ID of the previous lot within the same auction
next_lot int The item ID of the next lot within the same auction
primary_image object An object containing the base and paths to the different image sizes of the primary image
    base string The base will contain the first part of the URL needed to retrieve the specified image.
    parts object This will contain an array of URL parts for the different sizes of images.
        full string The end of the URL to retrieve a full-sized image.
        large string The end of the URL to retrieve a large-sized image.
        medium string The end of the URL to retrieve a medium-sized image.
        thumb string The end of the URL to retrieve a thumb-sized image.

 

Furthermore, you may request additional information along with the item request to obtain item images, auction information, a user's high bids for the item, and related items.  You may pass any or all of the following with your request:

  • get_related
  • get_auction
  • get_images
  • user_id
{ "get_related" : 1, "get_auction" : 1, "get_images" : 1, "user_id" : 16 }


Related items will be returned inline with the item object.

Response

 {
    [item-object],

    "related_items" : {
        "items":[
            {
                "item_id": <item_id>,
                "receipt_id": <receipt_id>,
                "office_id": <office_id>,
                "storage_id": <storage_id>,
                "auction_id": <auction_id>,
                "status_id": <status_id>,
                "category_id_1": <category_id_1>,
                "category_id_2": <category_id_2>,
                "category_id_3": <category_id_3>,
                "web_category_id_1": <web_category_id_1>,
                "web_category_id_2": <web_category_id_2>,
                "web_category_id_3": <web_category_id_3>,
                "item_advertise": <item_advertise>,
                "item_lot": <item_lot>,
                "department_id": <department_id>,
                "item_consignor_numbers": <item_consignor_numbers>,
                "item_lot": <item_lot>,
                "item_lot_suffix": <item_lot_suffix>,
                "item_buy_it_now": <item_buy_it_now>,
                "item_timed_auction_start": <item_timed_auction_start>,
                "item_timed_auction_end": <item_timed_auction_end>,
                "item_low_estimate": <item_low_estimate>,
                "item_high_estimate": <item_high_estimate>,
                "item_start_price": <item_high_estimate>,
                "item_reserve": <item_reserve>,
                "item_hammer_price": <item_hammer_price>,
                "bidder_id": <bidder_id>,
                "item_width": <item_width>,
                "item_height": <item_height>,
                "item_depth": <item_depth>,
                "item_weight": <item_weight>,
                "item_overnight_required": <item_overnight_required>,
                "item_quantity": <item_quantity>,
                "item_shippable": <item_shippable>,
                "item_shelf_location": <item_shelf_location>,
                "item_provenance": <item_provenance>,
                "item_title": <item_title>,
                "item_slug": <item_slug>,
                "item_description": <item_description>,
                "item_condition": <item_condition>,
                "item_comments_to_consignor": <item_comments_to_consignor>,
                "primary_image": {
                    "base" : [url-base],
                    "parts" : {
                        "full" : [url-addition],
                        "large" : [url-addition],
                        "medium" : [url-addition],
                        "thumb" : [url-addition]
                    }
                }
            },
           "record_count" : <record_count>
        ]
    }
}

 

 

Auction information will be returned inline with the item object.

Response

 {
    [item-object],

    "auction_info" : {
        "auction_id": <auction_id>,
        "company_id": <company_id>,
        "auction_lock": <auction_lock>,
        "auction_hide": <auction_hide>,
        "auction_preview": <auction_preview>,
        "auction_event": <auction_event>,
        "type_id": <type_id>,
        "type_name": <type_name>,
        "office_id": <office_id>,
        "office_name": <office_name>,
        "department_id": <department_id>,
        "department_name": <department_name>,
        "auction_date": <auction_date>,
        "auction_name": <auction_name>,
        "auction_bidder_type_ids": <auction_bidder_type_ids>,
        "bidsquare_ids": <bidsquare_ids>,
        "auction_description": <auction_description>,
        "auction_comments": <auction_comments>,
        "auction_terms": <auction_terms>,
        "auction_event_description": <auction_event_description>,
        "primary_image": <primary_image>,
        "calendar_image": <calendar_image>,
        "event_image": <event_image>,
        "auction_current_item": <auction_current_item>,
        "allows_phone_bids" : <allows_phone_bids>
    }
}

 

 Field  Type Description
auction_info object An object containing the auction information for the item
auction_id int The unique identifier for the auction
company_id int The ID for your company
auction_lock bool Whether the auction is locked or not
auction_hide bool Whether the auction is hidden or not
auction_preview bool Whether the auction can be previewed or not
auction_event bool Whether the auction is an event or not
type_id int The ID for the type of auction it is
type_name string The name for the type of auction it is
office_id int The ID for the office set for the auction
office_name int The name for the office set for the auction
department_id int The ID for the department set for the auction
department_name int The name for the department set for the auction
auction_date datetime The date and time of the auction
auction_name string The name of the auction
auction_bidder_type_ids string A JSON formatted string containing the different bidder types that can bid in this auction
bidsquare_ids string A JSON formatted string containing the different Bidsquare catalog IDS and lot ranges for each catalog
auction_description string The description provided for the auction
auction_comments string Additional comments provided for the auction
auction_terms string The terms and conditions for the auction
auction_event_description string The description for the auction event
primary_image string The image for the auction
calendar_image string The calendar image for the auction
event_image string The event image for the auction
auction_current_item string The current item the auctioneer is on during a live auction
allows_phone_bids bool Whether the auction allows phone bids to be taken

 

 

Images will be returned inline with the item object.

Response

{
    [item-object],

    "item_images" :
    [
        {
            "image" : {
                "base" : [url-base],
                "parts" : {
                    "full" : [url-addition],
                    "large" : [url-addition],
                    "medium" : [url-addition],
                    "thumb" : [url-addition]
                }
            },
            "image" : {
                "base" : [url-base],
                "parts" : {
                    "full" : [url-addition],
                    "large" : [url-addition],
                    "medium" : [url-addition],
                    "thumb" : [url-addition]
                }
            }
        }
    ]
}

 

 Field  Type Description
item_images object Contains an array of image objects.
image object Contains an array of an individual image's data.
base string The base will contain the first part of the URL needed to retrieve the specified image.
parts object This will contain an array of URL parts for the different sizes of images.
full string The end of the URL to retrieve a full-sized image.
large string The end of the URL to retrieve a large-sized image. (500px x 500px)
medium string The end of the URL to retrieve a medium-sized image. (250px x 250px)
thumb string The end of the URL to retrieve a thumb-sized image. (50px x 50px)

 

User bid data will be returned inline with the item object.

Response

{
    [item-object],

    "user" : {
        "high_bidder" : <high_bidder>,
        "following_item" : <following_item>,
        "can_bid" : {
            "live" : <live>,
            "timed" : <timed>,
            "absentee" : <absentee>,
            "phone" : <phone>,
            "buy_it_now" : <buy_it_now>
        },
        "high_bids" : {
            "bid_amount" : <bid_amount>,
            "phone_bid_active" : <phone_bid_actived>,
            "phone_bid_amount" : <phone_bid_amount>,
            "timed_bid_amount" : <timed_bid_amount>
        }
    }
}

 

 Field  Type Description
user object Contains an object of user details.
     high_bidder bool Whether the user is the high bidder for the item or not.
     following_item bool Whether the user is following the item or not.
    can_bid object/bool Object with a list of bidding actions available. If false, bid requirements have not been met.
        live bool Specifies whether the user can place a live bid for the current item or not.
        timed bool Specifies whether the user can place a timed bid for the current item or not.
        absentee bool Specifies whether the user can place a absentee bid for the current item or not.
        phone bool Specifies whether the user can register for a phone bid for the current item or not.
        buy_it_now bool Specifies whether the user can purchase the current item or not.
    high_bids object Contains information for the user's bids on the item.
        bid_amount
 decimal Contains the highest executed bid left for this item by the user.
        phone_bid_active
 bool Specifies if the user registered for phone bidding for this item.
        phone_bid_amount
 decimal Contains the phone bid insurance amount left for this item by the user.
        timed_bid_amount
 decimal Contains the top bid amount left for timed bidding for this item bye the user.