You can get a list of items being followed by a user by using the following URL and specifying the user ID.
| Method | URL |
| POST | https://api.fairwarningsoftware.com/v1.1.1/items/following/[user-id]/[start]/[limit] |
| Status | Response |
| 200 | {"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] } }, "bid_info" : { "high_bid" : <high_bid>, "next_bid" : <next_bid>, "bid_increment" : <bid_increment> } }, "record_count" : <record_count> ]} |
| 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 |
| 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. |
| record_count | int | The total number of records matching the search results |
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:
User bid data will be returned inline with the item object.
| Response |
|
{ "user" : { |
| 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. |
| bid_requirements | array object | Contains an array of requirement objects if bid requirements have not been met. |
| requirement_code | int | A numeric code corresponding to the requirement error. |
| requirement_message | string | An error message which can be displayed to the user. |
| 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. |
| Requirement Code |
Description |
| 1 | The user must submit a bid request, and has not yet submitted one. |
| 2 | The user submitted a bid request, but it is currently awaiting review. |
| 3 | The user submitted a bid request, but the request was denied. |
| 4 | The user must have their phone number, billing address, and shipping address on file. |
| 5 | The user must have a valid credit card on file. |