v1 migration guide
This guide supports Topsort users that still use either the /v1/auctions
or /v1/events
endpoints with migrating to the new endpoints.
If you are new to Topsort, please refer to the V2 Docs.
Notable new features
The v2
endpoints have many new features over v1
, surpassing it both in usability and performance.
Some of the new features in v2
include:
- Auctions
- Sponsored Brands
- Sponsored Banners
- Keyword-based targeting
- Category-based targeting
- Location Segmentation
- Audience Segmentation
- Batching up to 5 auctions in one request.
- No session needed
- Events
- Batching
- No session needed
- Banner attribution
Migration steps
Auctions
1. Update the API endpoint
The V2 API endpoint is https://api.topsort.com/v2/auctions
.
2. Update the request body
The request body structure has changed. Refer to the V2 Docs for the new structure.
Example V1 request body:
Gets updated to V2 request body:
The changes are the following:
auctions
array replaces the root object.type
field is added to specify the auction type.listings
, andbanners
are supported.products
object replaces theproducts
array.quality
field is replaced byqualityScores
array.geoTargeting
object stays the same.session
object is removed. No session is needed in V2.
3. Update the response
The response structure has changed. Refer to the V2 Docs for the new structure.
Example V1 response:
Example V2 response:
The changes are the following:
results
array replaces the root object.resultType
field is added to specify the auction type.listings
, andbanners
are supported, depends on the request.productId
field is replaced byid
.winnerType
field is replaced bytype
.auctionId
is removed in favor ofresolvedBidId
.campaignId
is added to specify the winning campaign
Events
1. Update the API endpoint
The V2 API endpoint is https://api.topsort.com/v2/events
.
2. Update the request body
The request body structure has changed. Refer to the V2 Docs for the new structure.
Example V1 request body:
Gets updated to V2 request body:
The changes are the following:
clicks
,impressions
, andpurchases
arrays replace the root object.eventType
field is removed. The event type is specified by the array name.entity
object replaces theproductId
field. Now an event can be related to a product, a vendor or a brand.auctionId
field is removed in favor of theresolvedBidId
.opaqueUserId
field is added replacing thesession
object.- Purchases don’t need to specify neither
auctionId
norresolvedBidId
anymore.