URL

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.

Http Method

POST


Headers 

BDXAPI_NAMEBDX API signature (See Api Security document)
Content-Typeapplication/json


Query String Parameters

See General Api Documentation document.


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.


Request Body 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.

'WebcastItem' item type is only valid if the auction type is Webcast.

Name

Type

Value Range

Required

Default

typeStringListing, Lot, WebcastItemY-
@classString
.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, 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 document.

Note: attachments must have a unique filename. If it is attempted to upload two attachment files with the same filename, the second will be ignored.
Nnone
documentsList<UrlAttachmentApiModel>see Common Data document.

Note: attachments must have a unique filename. If it is attempted to upload two attachment files with the same filename, the second will be ignored.
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.

Note: attachments must have a unique filename. If it is attempted to upload two attachment files with the same filename, the second will be ignored.
Nnone
locationAddressModelsee Common Data documentNfrom auction

buyersPremium

Long0 - 100Nfrom auction

contactSellerEnabled

BooleanEnables the contact vendor feature per item.Nfalse
currencyCurrencyModelsee Common Data documentNfrom 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


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 lot.

2 - per item 

3 - per Lot


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.


Example 1: api call with minimal information to create two items

{ 
 "@class":"com.bidlogix.scaffold.models.BackboneCollectionModel",
   "collection":[ 
      { 
         "type":"Listing",
         "@class":".ItemApiModel"
      },
      {
         "type":"Listing",
         "@class":".ItemApiModel"
      }
   ]
}


Api Response:

{
  "@class": ".BackboneCollectionModel",
  "collection": [
    {
      "@class": ".auctionapi.ItemApiModel",
      "id": 225,
      "type": "Listing",
      "auctionIndex": 4,
      "auctionId": 159,
      "auctioneerId": 1,
      "title": "Title for Item 5",
      "summary": null,
      "description": null,
      "lotNumber": "5",
      "statusId": 2,
      "endTime": 1630400400000,
      "endTimeReadable": "2021-08-31T10:00:00.000+01:00",
      "locale": null,
      "listingUuid": "cc6ee1e6-3ca8-437b-a303-6b55ce5427d0",
      "auctionUuid": "be7c0e81-5498-4979-82c8-5ffa89ef5be1",
      "hammerTaxRate": 17.5,
      "bpTaxRate": 17.5,
      "charges": 0,
      "chargesTaxRate": 17.5,
      "buyersPremium": 15,
      "displayPrice": null,
      "purchaseOption": "NONE",
      "contactSellerEnabled": false,
      "minimumAcceptableOffer": null,
      "unitOfMeasurement": null,
      "vendorId": 10,
      "vendor": {
        "@class": ".VendorModel",
        "id": 10,
        "auctioneer": null,
        "name": "Bidlogix 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": 2,
      "currency": {
        "@class": ".CurrencyModel",
        "id": 2,
        "name": "British Pound Sterling",
        "code": "GBP",
        "selected": false,
        "symbol": "&#163;"
      },
      "openingBid": null,
      "bidIncrement": null,
      "reservePrice": null,
      "numberOfUnits": 1,
      "numberOfUnitsRemaining": null,
      "biddingType": null,
      "emailOptions": {
        "@class": ".ItemEmailOptionsApiModel",
        "sendTransferEmailNotification": null
      },
      "documents": null,
      "images": null,
      "videos": null,
      "location": {
        "@class": ".AddressModel",
        "id": 704,
        "version": 0,
        "addressType": 0,
        "addressLine1": "69 Middle Street",
        "addressLine2": "",
        "addressLine3": null,
        "addressLine4": null,
        "city": "Brighton",
        "county": "",
        "postcode": "BN1 1AL",
        "countryId": 232,
        "countryCode": "uk",
        "countryName": "United Kingdom",
        "continentId": 1,
        "continentCode": "EUR",
        "latitude": "",
        "longitude": ""
      },
      "attachmentType": null,
      "attachmentUrl": null
    },
    {
      "@class": ".auctionapi.ItemApiModel",
      "id": 226,
      "type": "Listing",
      "auctionIndex": 5,
      "auctionId": 159,
      "auctioneerId": 1,
      "title": "Title for Item 6",
      "summary": null,
      "description": null,
      "lotNumber": "6",
      "statusId": 2,
      "endTime": 1630400400000,
      "endTimeReadable": "2021-08-31T10:00:00.000+01:00",
      "locale": null,
      "listingUuid": "770a7942-86b1-4959-a226-068353804523",
      "auctionUuid": "be7c0e81-5498-4979-82c8-5ffa89ef5be1",
      "hammerTaxRate": 17.5,
      "bpTaxRate": 17.5,
      "charges": 0,
      "chargesTaxRate": 17.5,
      "buyersPremium": 15,
      "displayPrice": null,
      "purchaseOption": "NONE",
      "contactSellerEnabled": false,
      "minimumAcceptableOffer": null,
      "unitOfMeasurement": null,
      "vendorId": 10,
      "vendor": {
        "@class": ".VendorModel",
        "id": 10,
        "auctioneer": null,
        "name": "Bidlogix 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": 2,
      "currency": {
        "@class": ".CurrencyModel",
        "id": 2,
        "name": "British Pound Sterling",
        "code": "GBP",
        "selected": false,
        "symbol": "&#163;"
      },
      "openingBid": null,
      "bidIncrement": null,
      "reservePrice": null,
      "numberOfUnits": 1,
      "numberOfUnitsRemaining": null,
      "biddingType": null,
      "emailOptions": {
        "@class": ".ItemEmailOptionsApiModel",
        "sendTransferEmailNotification": null
      },
      "documents": null,
      "images": null,
      "videos": null,
      "location": {
        "@class": ".AddressModel",
        "id": 704,
        "version": 0,
        "addressType": 0,
        "addressLine1": "69 Middle Street",
        "addressLine2": "",
        "addressLine3": null,
        "addressLine4": null,
        "city": "Brighton",
        "county": "",
        "postcode": "BN1 1AL",
        "countryId": 232,
        "countryCode": "uk",
        "countryName": "United Kingdom",
        "continentId": 1,
        "continentCode": "EUR",
        "latitude": "",
        "longitude": ""
      },
      "attachmentType": null,
      "attachmentUrl": null
    }
  ]
}


Example 2: api call with minimal information and images to create one item with images

{
  "@class": "com.bidlogix.scaffold.models.BackboneCollectionModel",
  "collection": [
    {
      "type": "Listing",
      "@class": ".ItemApiModel",
      "images": [
        {
          "@class": ".UrlAttachmentApiModel",
          "url": "full image url"
        },
        {
          "@class": ".UrlAttachmentApiModel",
          "url": "full image url"
        }
      ]
    }
  ]
}


Api Response

{
    "@class": ".BackboneCollectionModel",
    "collection": [
        {
            "@class": ".auctionapi.ItemApiModel",
            "id": 227,
            "type": "Listing",
            "auctionIndex": 6,
            "auctionId": 159,
            "auctioneerId": 1,
            "title": "Title for Item 7",
            "summary": null,
            "description": null,
            "lotNumber": "7",
            "statusId": 2,
            "endTime": 1630400400000,
            "endTimeReadable": "2021-08-31T10:00:00.000+01:00",
            "locale": null,
            "listingUuid": "19951ad1-f84d-4bf9-82ea-62a54a7b84bb",
            "auctionUuid": "be7c0e81-5498-4979-82c8-5ffa89ef5be1",
            "hammerTaxRate": 17.50,
            "bpTaxRate": 17.50,
            "charges": 0,
            "chargesTaxRate": 17.50,
            "buyersPremium": 15.00,
            "displayPrice": null,
            "purchaseOption": "NONE",
            "contactSellerEnabled": false,
            "minimumAcceptableOffer": null,
            "unitOfMeasurement": null,
            "vendorId": 10,
            "vendor": {
                "@class": ".VendorModel",
                "id": 10,
                "auctioneer": null,
                "name": "Bidlogix 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": 2,
            "currency": {
                "@class": ".CurrencyModel",
                "id": 2,
                "name": "British Pound Sterling",
                "code": "GBP",
                "selected": false,
                "symbol": "&#163;"
            },
            "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": "full image url",
                    "label": null,
                    "publicId": null,
                    "errInfo": null
                },
                {
                    "@class": ".UrlAttachmentApiModel",
                    "type": null,
                    "url": "full image url",
                    "label": null,
                    "publicId": null,
                    "errInfo": null
                }
            ],
            "videos": null,
            "location": {
                "@class": ".AddressModel",
                "id": 704,
                "version": 0,
                "addressType": 0,
                "addressLine1": "69 Middle Street",
                "addressLine2": "",
                "addressLine3": null,
                "addressLine4": null,
                "city": "Brighton",
                "county": "",
                "postcode": "BN1 1AL",
                "countryId": 232,
                "countryCode": "uk",
                "countryName": "United Kingdom",
                "continentId": 1,
                "continentCode": "EUR",
                "latitude": "",
                "longitude": ""
            },
            "attachmentType": null,
            "attachmentUrl": 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":".ItemApiModel",
         "charges":"dfsdf"
      }
   ]
}

Yields the response:

{
    "message": "Error message string",
    "status": "Status code string"
}


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"),

WITHDRAWN_ENDED         (14"Withdrawn Ended");