Description

Create items within an already defined auction. This API call adds items to the auction - there may or may not be items in the auction already.

The API is very flexible and only the item type is needed to create a new item (all data can of course be reviewed and changed within the bidlogix admin system). Having said that the API allows any or all of the fields to be set in the API call, although errors will be generated if values of the wrong type are sent (e.g. sending a string instead of a numeric value).

Apart from this the error handling is very lenient and default values will be provided where no value is sent in the API. 

URL

where

https://your_bidlogix_domain/auction-mgt/bdxapi/items/{auctionId}?clientId=your_bidlogix_client_id


{auctionId} : the id of the auction you wish to create items within.


Method

Http Method: POST


Security

See Bidlogix API document. 


Query String Parameters

See Bidlogix API document.


Post Data

The minimum data that needs to be sent to bidlogix to create an item are the item type and a class identifier for internal bidlogix use.

Also type='WebcastItem' is only valid if the auction type is Webcast.

Name

Type

Value Range

Required

Default

typeStringListing, Lot, WebcastItem, BulkBuyItemY-
@classString
com.bidlogix.scaffold.models.auctionapi.ItemApiModel
Y-

Errors in sent values will be corrected automatically. Validation tools and life cycle workflows within the bidlogix system are designed to check bidding data before items are made live. The API is mainly intended for asset database content - titles and images can be easily uploaded into auctions within the bidlogix platform.

Lot numbers will default to the index of the item within the list of items, and the title will default to 'Item for lot number x'.

Name

Type

Value range

Required

Default

The following set of fields apply to all item types (Listing, Lot, BulkBuy, Webcast)
lotNumberStringIf not supplied the lot number is generated as the index of the item in the list. Lot numbers cannot contain duplicate values.Nitem index
titleStringThe title of the auction - required is using strict validationYItem for lot number x
summaryStringA short summary of the item or alternate information such as estimate of the sale price.Nnone
descriptionStringA full description displayed on the item details page.Nnone

images

List<UrlAttachmentApiModel>see Common Data documentNnone
documentsList<UrlAttachmentApiModel>see Common Data document
Nnone
videosList<UrlAttachmentApiModel>see Common Data document. Set the Youtube video id as the URL of the model object to attach Youtube videos to the item.Nnone
locationAddressModelsee Common Data document
Nfrom auction

buyersPremium

Long0 - 100Nfrom auction

contactSellerEnabled

BooleanEnables the contact vendor feature per item.Nfalse
currencyCurrencyModelsee Common Data document
Nfrom auction
vendorIdLongValid bidlogix vendor idYfirst defined
categoryIdLongValid bidlogix category idYfirst defined

Fields related to charges and invoicing of the item...

chargesBig Decimal
N0.00

buyersPremium

Big Decimal
Nfrom auction

chargesTaxRate

Big Decimal
Nfrom auction

hammerTaxRate

Big Decimal
Nfrom auction

bpTaxRate

Big Decimal
Nfrom auction


Listing specific fields - listings do not support bidding. They optionally support buy now, make offer and transfer options.

purchaseOptionString

Listing: 'NONE', 'MAKE_OFFER', 'BUY_NOW', 'TRANSFER', 'TENDER', 'TENDER_PCT'


NONE

minimumAcceptableOffer

LongApplies only if purchaseOption=MAKE_OFFER or BUY_NOW. If purchaseOption=MAKE_OFFER then offers including and below this amount will be automatically rejected. If purchaseOption=BUY_NOW then this field represents the buy now purchase price.Y for BUY_NOWNONE
displayPriceLongAn optional value to display on listings with a private treaty, or items for TRANSFER.

NONE

unitOfMeasurementString

Required for listings with the purchase options of TENDER or TENDER_PCT.

For TENDER, the value should be the unit of measurement of the quantity provided e.g. 'Tonne'.

For TENDER_PCT, the value is a label describing the nature of the % value being offered e.g. 'Discount on LME spot price'.

Y for TENDER, TENDER_PCT
numberOfUnitsBig DecimalFor TENDER and TENDER_PCT listings, the number or approximate number of units available.Y for TENDER, TENDER_PCT


Lot specific fields - lots support bidding. They also optionally support buy now and make offer options.

purchaseOptionString

Lot: 'NONE', 'MAKE_OFFER', 'BUY_NOW'


NONE

minimumAcceptableOffer

LongApplies only if purchaseOption=MAKE_OFFER or BUY_NOW. If purchaseOption=MAKE_OFFER then offers below this amount will be automatically rejected. If purchaseOption=BUY_NOW then this field represents the buy now price.
NONE

openingBid

LongThe amount to show as the starting bid.
0
bidIncrementLongThe increment - this may be overridden if the auctioneer is using increment tables!
10
reservePriceLongA price the item must fetch before being sold
0
numberOfUnitsLongThe number of units available. Bidding is per item i.e. all units.
1


BulkBuy specific fields - bulk buy (multi items) do not support bidding. They are intended to be used with the 'make offer' function but with items composed of multiple units. Users can then make offers different multiples of these units.

numberOfUnits

LongThe total number of units of the item available.


Webcast Item specific fields - used exclusively in live Webcast auctions. They are similar to lots in that they support bidding but they do not support the purchase option functions; make offer, buy now and transfer. Unlike lots these items support bidding type; per item or per unit and can be grouped and sold together with various options for the bidding.

biddingType

Longper item or per unit.
per lot

openingBid

LongThe amount to show as the starting bid.
0
bidIncrementLongThe increment - this may be overridden if the auctioneer is using increment tables!
10
reservePriceLongA price the item must fetch before being sold
0
numberOfUnitsLongThe number of units available. Bidding is per item i.e. all units.
1


Examples


Please find attached a working json post call. 


Request 1: No Images

   "@class":"com.bidlogix.scaffold.models.BackboneCollectionModel",

   "collection":[ 

      

         "type":"Listing",

         "@class":"com.bidlogix.scaffold.models.auctionapi.ItemApiModel",

      },

      

         "type":"Listing",

         "@class":"com.bidlogix.scaffold.models.auctionapi.ItemApiModel",

      }

   ]

}

Response:

   "@class":".BackboneCollectionModel",   "collection":[                "@class":".auctionapi.ItemApiModel",         "id":225,         "type":"Listing",         "auctionIndex":2,         "title":"Title for Item 1",         "summary":null,         "description":null,         "lotNumber":"1",         "statusId":2,         "endTime":1479340800000,         "endTimeReadable":"2016-11-17T00:00:00.000Z",         "locale":null,         "hammerTaxRate":20,         "bpTaxRate":20,         "chargesTaxRate":20,         "buyersPremium":15,         "vendor":{             "@class":".VendorModel",            "id":10,            "auctioneer":null,            "name":"Apex Auctions Ltd",            "companyContact":null,            "contacts":[              ],            "contactable":false,            "activated":false,            "summary":null,            "description":null,            "timeZone":null,            "administrators":[              ]         },         "category":{             "@class":".CategoryModel",            "id":1,            "name":"Turning",            "code":null,            "selected":false,            "treeName":"Industrial Machinery",            "treeId":1,            "parentName":null,            "parentId":null,            "children":null         }      },               "@class":".auctionapi.ItemApiModel",         "id":226,         "type":"Listing",         "auctionIndex":3,         "title":"Title for Item 2",         "summary":null,         "description":null,         "lotNumber":"2",         "statusId":2,         "endTime":1479340800000,         "endTimeReadable":"2016-11-17T00:00:00.000Z",         "locale":null,         "hammerTaxRate":20,         "bpTaxRate":20,         "chargesTaxRate":20,         "buyersPremium":15,         "vendor":{             "@class":".VendorModel",            "id":10,            "auctioneer":null,            "name":"Apex Auctions Ltd",            "companyContact":null,            "contacts":[              ],            "contactable":false,            "activated":false,            "summary":null,            "description":null,            "timeZone":null,            "administrators":[              ]         },         "category":{             "@class":".CategoryModel",            "id":1,            "name":"Turning",            "code":null,            "selected":false,            "treeName":"Industrial Machinery",            "treeId":1,            "parentName":null,            "parentId":null,            "children":null         }      }   ]}

   "@class":".BackboneCollectionModel",

   "collection":[ 

      

         "@class":".auctionapi.ItemApiModel",

         "id":225,

         "type":"Listing",

         "auctionIndex":2,

         "title":"Title for Item 1",

         "summary":null,

         "description":null,

         "lotNumber":"1",

         "statusId":2,

         "endTime":1479340800000,

         "endTimeReadable":"2016-11-17T00:00:00.000Z",

         "locale":null,

         "hammerTaxRate":20,

         "bpTaxRate":20,

         "chargesTaxRate":20,

         "buyersPremium":15,

         "vendor":{ 

            "@class":".VendorModel",

            "id":10,

            "auctioneer":null,

            "name":"Apex Auctions Ltd",

            "companyContact":null,

            "contacts":[ 

 

            ],

            "contactable":false,

            "activated":false,

            "summary":null,

            "description":null,

            "timeZone":null,

            "administrators":[ 

 

            ]

         },

         "category":{ 

            "@class":".CategoryModel",

            "id":1,

            "name":"Turning",

            "code":null,

            "selected":false,

            "treeName":"Industrial Machinery",

            "treeId":1,

            "parentName":null,

            "parentId":null,

            "children":null

         }

      },

      

         "@class":".auctionapi.ItemApiModel",

         "id":226,

         "type":"Listing",

         "auctionIndex":3,

         "title":"Title for Item 2",

         "summary":null,

         "description":null,

         "lotNumber":"2",

         "statusId":2,

         "endTime":1479340800000,

         "endTimeReadable":"2016-11-17T00:00:00.000Z",

         "locale":null,

         "hammerTaxRate":20,

         "bpTaxRate":20,

         "chargesTaxRate":20,

         "buyersPremium":15,

         "vendor":{ 

            "@class":".VendorModel",

            "id":10,

            "auctioneer":null,

            "name":"Apex Auctions Ltd",

            "companyContact":null,

            "contacts":[ 

 

            ],

            "contactable":false,

            "activated":false,

            "summary":null,

            "description":null,

            "timeZone":null,

            "administrators":[ 

 

            ]

         },

         "category":{ 

            "@class":".CategoryModel",

            "id":1,

            "name":"Turning",

            "code":null,

            "selected":false,

            "treeName":"Industrial Machinery",

            "treeId":1,

            "parentName":null,

            "parentId":null,

            "children":null

         }

      }

   ]

}


Request 2: With Images

   "@class":"com.bidlogix.scaffold.models.BackboneCollectionModel",

   "collection":[ 

      

         "type":"BulkBuyItem",

         "@class":"com.bidlogix.scaffold.models.auctionapi.ItemApiModel",

         "images":[ 

            

               "@class":"com.bidlogix.scaffold.models.auctionapi.UrlAttachmentApiModel",

               "url":"https://image.tmdb.org/t/p/w185/mBDlsOhNOV1MkNii81aT14EYQ4S.jpg"

            },

            

               "@class":"com.bidlogix.scaffold.models.auctionapi.UrlAttachmentApiModel",

               "url":"http://ichef.bbci.co.uk/news/660/cpsprodpb/8FE2/production/_92443863_hi036394711.jpg"

            }

         ]

      }

   ]

}

 


Response

{

    "@class"".BackboneCollectionModel",

    "collection": [

        {

        "@class"".auctionapi.ItemApiModel",

        "id"219,

        "type""Listing",

        "auctionIndex"1,

        "auctionId"8,

        "auctioneerId"1,

        "title""Title for Item 2",

        "summary"null,

        "description"null,

        "lotNumber""2",

        "statusId"2,

        "endTime"1538956800000,

        "endTimeReadable""2018-10-08T01:00:00.000+01:00",

        "locale"null,

        "hammerTaxRate"20,

        "bpTaxRate"20,

        "charges"0,

        "chargesTaxRate"20,

        "buyersPremium"15,

        "displayPrice"null,

        "purchaseOption""NONE",

        "contactSellerEnabled"false,

        "minimumAcceptableOffer"null,

        "unitOfMeasurement"null,

        "vendorId"10,

        "vendor": {

            "@class"".VendorModel",

            "id"10,

            "auctioneer"null,

            "name""Apex Auctions Ltd",

            "companyContact"null,

            "contacts": [],

            "contactable"false,

            "activated"false,

            "summary"null,

            "description"null,

            "timeZone"null,

            "administrators": [],

        },

        "categoryId"2,

        "category": {

            "@class"".CategoryModel",

            "id"2,

            "name""CNC Lathes - Integrated Turning & Milling Machines",

            "code"null,

            "selected"false,

            "treeName""Industrial Machinery",

            "treeId"1,

            "parentName""Turning",

            "parentId"1,

            "children"null

        },

        "currencyId"10,

        "currency": {

            "@class"".CurrencyModel",

            "id"10,

            "name""Russian Rouble",

            "code""RUB",

            "selected"false,

            "symbol""руб"

        },

        "openingBid"null,

        "bidIncrement"null,

        "reservePrice"null,

        "numberOfUnits"1,

        "numberOfUnitsRemaining"null,

        "biddingType"null,

        "emailOptions": {

            "@class"".ItemEmailOptionsApiModel",

            "sendTransferEmailNotification"null

        },

        "documents"null,

        "images": [

            {

            "@class"".UrlAttachmentApiModel",

            "type"null,

            "url""https://image.tmdb.org/t/p/w185/mBDlsOhNOV1MkNii81aT14EYQ4S.jpg",

            "label"null,

            "publicId""local/mBDlsOhNOV1MkNii81aT14EYQ4S_e4incs",

            "errInfo"null

            },

            {

            "@class"".UrlAttachmentApiModel",

            "type"null,

            "url""http://ichef.bbci.co.uk/news/660/cpsprodpb/8FE2/production/_92443863_hi036394711.jpg",

            "label"null,

            "publicId""local/_92443863_hi036394711_vvgogv",

            "errInfo"null

            }

        ],

        "videos"null,

        "location": {

            "@class"".AddressModel",

            "id"2,

            "version"0,

            "addressType"0,

            "addressLine1""21 Low St",

            "addressLine2""North Rd.",

            "addressLine3""",

            "addressLine4""",

            "city""London",

            "county""",

            "postcode""N17 1PL",

            "countryId"232,

            "countryCode""uk",

            "countryName""United Kingdom",

            "continentId"1,

            "continentCode""EUR",

            "latitude"null,

            "longitude"null

            }

        }

    ],

}

 


Errors

Errors are handled where possible by returning an ErrorModel with the field 'failed' set to true. The error model will contain a detailed message indicating the first errored field. The errors are generally related to incorrect types being sent in the fields above. For example the following fails because a 'string' value is sent in the 'charges' field which should contain a big decimal value.

Status Code: 400 (Bad Request)

   "@class":"com.bidlogix.scaffold.models.BackboneCollectionModel",

   "collection":[ 

      

         "type":"Listing",

         "@class":"com.bidlogix.scaffold.models.auctionapi.ItemApiModel",

         "charges":"dfsdf"

      }

   ]

}

Yields the response...

   "@class":".ErrorModel",

   "failed":true,

   "field":null,

   "code":"BIDLOGIX_API",

   "message":"Could not read JSON: Can not construct instance of java.math.BigDecimal from String value 'dfsdf': not a valid representation\n at [Source: java.io.PushbackInputStream@430ab1bf; line: 1, column: 161] (through reference chain: com.bidlogix.scaffold.models.BackboneCollectionModel[\"collection\"]->java.util.ArrayList[0]->com.bidlogix.scaffold.models.auctionapi.ItemApiModel[\"charges\"]); nested exception is com.fasterxml.jackson.databind.exc.InvalidFormatException: Can not construct instance of java.math.BigDecimal from String value 'dfsdf': not a valid representation\n at [Source: java.io.PushbackInputStream@430ab1bf; line: 1, column: 161] (through reference chain: com.bidlogix.scaffold.models.BackboneCollectionModel[\"collection\"]->java.util.ArrayList[0]->com.bidlogix.scaffold.models.auctionapi.ItemApiModel[\"charges\"])",

   "loggedIn":false

}


Notes

  1. Duplicate lot numbers were previously allowed via the API but were considered validation errors within bidlogix management. As of November 2019, this is no longer the case and attempting to create items with lot numbers that already exist in the system for this auction will return a 400 error response (with the duplicates listed in the body of the error response).
  2. Items are created in state 'DRAFT'. See table below for current bidlogix item states.


NEW                     (1"New"),

DRAFT                   (2"Draft"),

PREVIEW                 (3"Preview"),

LIVE                    (4"Live")

WITHDRAWN               (5"Withdrawn"),

SOLD                    (6"Sold Bidding"),

SOLD_MAKE_OFFER         (7"Sold Make Offer"),

UNSOLD                  (8"Unsold"),

SUSPENDED               (9"Suspended"),

SOLD_BUY_NOW            (10"Sold Buy Now"),

SOLD_BULK_BUY_FULL      (11"Sold Bulk Buy"),

SOLD_BULK_BUY_PARTIAL   (12"Sold Bulk Buy"),

OPEN_BULK_BUY_PARTIAL   (13"Live - Bulk Buy"),

WITHDRAWN_ENDED         (14"Withdrawn Ended");