Developer Documentation

Develop and scale an auction-based advertising platform in your marketplace.

Intro to Topsort →API Reference →

Two Integration Paths — Mix and Match as Necessary

Low Code

Deals with common use cases and gets you started quickly.

API Driven

For bespoke functionality and advanced use cases.

Try It Out

Explore our API with these common workflows.

1. Upload a product
2. Create a campaign
3. Run an auction
4. Track events

Upload products to your catalog using the Catalog API.

curl --request POST \
  --url https://api.topsort.com/v2/products \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "products": [
      {
        "id": "product-123",
        "name": "Example Product",
        "price": 29.99,
        "imageUrl": "https://example.com/product.jpg",
        "category": "electronics"
      }
    ]
  }'

Create your first advertising campaign.

curl --request POST \
  --url https://api.topsort.com/v2/campaigns \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My First Campaign",
    "budget": 1000,
    "type": "sponsored_listings",
    "startDate": "2024-01-01"
  }'

Request ad placements through the auction system.

curl --request POST \
  --url https://api.topsort.com/v2/auctions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "slots": 3,
    "products": {
      "ids": ["product-123", "product-456"]
    },
    "category": {
      "id": "electronics"
    }
  }'

Track user interactions and conversions.

curl --request POST \
  --url https://api.topsort.com/v2/events \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "events": [
      {
        "type": "click",
        "productId": "product-123",
        "resolvedBidId": "bid-456",
        "occurredAt": "2024-10-12T17:30:00Z"
      }
    ]
  }'