Create Campaign Bids

curl --request POST \
  --url https://api.topsort.com/public/v1/campaign-service/campaigns/{campaign-id}/bids \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "bids": [
    {
      "target": {
        "id": "<string>",
        "type": "product"
      },
      "amount": "<unknown>",
      "location": "Santiago",
      "trigger": {
        "type": "<string>",
        "value": {
          "words": [
            "<string>"
          ],
          "matchType": "exact"
        }
      },
      "triggers": [],
      "formatProperties": {
        "bannerAssets": [
          {
            "dimensions": {
              "width": 123,
              "height": 123
            },
            "url": "<string>",
            "contentType": "image/png",
            "size": 123,
            "assetId": "asset_01j713j64yfsvtj4bs3ccpy5ca",
            "content": {},
            "jsonTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          }
        ],
        "slotId": "<string>",
        "adFormat": "<string>",
        "deviceType": "desktop"
      }
    }
  ]
}
'

{
  "hasMore": true,
  "bids": [
    {
      "bidId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "target": {
        "id": "<string>",
        "type": "product"
      },
      "isActive": true,
      "triggers": [
        {
          "type": "<string>",
          "value": {
            "words": [
              "<string>"
            ],
            "matchType": "exact"
          }
        }
      ],
      "campaignId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "state": "active",
      "amount": "<unknown>",
      "trigger": {
        "type": "<string>",
        "value": {
          "words": [
            "<string>"
          ],
          "matchType": "exact"
        }
      },
      "location": "Santiago",
      "bidsBehaviorData": "<string>",
      "formatProperties": {
        "bannerAssets": [
          {
            "dimensions": {
              "width": 123,
              "height": 123
            },
            "url": "<string>",
            "contentType": "image/png",
            "size": 123,
            "assetId": "asset_01j713j64yfsvtj4bs3ccpy5ca",
            "content": {},
            "jsonTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          }
        ],
        "slotId": "<string>",
        "adFormat": "<string>",
        "deviceType": "desktop"
      }
    }
  ],
  "next": {
    "offset": 123,
    "limit": 123
  }
}

POST

public

campaign-service

campaigns

{campaign-id}

bids

Create Campaign Bids

curl --request POST \
  --url https://api.topsort.com/public/v1/campaign-service/campaigns/{campaign-id}/bids \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "bids": [
    {
      "target": {
        "id": "<string>",
        "type": "product"
      },
      "amount": "<unknown>",
      "location": "Santiago",
      "trigger": {
        "type": "<string>",
        "value": {
          "words": [
            "<string>"
          ],
          "matchType": "exact"
        }
      },
      "triggers": [],
      "formatProperties": {
        "bannerAssets": [
          {
            "dimensions": {
              "width": 123,
              "height": 123
            },
            "url": "<string>",
            "contentType": "image/png",
            "size": 123,
            "assetId": "asset_01j713j64yfsvtj4bs3ccpy5ca",
            "content": {},
            "jsonTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          }
        ],
        "slotId": "<string>",
        "adFormat": "<string>",
        "deviceType": "desktop"
      }
    }
  ]
}
'

{
  "hasMore": true,
  "bids": [
    {
      "bidId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "target": {
        "id": "<string>",
        "type": "product"
      },
      "isActive": true,
      "triggers": [
        {
          "type": "<string>",
          "value": {
            "words": [
              "<string>"
            ],
            "matchType": "exact"
          }
        }
      ],
      "campaignId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "state": "active",
      "amount": "<unknown>",
      "trigger": {
        "type": "<string>",
        "value": {
          "words": [
            "<string>"
          ],
          "matchType": "exact"
        }
      },
      "location": "Santiago",
      "bidsBehaviorData": "<string>",
      "formatProperties": {
        "bannerAssets": [
          {
            "dimensions": {
              "width": 123,
              "height": 123
            },
            "url": "<string>",
            "contentType": "image/png",
            "size": 123,
            "assetId": "asset_01j713j64yfsvtj4bs3ccpy5ca",
            "content": {},
            "jsonTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          }
        ],
        "slotId": "<string>",
        "adFormat": "<string>",
        "deviceType": "desktop"
      }
    }
  ],
  "next": {
    "offset": 123,
    "limit": 123
  }
}

Authorizations

Authorization

string

header

required

A valid API key generated in Topsort's UI.

Path Parameters

campaign-id

string<uuid>

required

The ID of the campaign.

Query Parameters

skip_existing_bids

boolean

default:false

Skip creating bids that already exist. Existing bids will not be updated and will not be returned in the response.

Body

application/json

bids

BidCreate · object[]

required

An array of bids to be created.

Required array length: 1 - 500 elements

Show child attributes

bids.target

Entity · object

required

Represents a promotable entity that will be returned upon a winning auction.

Show child attributes

bids.target.id

string

required

The unique ID of the entity.

Required string length: 1 - 256

bids.target.type

enum<string>

required

The type of the entity to be advertised.

Available options:

product,

brand,

vendor,

url

bids.amount

any

bids.location

string | null

By using this option you will be able to target this campaign to a specific group.You must define the same location as a parameter on the auction request. Products on a specific campaign will have specific conversion rates, considering the context of location, so it will not interfere with the conversion rates for the same product in other campaigns.

Minimum string length: 1

Example:

"Santiago"

bids.trigger

KeywordTrigger · object

deprecated

The object that triggers the appearance of this bid on an auction.

Show child attributes

bids.trigger.type

string

required

Allowed value: "keyword"

bids.trigger.value

Value · object

required

Show child attributes

bids.trigger.value.words

string[]

required

The list of keywords.

bids.trigger.value.matchType

enum<string>

required

Available options:

exact,

phrase

bids.triggers

A list of objects that trigger the appearance of this bid on an auction.

Minimum array length: 1

When should this bid participate in an auction.

Show child attributes

bids.triggers.type

string

required

Allowed value: "keyword"

bids.triggers.value

Value · object

required

Show child attributes

bids.triggers.value.words

string[]

required

The list of keywords.

bids.triggers.value.matchType

enum<string>

required

Available options:

exact,

phrase

bids.formatProperties

BannerAd · object

The format properties of the bid. This field is required for banner ads. Should be not set for listing ads.

Show child attributes

bids.formatProperties.bannerAssets

BannerAsset · object[]

required

The assets for the banner campaign, if adFormat is banner.

Minimum array length: 1

Show child attributes

bids.formatProperties.bannerAssets.dimensions

Dimensions · object

required

The width and height of an asset.

Show child attributes

bids.formatProperties.bannerAssets.dimensions.width

integer

required

The width of the image.

bids.formatProperties.bannerAssets.dimensions.height

integer

required

The height of the image.

bids.formatProperties.bannerAssets.url

string<uri> | null

The url where the asset is located. If asset_id is provided, this field will be ignored.

Required string length: 1 - 2083

bids.formatProperties.bannerAssets.contentType

string | null

The mime type of the asset. If asset_id is provided, this field will be ignored.

Minimum string length: 1

Example:

"image/png"

bids.formatProperties.bannerAssets.size

integer | null

The file size of the asset, in bytes. If asset_id is provided, this field will be ignored.

bids.formatProperties.bannerAssets.assetId

string | null

Asset id, if created using the asset API.

Maximum string length: 33

Example:

"asset_01j713j64yfsvtj4bs3ccpy5ca"

bids.formatProperties.bannerAssets.content

Content · object

Custom additional metadata about the banner. If provided, the asset_id and url fields will be ignored. Maximum size is 20KB when serialized.

Show child attributes

bids.formatProperties.bannerAssets.content.{key}

bids.formatProperties.bannerAssets.jsonTemplateId

string<uuid> | null

The id of the json template that was used to create the json content.

bids.formatProperties.slotId

string

required

The external slot id provided by the marketplace.

Minimum string length: 1

bids.formatProperties.adFormat

string

required

Allowed value: "banner"

bids.formatProperties.deviceType

enum<string>

default:desktop

The targeted device for this campaign, if adFormat is banner.

Available options:

mobile,

desktop

Response

Successful Response

The public response body of the bids endpoints.

hasMore

boolean

required

Whether this is the last page of results or not.

bids

Bid · object[]

required

An array of bids.

Maximum array length: 500

Show child attributes

bids.bidId

string<uuid>

required

The ID of the bid

bids.target

Entity · object

required

The type of entity this bid will be targeting.

Show child attributes

bids.target.id

string

required

The unique ID of the entity.

Required string length: 1 - 256

bids.target.type

enum<string>

required

The type of the entity to be advertised.

Available options:

product,

brand,

vendor,

url

bids.isActive

boolean

required

Whether the bid is active.

bids.triggers

required

A list of objects that trigger the appearance of this bid on an auction.

When should this bid participate in an auction.

Show child attributes

bids.triggers.type

string

required

Allowed value: "keyword"

bids.triggers.value

Value · object

required

Show child attributes

bids.triggers.value.words

string[]

required

The list of keywords.

bids.triggers.value.matchType

enum<string>

required

Available options:

exact,

phrase

bids.campaignId

string<uuid>

required

The ID of the campaign.

bids.state

enum<string>

required

The activity state of the bid.

Available options:

active,

deactivated_manually,

inactive_entity,

deleted_entity,

legacy_inactive

bids.amount

any

bids.trigger

KeywordTrigger · object

deprecated

An object that triggers the appearance of this bid on an auction.

Show child attributes

bids.trigger.type

string

required

Allowed value: "keyword"

bids.trigger.value

Value · object

required

Show child attributes

bids.trigger.value.words

string[]

required

The list of keywords.

bids.trigger.value.matchType

enum<string>

required

Available options:

exact,

phrase

bids.location

string | null

Minimum string length: 1

Example:

"Santiago"

bids.bidsBehaviorData

string | null

deprecated

Deprecated. This field is always null. For behavioral data use reporting service.

bids.formatProperties

BannerAd · object

Show child attributes

bids.formatProperties.bannerAssets

BannerAsset · object[]

required

The assets for the banner campaign, if adFormat is banner.

Minimum array length: 1

Show child attributes

bids.formatProperties.bannerAssets.dimensions

Dimensions · object

required

The width and height of an asset.

Show child attributes

bids.formatProperties.bannerAssets.dimensions.width

integer

required

The width of the image.

bids.formatProperties.bannerAssets.dimensions.height

integer

required

The height of the image.

bids.formatProperties.bannerAssets.url

string<uri> | null

The url where the asset is located. If asset_id is provided, this field will be ignored.

Required string length: 1 - 2083

bids.formatProperties.bannerAssets.contentType

string | null

The mime type of the asset. If asset_id is provided, this field will be ignored.

Minimum string length: 1

Example:

"image/png"

bids.formatProperties.bannerAssets.size

integer | null

The file size of the asset, in bytes. If asset_id is provided, this field will be ignored.

bids.formatProperties.bannerAssets.assetId

string | null

Asset id, if created using the asset API.

Maximum string length: 33

Example:

"asset_01j713j64yfsvtj4bs3ccpy5ca"

bids.formatProperties.bannerAssets.content

Content · object

Custom additional metadata about the banner. If provided, the asset_id and url fields will be ignored. Maximum size is 20KB when serialized.

Show child attributes

bids.formatProperties.bannerAssets.content.{key}

bids.formatProperties.bannerAssets.jsonTemplateId

string<uuid> | null

The id of the json template that was used to create the json content.

bids.formatProperties.slotId

string

required

The external slot id provided by the marketplace.

Minimum string length: 1

bids.formatProperties.adFormat

string

required

Allowed value: "banner"

bids.formatProperties.deviceType

enum<string>

default:desktop

The targeted device for this campaign, if adFormat is banner.

Available options:

mobile,

desktop

Next · object

The parameters that should be used to fetch the next page.

Show child attributes

next.offset

integer<int32>

required

How many items to skip from the beginning of the list.

next.limit

integer<int32>

required

How many items to return.

Get Campaign Bids Delete All Bids From A Campaign

⌘I

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

Create Campaign Bids

Authorizations

Path Parameters

Query Parameters

Body

Response