Topsort

Topsort Endpoints API Reference (2.0.0)

Download OpenAPI specification:Download

E-mail: wicha@topsort.com License: Apache 2.0

Auctions

An auction determines which products should be promoted based on the vendors' bids.

Create new auctions

SecurityBearerAuth
Request
Request Body schema: application/json

The information describing what will be auctioned. Topsort will run an auction for each batched auction request, for which products, brands and/or vendors' bids will compete against each other. Provided fields are additive, in the sense that only bids that match all filtering fields are considered (e.g. in the example below, only bids for products in the c_yogurt category that match the "Noosa Peach" search string will participate in the acution).

required
Array of any (AuctionRequest) [ 1 .. 5 ] items
Responses
201

The auction results. The list of winners will contain at most slots entries per auction. It may contain fewer or no entries at all if there aren't enough products with usable bids, that is, a bid amount greater than the reserve price and belonging to a campaign with enough remaining budget. Bids become unusable if campaign budget is exhausted, the bid is disqualified to preserve spend pacing, etc.

400

HTTP status codes as registered with IANA.

401

Access token is missing or invalid

402

A monthly invoice has been issued and payment is late

post/auctions
Request samples
application/json
{
  • "auctions": [
    ]
}
Response samples
application/json
{
  • "results": [
    ]
}

Events

Significant consumer interactions on the marketplace app.

Report events

SecurityBearerAuth
Request
Request Body schema: application/json

Use the /events endpoint to notify Topsort about significant consumer interactions on the marketplace app: impressions — ad promotions become visible to the consumer; clicks — the consumer clicks on an ad promotion; and purchases — the consumer buys some products.

non-empty
Array of objects (Impression) [ 1 .. 50 ] items
Array of objects (Click) [ 1 .. 50 ] items
Array of objects (Purchase) [ 1 .. 50 ] items
Responses
204

All events were reported successfully.

400

HTTP status codes as registered with IANA.

401

Access token is missing or invalid

post/events
Request samples
application/json
{ }
Response samples
application/json
{}

All Models

AssetSource

A source available for an asset (banner or video).

url
required
string <uri>

A vendor provided asset that the marketplace has to use as a banner. The asset will be served by Topsort's CDN.

{}

Auction

required
Array of objects (Winner)

Array of winner objects in order from highest to lowest bid. It will be empty if there were no qualifying bids or if there was an error.

error
required
boolean

A boolean indicating whether this auction was resolved successfully.

{
  • "winners": [
    ],
  • "error": false
}

Auctions Request (Banners)

Describes the intent of running a banner ads auction. Only one field between category and searchQuery must be provided.

type
required
string

Discriminator for the type of auction.

Value: "banners"
slots
required
integer <int32> >= 1

Specifies the maximum number of auction winners that should be returned.

object (Category)

An object describing the category of the bids that will participate in an auction.

searchQuery
string

The search string provided by a user.

device
string (Device)
Default: "desktop"

The device for which the ads are meant for.

Enum: "desktop" "mobile"
aspectRatio
required
string^\d+:\d+$

The aspect ratio for a specific slot for a banner placement in the marketplace app. The aspect ratio for the category (or home page, if no category ID was provided in the request) must have been previously set up in the Topsort app.

{
  • "type": "banners",
  • "slots": 1,
  • "aspectRatio": "4:1",
  • "category": {
    }
}

Auctions Request (Sponsored Listings)

Describes the intent of running a sponsored listings auction. At least one of the following fields must be set: category, products.

type
required
string

Discriminator for the type of auction.

Value: "listings"
slots
required
integer <int32> >= 1

Specifies the maximum number of auction winners that should be returned.

required
object (Products)
object (GeoTargeting)

An object describing geographical information associated with this auction.

{
  • "type": "listings",
  • "slots": 2,
  • "products": {
    },
  • "geoTargeting": {
    }
}

Category

An object describing the category of the bids that will participate in an auction.

id
required
string

The marketplace's ID of the category for which an auction will be run.

{
  • "id": "c_yogurt"
}

Click

A click is sent to Topsort when the consumer has clicked on an ad. Topsort charges the vendor and pays the marketplace for clicks on ads in promoted placements on the marketplace app.

resolvedBidId
string

If the click is over an ad promotion, this is the resolvedBidId field received from the /auctions request.

object (Placement)
occurredAt
required
string <date-time>

RFC3339 formatted timestamp including UTC offset.

opaqueUserId
required
string

The opaque user ID allows correlating user activity, whether or not they are actually logged in. It must be long lived.

id
required
string

The marketplace's unique ID for the click. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no click model on the marketplace side, generate a unique string that does not change if the event is resent.

{
  • "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
  • "placement": {
    },
  • "occurredAt": "2009-01-01T12:59:59-05:00",
  • "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
  • "id": "b39d39ed-ea0e-4059-9d15-4990b39c85a2"
}

Error

errCode
required
string

A short string uniquely identifying the problem.

Enum: "bad_request" "empty_request" "internal_server_error" "invalid_api_key" "invalid_auction_id" "invalid_event_type" "invalid_promotion_type" "invalid_session" "missing_aspect_ratio" "missing_auctions" "missing_context" "missing_placement" "missing_product_id" "missing_promotion_type" "missing_purchased_at" "missing_session" "missing_slots" "no_products" "no_purchase_items" "purchase_item_quantity_less_or_equal_than_zero" "resolved_bid_id_not_found" "too_few_impressions" "too_few_slots" "too_many_auctions"
docUrl
string <uri>

A link to a documentation page providing more information about the error.

message
string

Human-readable explanation of or details about the error. The string for a given error may change over time; code should not parse or dispatch based on particular values for this field.

{}

Events Request

Array of objects (Impression) [ 1 .. 50 ] items
Array of objects (Click) [ 1 .. 50 ] items
Array of objects (Purchase) [ 1 .. 50 ] items
{
  • "impressions": [
    ],
  • "clicks": [
    ],
  • "purchases": [
    ]
}

Geotargeting

An object describing geographical information associated with this auction.

location
required
string

The location this banner is being run for.

{
  • "location": "string"
}

Impression

An impression means an ad has become visible to the consumer. In case you cannot send an impression when the product becomes visible, send us an impression event when the product was rendered in the HTML or, if that's also not possible, when your API returns the results. It is important to select the most specific event so that your vendors have more accurate CTR metrics, which will allow them to better predict their campaigns.

resolvedBidId
string

If the impression is over an ad promotion, this is the resolvedBidId field received from the /auctions request.

object (Placement)
occurredAt
required
string <date-time>

RFC3339 formatted timestamp including UTC offset.

opaqueUserId
required
string

The opaque user ID allows correlating user activity, whether or not they are actually logged in. It must be long lived.

id
required
string

The marketplace's unique ID for the impression. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no impression model on the marketplace side, generate a unique string that does not change if the event is resent.

{
  • "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
  • "placement": {
    },
  • "occurredAt": "2009-01-01T12:59:59-05:00",
  • "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
  • "id": "eb874c98-bf4d-40a9-ae6d-fcf4cecb535c"
}

Products

ids
required
Array of strings [ 1 .. 10000 ] items

An array of product IDs that should participate in the auction.

quality_scores
Array of numbers <float> [ 1 .. 10000 ] items

An array of marketplace defined quality scores, each corresponding to the product ID with matching array index. If given, these values will be combined with our internal quality scores to provide a score that better represents the relevance of the participating products. Note that the length of this array must be the same as the length of the ids array and that the values must be between 0 and 1.

{
  • "ids": [
    ],
  • "quality_scores": [
    ]
}

Purchase

A purchase is sent to Topsort once a marketplace customer places an order. These events are used to measure the effectiveness of an ad campaign.

occurredAt
required
string <date-time>

RFC3339 formatted timestamp, including UTC offset, of the instant in which the order was placed.

opaqueUserId
required
string

The opaque user ID allows correlating user activity, whether or not they are actually logged in. It must be long lived.

required
Array of objects (PurchaseItem) non-empty

Items purchased.

id
required
string

The marketplace unique ID for the order. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no unique ID for orders on the marketplace side, generate a unique string that does not change if the event is resent.

{
  • "occurredAt": "2021-10-12T07:20:50.52Z",
  • "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
  • "items": [
    ],
  • "id": "0e06c899-b2cd-4e0d-b0de-8aefb4b6d0a0"
}

Purchase Item

productId
required
string

The marketplace ID of the product being purchased.

quantity
integer >= 1
Default: 1

Count of products purchased.

unitPrice
required
number <float> > 0

The price of a single item in the marketplace currency.

{
  • "productId": "p_SA0238",
  • "quantity": 2,
  • "unitPrice": 12.95
}

Winner

rank
required
integer <int32> >= 1

Where the product's bid ranked in the auction. One-based, so the product with rank 1 won the auction. In an auction response, the winners array is sorted so rank will match the entry's index.

type
required
string

The type of the winning bid.

Enum: "product" "vendor"
id
required
string

The marketplace's ID of the winning entity, depending on the campaign.

resolvedBidId
required
string

An opaque Topsort ID to be used when this item is interacted with.

Array of objects (AssetSource) non-empty

The list of available sources for an asset (banner or video).

{
  • "rank": 1,
  • "type": "product",
  • "id": "p_Mfk15",
  • "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
  • "asset": []
}