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"
      }
    ]
  }'

Our Products

Explore Topsort’s core components designed to power your retail media business:

Ad Platform

Comprehensive solution for launching and managing your advertising business with campaigns, reports, and integrations.

Ad Server

Powerful APIs for customizing ads and integrating with existing systems. Control relevance, targeting, and performance.

Ad Intelligence

Smart tools for forecasting, retrieval, and attribution to enhance your ad system with AI-powered insights.

Toppie

DSP for advertising agencies and brands to manage campaigns across multiple retailers with real-time data.

Client Libraries

We provide client libraries to help you get started quickly:

Topsort.js

Client-side JavaScript SDK

Analytics.js

Analytics tracking library

Topsort.kt

Kotlin SDK for Android

PHP SDK

Server-side PHP library

Banners.js

Banner ad integration library

Topsort.swift

Swift SDK for iOS

Learn More

Not sure where to begin? Learn about the fundamental components:

The Catalog

Manage your product inventory

Banners

Create and manage banner campaigns

Listings

Auctions

Understand auction mechanics

Events

Track impressions and conversions

General

Auction examples

Webhook examples

Auctions

Events

Toptimize

Toppie API

Campaign API

Catalog API

Billing API

Reporting API

Invitation API

User API

Webhooks API

Assets API

Segments Service

Offsite Ads API

Forecasting Service

Media API

API Reference

​Developer Documentation

​Two Integration Paths — Mix and Match as Necessary

Low Code

API Driven

​Try It Out

​Our Products

Ad Platform

Ad Server

Ad Intelligence

Toppie

​Client Libraries

Topsort.js

Analytics.js

Topsort.kt

PHP SDK

Banners.js

Topsort.swift

​Learn More

The Catalog

Banners

Listings

Auctions

Events

Developer Documentation

Two Integration Paths — Mix and Match as Necessary

Try It Out

Our Products

Client Libraries

Learn More