Items can be retrieved by using the following URL and specifying a starting record number and ending record number. If left blank, this will default to the first 50 records. Items are returned in descending order of full text search relavance (if applicable), item lot, item lot suffix, then item title. Only price and bid data is returned for each item along with the item ID and auction ID.
| Method | URL |
| GET | https://api.fairwarningsoftware.com/v1.1.1/items/refresh/[start]/[limit] |
| Status | Response |
| 200 | {"items":[ { "item_id": <item_id>, "auction_id": <auction_id>, "item_hammer_price": <item_hammer_price>, "item_premium": <item_premium>, "item_timed_auction_start": <item_timed_auction_start>, "item_timed_auction_end": <item_timed_auction_end>, "item_start_price": <item_high_estimate>, "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 |
| auction_id | int | The unique identifier for the auction the item is in |
| 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_start_price | double | The price that the first bid must meet or exceed |
To sort, you can specify a "sort_by" object in the JSON using any field that is searchable, and specifying whether to sort it "asc" or "desc".
{ "sort_by" : { <field_name> : <sort_direction>, "item_lot" : "asc", "item_lot_suffix" : "asc" } }
Furthermore, you may request additional information along with the item request to obtain a user's high bids for the item. You may pass the following with your request:
{ "user_id" : 16 }
User bid data will be returned inline with the item object.
| Response |
|
{ "user" : { |
| Field | Type | Description |
| user | object | Contains an object of user details. |
| can_bid | bool | Specifies whether the user can place a bid for 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. |
You may also choose to search the items in order to retrieve more specific results. For instance, if you are only looking for items in a certain primary category, you could pass query parameters to specify the primary category ID you want the auction results to belong to.
{ "category_id_1": { "operator" : "equals", "value": 59 } }
By passing this data string as raw post data, you will limit your results to only items that belong to the primary cateogory with the cateogory ID of 59.
You may also wish to only get a list of items that are at an office with an ID of 82 that belong to cateogory 59. In that case, you could add a second parameter to your search like so:
{ "category_id_1": { "operator" : "equals", "value": 59 }, "office_id": { "operator" : "equals", "value": 82 } }
In this way, you will limit the search results to both the category ID and the office ID.
Below is a list of search fields that you can perform a full text search on: