Campaign API - Sponsored Listings Enhancements

Ad Server Update

The Campaign API has been enhanced to support audience targeting and frequency capping for Sponsored Listings campaigns, giving developers programmatic access to advanced campaign controls.

Key Enhancements

Audience Targeting

Apply user segment filters to include or exclude specific audiences from your sponsored listings campaigns.

Frequency Capping

Control how often users see your ads within a specific timeframe to prevent ad fatigue.

Audience Targeting via API

Configure audience segments and bid multipliers during campaign creation:

Create Campaign with Audience Targeting

curl --request POST \
  --url https://api.topsort.com/public/v1/campaign-service/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "adFormat": "listing",
  "name": "Targeted Sponsored Listing",
  "campaignType": "manual",
  "chargeType": "CPC",
  "budget": {
    "amount": 1000,
    "type": "daily"
  },
  "targetingFilters": {
    "isActive": true,
    "targetingFilters": [
      {
        "segmentId": "DFJ9R4",
        "type": "user_segment"
      },
      {
        "segmentId": "984103",
        "type": "user_segment"
      }
    ]
  },
  "multiplierConfig": {
    "isActive": true,
    "multipliers": [
      {
        "multiplier": 2.5,
        "segmentId": "DFJ9R4",
        "type": "user_segment"
      }
    ]
  }
}'

The audience targeting configuration supports up to three segments with OR logic and bid multipliers between 1.0x and 5.0x for boosting strategies.

Frequency Cap via API

Configure impression limits using the campaign restrictions endpoint:

Create Frequency Cap

curl --request POST \
  --url https://api.topsort.com/public/v1/campaign-service/campaigns/{campaign-id}/restrictions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "limit": 10,
  "restrictionTypeId": 1
}'

Response

{
  "campaignId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "2025-08-13T05:31:56Z",
  "id": 123,
  "limit": 10,
  "marketplaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "restrictionType": {
    "frequencyType": "daily",
    "id": 1,
    "interactionType": "impressions",
    "level": "campaign"
  },
  "status": "active",
  "updatedAt": "2025-08-13T05:31:56Z"
}

Retrieve existing frequency caps for a campaign:

Get Campaign Restrictions

curl --request GET \
  --url https://api.topsort.com/public/v1/campaign-service/campaigns/{campaign-id}/restrictions \
  --header 'Authorization: Bearer <token>'

---

These enhancements are now live in the Campaign API. To learn more, check out the Campaign API reference.