URL
https://your_bidlogix_domain/auction-mgt/bdxapi/items/{auctionId}?clientId=your_bidlogix_client_id |
Http Method
POST
Headers
| BDXAPI_NAME | BDX API signature (See Api Security document) |
| Content-Type | application/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 |
|---|---|---|---|---|
| type | String | Listing, Lot, WebcastItem | Y | - |
| @class | String | .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) | ||||
| lotNumber | String | If not supplied the lot number is generated as the index of the item in the list. Lot numbers cannot contain duplicate values. | N | item index |
| title | String | The title of the auction - required is using strict validation | Y | Item for lot number x |
| summary | String | A short summary of the item or alternate information such as estimate of the sale price. | N | none |
| description | String | A full description displayed on the item details page. | N | none |
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. | N | none |
| documents | 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. | N | none |
| videos | List<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. | N | none |
| location | AddressModel | see Common Data document | N | from auction |
buyersPremium | Long | 0 - 100 | N | from auction |
contactSellerEnabled | Boolean | Enables the contact vendor feature per item. | N | false |
| currency | CurrencyModel | see Common Data document | N | from auction |
| vendorId | Long | Valid bidlogix vendor id | Y | first defined |
| categoryId | Long | Valid bidlogix category id | Y | first defined |
Fields related to charges and invoicing of the item. | ||||
| charges | Big Decimal | N | 0.00 | |
buyersPremium | Big Decimal | N | from auction | |
chargesTaxRate | Big Decimal | N | from auction | |
hammerTaxRate | Big Decimal | N | from auction | |
bpTaxRate | Big Decimal | N | from auction | |
Listing specific fields - listings do not support bidding. They optionally support buy now, make offer and transfer options. | ||||
| purchaseOption | String | Listing: 'NONE', 'MAKE_OFFER', 'BUY_NOW', 'TRANSFER', 'TENDER', 'TENDER_PCT' | NONE | |
minimumAcceptableOffer | Long | Applies 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_NOW | NONE |
| displayPrice | Long | An optional value to display on listings with a private treaty, or items for TRANSFER. | NONE | |
| unitOfMeasurement | String | 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 | |
| numberOfUnits | Big Decimal | For 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. | ||||
| purchaseOption | String | Lot: 'NONE', 'MAKE_OFFER', 'BUY_NOW' | NONE | |
minimumAcceptableOffer | Long | Applies 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 | Long | The amount to show as the starting bid. | 0 | |
| bidIncrement | Long | The increment - this may be overridden if the auctioneer is using increment tables! | 10 | |
| reservePrice | Long | A price the item must fetch before being sold | 0 | |
| numberOfUnits | Long | The 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 | Long | per item or per lot. 2 - per item 3 - per Lot | per lot | |
openingBid | Long | The amount to show as the starting bid. | 0 | |
| bidIncrement | Long | The increment - this may be overridden if the auctioneer is using increment tables! | 10 | |
| reservePrice | Long | A price the item must fetch before being sold | 0 | |
| numberOfUnits | Long | The 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": "£"
},
"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": "£"
},
"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": "£"
},
"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
- 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).
- Items are created in state 'DRAFT'. See table below for current bidlogix item states.
|