Table of contents
How to list your auctions and items on Aucteeno platform
There is specific process how to apply, or conditions you do have to meet. If you want your auctions and online/timed auctions items listed on Aucteeno please visit Contact form and put subject “New publisher” with all your details filled in.
Accepted formats
On Aucteeno there are 2 accepted formats of your feeds. JSON and XML.
JSON would be our preferred format, because it is more resilient to special characters, and overall experience with JSON, in our humble opinion, makes it easier for implementation on our end.
Data structure
Company data structure
If you have multiple companies which feeds you want to pass to us, you don’t have to create multiple endpoints, but we do need to have specific format of data for each company in order to be able to retrieve company data and make sure out data are consistent with what you have on your side.
Companies API endpoint
/companies?page={page}&per_page={perPage}/companies/page/{page}/per_page/{perPage}
Companies API data usage
Companies endpoint allows Aucteeno to automatically import all your companies (if you are providing multiple companies feed) that will get matched with auctions and items, and will be properly associated. Missing companies can be automatically created on our end, effectively eliminating the need to reach out to us every time new company gets created, or when some change is needed.
Companies API preferred data structure
{
"companies": [
{
"companyId": {
"type": "int|string",
"required": true,
"unique": true,
"description": "ID of company on your bidding platform"
},
"name": {
"type": "string",
"required": true,
"unique": false,
"description": "Company name on your bidding platform."
},
"email": {
"type": "string",
"required": true,
"unique": true,
"description": "Company email address. Used to make internal account for company on Aucteeno."
},
"defaultCurrency": {
"type": "string",
"required": true,
"unique": false,
"description": "Company default currency for auctions in 3 letter format (CAD, USD, EUR)."
},
"defaultTimezone": {
"type": "string",
"required": true,
"unique": false,
"description": "Company default timezone in TZ Database format (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)"
},
"logo": {
"type": "string",
"required": false,
"unique": false,
"description": "URL path to company logo. Needs to be valid URL."
},
"location": {
"country": {
"type": "string",
"required": true,
"unique": false,
"description": "Company location country in ISO 3166-1 standard Alpha 2 format (ex. US/CA/DE/NL)"
},
"subdivision": {
"type": "string",
"required": true,
"unique": false,
"description": "Company location subdivision (state/province) in ISO 3166-2 standard (ex. US-CA, US-TX, CA-MB)"
},
"city": {
"type": "string",
"required": true,
"unique": false,
"description": "Company location city"
},
"postal_code": {
"type": "string",
"required": true,
"unique": false,
"description": "Company location postal/zip code"
},
"address": {
"type": "string",
"required": false,
"unique": false,
"description": "Company location postal/zip code"
},
"address2": {
"type": "string",
"required": false,
"unique": false,
"description": "Company location postal/zip code"
}
}
}
],
"pagination": {
"currentPage": {
"type": "int",
"required": true,
"unique": false,
"description": "Current page listed"
},
"maxPage": {
"type": "int",
"required": true,
"unique": false,
"description": "Last page available. Max value for page query argument"
},
"perPage": {
"type": "int",
"required": false,
"unique": false,
"description": "Number of items we can found per page"
}
}
}Auctions data structure
Auctions API endpoint
/auctions?page={page}&per_page={per_page}/auctions/page/{page}/per_page/{per_page}/auctions?page={page}&per_page={per_page}&company={companyId}/companies/{companyId}/auctions/page/{page}/per_page/{per_page}
If you decide to implement listing-per-company make sure that companyId passed in companies feed can be used for filtering in this case too.
Auctions API data usage
Auctions endpoint allows Aucteeno to automatically import all your auctions (for all companies, if you are providing multiple companies feed, or per-company bases using company query argument). Pagination rules are applied, or you can ship all auctions in one feed (this might be suboptimal if you have high number of auctions).
Auctions API preferred data structure
{
"auctions": [
{
"auctionId": {
"type": "int|string",
"required": true,
"unique": true,
"description": "Unique ID of auction on your bidding platform"
},
"companyId": {
"type": "int|string",
"required": false,
"unique": true,
"description": "UniqueID of company on your bidding platform. Applicable only in case of multi-company setup."
},
"type": {
"type": "string",
"required": true,
"unique": false,
"description": "Auction type on your bidding platform. Accepted values are ONLINE, TIMED, LIVE"
},
"title": {
"type": "string",
"required": true,
"unique": false,
"description": "Auction title on your bidding platform."
},
"externalUrl": {
"type": "string",
"required": true,
"unique": true,
"description": "Link to auction on your bidding platform."
},
"description": {
"type": "string",
"required": false,
"unique": false,
"description": "Auction description text on your bidding platform."
},
"notice": {
"type": "string",
"required": false,
"unique": false,
"description": "Auction notice text on your bidding platform."
},
"biddingNotice": {
"type": "string",
"required": false,
"unique": false,
"description": "Auction bidding notice text on your bidding platform."
},
"directions": {
"type": "string",
"required": false,
"unique": false,
"description": "Auction directions text on your bidding platform."
},
"termsAndConditions": {
"type": "string",
"required": false,
"unique": false,
"description": "Auction terms&conditions text on your bidding platform."
},
"bidding": {
"startsAtUtc": {
"type": "datetime|int",
"required": false,
"unique": false,
"description": "Auction bidding start UTC time on your bidding platform. Can be timestamp format in ISO8601 format (2005-08-15T15:52:01+0000) or unixtime (number of seconds since 1970-01-01T00:00:00-00:00). If left out, start time of auction will be set to the moment of import."
},
"endsAtUtc": {
"type": "datetime|int",
"required": true,
"unique": false,
"description": "Auction bidding end UTC time on your bidding platform. Can be timestamp format in ISO8601 format (2005-08-15T15:52:01+0000) or unixtime (number of seconds since 1970-01-01T00:00:00-00:00)."
},
"startsAt": {
"type": "datetime|int",
"required": false,
"unique": false,
"description": "Auction bidding start local time on your bidding platform. Can be timestamp format in ISO8601 format (2005-08-15T15:52:01+0000) or unixtime (number of seconds since 1970-01-01T00:00:00-00:00). If left out, start time of auction will be set to the moment of import."
},
"endsAt": {
"type": "datetime|int",
"required": false,
"unique": false,
"description": "Auction bidding end local time on your bidding platform. Can be timestamp format in ISO8601 format (2005-08-15T15:52:01+0000) or unixtime (number of seconds since 1970-01-01T00:00:00-00:00)."
}
},
"location": {
"country": {
"type": "string",
"required": true,
"unique": false,
"description": "Company location country in ISO 3166-1 standard Alpha 2 format (ex. US/CA/DE/NL)"
},
"subdivision": {
"type": "string",
"required": true,
"unique": false,
"description": "Company location subdivision (state/province) in ISO 3166-2 standard (ex. US-CA, US-TX, CA-MB)"
},
"city": {
"type": "string",
"required": true,
"unique": false,
"description": "Company location city"
},
"postal_code": {
"type": "string",
"required": true,
"unique": false,
"description": "Company location postal/zip code"
},
"address": {
"type": "string",
"required": false,
"unique": false,
"description": "Company location postal/zip code"
},
"address2": {
"type": "string",
"required": false,
"unique": false,
"description": "Company location postal/zip code"
}
}
}
],
"pagination": {
"currentPage": {
"type": "int",
"required": true,
"unique": false,
"description": "Current page listed"
},
"maxPage": {
"type": "int",
"required": true,
"unique": false,
"description": "Last page available. Max value for page query argument"
},
"perPage": {
"type": "int",
"required": false,
"unique": false,
"description": "Number of items we can found per page"
}
}
}Auction item / lot data structure
Lots API endpoint
/lots?page={page}&per_page={perPage}/lots?page={page}&per_page={perPage}&company={companyId}/lots?page={page}&per_page={perPage}&auction={auctionId}/lots/page/{page}/per_page/{perPage}/auctions/{auctionId}/lots/page/{page}/per_page/{perPage}/companies/{companyId}/auctions/{auctionId}/lots/page/{page}/per_page/{perPage}
If you decide to implement listing-per-company, or listing-per-auction make sure that companyId or/and auctionId passed in companies/auctions feed can be used for filtering in this case too.
Lots API data usage
Lots endpoint allows Aucteeno to automatically import all your auction items/lots (for all companies, if you are providing multiple companies feed, or per-company bases using company query argument, or if you decide to break it by auction, by auction arguments). Pagination rules are applied, or you can ship all auctions items/lots in one feed (this might be suboptimal if you have high number of entries). If sale object is provided we can keep showing winning bid value even after bidding is expired. If you provide bidding prices, we can display current bidding price on the page, while auction is still ongoing.
Lots API preferred data structure
{
"lots": [
{
"lotId": {
"type": "int|string",
"required": true,
"unique": true,
"description": "Unique ID of auction item/lot on your bidding platform"
},
"auctionId": {
"type": "int|string",
"required": true,
"unique": true,
"description": "Unique ID of auction on your bidding platform"
},
"companyId": {
"type": "int|string",
"required": false,
"unique": true,
"description": "UniqueID of company on your bidding platform. Applicable only in case of multi-company setup."
},
"lotNo": {
"type": "int|string",
"required": false,
"unique": false,
"description": "Lot number of item/lot (1, 2, 3, 1A, or code) on your bidding platform"
},
"type": {
"type": "string",
"required": true,
"unique": false,
"description": "Auction item/lot type on your bidding platform. Accepted values are ONLINE, TIMED, LIVE"
},
"title": {
"type": "string",
"required": true,
"unique": false,
"description": "Item/lot title on your bidding platform."
},
"externalUrl": {
"type": "string",
"required": true,
"unique": true,
"description": "Link to auction on your bidding platform."
},
"description": {
"type": "string",
"required": false,
"unique": false,
"description": "Item/lot description text on your bidding platform."
},
"bidding": {
"startsAtUtc": {
"type": "datetime|int",
"required": false,
"unique": false,
"description": "Auction bidding start UTC time on your bidding platform. Can be timestamp format in ISO8601 format (2005-08-15T15:52:01+0000) or unixtime (number of seconds since 1970-01-01T00:00:00-00:00). If left out, start time of auction will be set to the moment of import."
},
"endsAtUtc": {
"type": "datetime|int",
"required": true,
"unique": false,
"description": "Auction bidding end UTC time on your bidding platform. Can be timestamp format in ISO8601 format (2005-08-15T15:52:01+0000) or unixtime (number of seconds since 1970-01-01T00:00:00-00:00)."
},
"startsAt": {
"type": "datetime|int",
"required": false,
"unique": false,
"description": "Auction bidding start local time on your bidding platform. Can be timestamp format in ISO8601 format (2005-08-15T15:52:01+0000) or unixtime (number of seconds since 1970-01-01T00:00:00-00:00). If left out, start time of auction will be set to the moment of import."
},
"endsAt": {
"type": "datetime|int",
"required": false,
"unique": false,
"description": "Auction bidding end local time on your bidding platform. Can be timestamp format in ISO8601 format (2005-08-15T15:52:01+0000) or unixtime (number of seconds since 1970-01-01T00:00:00-00:00)."
},
"currency": {
"type": "string",
"required": true,
"unique": false,
"description": "Bidding currency in 3 letter format (CAD, USD, EUR)."
},
"AskingBid": {
"type": "float",
"required": false,
"unique": false,
"description": "Item/lot asking bid."
},
"CurrentBid": {
"type": "float",
"required": false,
"unique": false,
"description": "Item/lot current bid."
}
},
"sale": {
"soldAtUtc": {
"type": "datetime|int",
"required": false,
"unique": false,
"description": "Item sold time in UTC timezone on your bidding platform. Can be timestamp format in ISO8601 format (2005-08-15T15:52:01+0000) or unixtime (number of seconds since 1970-01-01T00:00:00-00:00)."
},
"soldAt": {
"type": "datetime|int",
"required": false,
"unique": false,
"description": "Item sold time in local timezone on your bidding platform. Can be timestamp format in ISO8601 format (2005-08-15T15:52:01+0000) or unixtime (number of seconds since 1970-01-01T00:00:00-00:00)."
},
"soldPrice": {
"type": "float",
"required": false,
"unique": false,
"description": "Item/lot winning bid."
}
},
"media": [
{
"url": {
"type": "string",
"required": true,
"unique": false,
"description": "Item/lot photo link."
},
"caption": {
"type": "string",
"required": false,
"unique": false,
"description": "Item/lot photo caption to be displayed. If not provided automatically will be generated from item/lot title."
},
"order": {
"type": "int" ,
"required": false,
"unique": false,
"description": "Item/lot photo order value. If not provided order will match order given in list of media items."
}
}
],
"location": {
"country": {
"type": "string",
"required": true,
"unique": false,
"description": "Company location country in ISO 3166-1 standard Alpha 2 format (ex. US/CA/DE/NL)"
},
"subdivision": {
"type": "string",
"required": true,
"unique": false,
"description": "Company location subdivision (state/province) in ISO 3166-2 standard (ex. US-CA, US-TX, CA-MB)"
},
"city": {
"type": "string",
"required": true,
"unique": false,
"description": "Company location city"
},
"postal_code": {
"type": "string",
"required": true,
"unique": false,
"description": "Company location postal/zip code"
},
"address": {
"type": "string",
"required": false,
"unique": false,
"description": "Company location postal/zip code"
},
"address2": {
"type": "string",
"required": false,
"unique": false,
"description": "Company location postal/zip code"
}
}
}
],
"pagination": {
"currentPage": {
"type": "int",
"required": true,
"unique": false,
"description": "Current page listed"
},
"maxPage": {
"type": "int",
"required": true,
"unique": false,
"description": "Last page available. Max value for page query argument"
},
"perPage": {
"type": "int",
"required": false,
"unique": false,
"description": "Number of items we can found per page"
}
}
}Backlinks tracking / Syndication arguments
All links sent back to your website will be enhanced with 3 additional URL query arguments.
Every externalUrl attribute will be enhanced to contain utm_source, utm_medium and utm_campaign
utm_sourcealways has value ofaucteenoutm_mediumalways has value ofsyndicationutm_campaignwill change based on publisher, and our developers will let you know what yours is
https://yourwebsite.com/auction/123will become
https://yourwebsite.com/auction/123?utm_source=aucteeno&utm_medium=syndication&utm_campaign=companyIf your URLs already contain query args, we will simply append them
https://yourwebsite.com/?type=auction&id=123will become
https://yourwebsite.com?type=auction&id=123&utm_source=aucteeno&utm_medium=syndication&utm_campaign=company