Campaigns

First, read about authorization, error handling and pagination.

Campaign

Fetch campaign list

GET /api/v2/campaigns

Fetch campaigns. Response uses Pagination.

Query Parameters:

• limit – (optional) maximal number of campaigns per page

Request Headers:

• Content-Type – application/json

Status Codes:

• 200 OK – no error

Response JSON Object:

• data (Campaign[]) – campaign list

Fetch campaign

GET /api/v2/campaigns/(id)

Fetch campaign by ID.

Parameters:

• id – campaign ID

Request Headers:

• Content-Type – application/json

Status Codes:

• 200 OK – no error

• 404 Not Found – campaign not found

Response JSON Object:

• data (Campaign) – campaign

Add campaign

POST /api/v2/campaigns

Add campaign.

Request Headers:

• Content-Type – application/json

Status Codes:

• 200 OK – no error

• 422 Unprocessable Entity – validation error

Request JSON Object:

• status (string) – status

• name (string) – name

• targetUrl (string) – landing URL

• maxCpc (float, null) – maximal CPC in USD

• maxCpm (float, null) – maximal CPM in USD, null for automatic

• budget (float) – budget in USD

• medium (string) – medium

• vendor (string, null) – vendor

• dateStart (string) – date of start in ISO 8601 format

• dateEnd (string, null) – date of end in ISO 8601 format, null for interminable campaign

• campaign.targeting (CampaignTargeting) – targeting (required and forbidden features)

• campaign.creatives (CreativeInput[]) – creatives

Response JSON Object:

• data (Campaign) – campaign

Edit campaign

POST /api/v2/campaigns/(id)

Edit campaign.

Parameters:

• id – campaign ID

Request Headers:

• Content-Type – application/json

Status Codes:

• 200 OK – no error

• 422 Unprocessable Entity – validation error

Request JSON Object:

• status (string) – (optional) status

• name (string) – (optional) name

• targetUrl (string) – (optional) landing URL

• maxCpc (float, null) – (optional) maximal CPC in USD

• maxCpm (float, null) – (optional) maximal CPM in USD, null for automatic

• budget (float) – (optional) budget in USD

• dateStart (string) – (optional) date of start in ISO 8601 format

• dateEnd (string, null) – (optional) date of end in ISO 8601 format, null for interminable campaign

• campaign.targeting (CampaignTargeting) – (optional) targeting (required and forbidden features)

• bidStrategyUuid (string) – (optional) bid strategy UUID

Delete campaign

DELETE /api/v2/campaigns/(id)

Delete campaign by ID.

Parameters:

• id – campaign ID

Status Codes:

• 200 OK – no error

• 404 Not Found – campaign not found

Response JSON Object:

• data – empty array

Creative

Upload creative

POST /api/v2/campaigns/creative

Upload creative.

Request Headers:

• Content-Type – multipart/form-data

Form Parameters:

• binary file – file

• string medium – medium ID

• string vendor – (optional) vendor ID

• string type – type

• string scope – (optional) scope, required if cannot be determined automatically, e.g. HTML creatives

Status Codes:

• 200 OK – no error

• 422 Unprocessable Entity – validation error

Response JSON Object:

• data.id (string) – file ID

• data.url (string) – temporary URL. Can be used for preview

Fetch creative list

GET /api/v2/campaigns/(campaignId)/creatives

Fetch creatives. Response uses Pagination.

Parameters:

• campaignId – campaign ID

Request Headers:

• Content-Type – application/json

Status Codes:

• 200 OK – no error

Response JSON Object:

• data (Creative[]) – creative list

Fetch creative

GET /api/v2/campaigns/(campaignId)/creatives/(creativeId)

Fetch creative by ID.

Parameters:

• campaignId – campaign ID

• creativeId – creative ID

Request Headers:

• Content-Type – application/json

Status Codes:

• 200 OK – no error

• 404 Not Found – creative not found

Response JSON Object:

• data (Creative) – creative

Add creative

POST /api/v2/campaigns/(campaignId)/creatives

Add creative.

Parameters:

• campaignId – campaign ID

Request Headers:

• Content-Type – application/json

Status Codes:

• 200 OK – no error

• 422 Unprocessable Entity – validation error

Request json object:

creative data (CreativeInput)

Response JSON Object:

• data (Creative) – creative

Edit creative

POST /api/v2/campaigns/(campaignId)/creatives/(creativeId)

Edit creative.

Parameters:

• campaignId – campaign ID

• creativeId – creative ID

Request Headers:

• Content-Type – application/json

Status Codes:

• 200 OK – no error

• 404 Not Found – creative not found

• 422 Unprocessable Entity – validation error

Request JSON Object:

• name (string) – (optional) name

• status (integer) – (optional) status

Response JSON Object:

• data (Creative) – creative

Delete creative

DELETE /api/v2/campaigns/(campaignId)/creatives/(creativeId)

Delete creative.

Parameters:

• campaignId – campaign ID

• creativeId – creative ID

Status Codes:

• 200 OK – no error

• 404 Not Found – creative not found

Response JSON Object:

• data – empty array

Data structures

Campaign status

Campaign status is a string. Campaign can be in one of following states:

• draft - campaign during creation

• inactive - campaign is not active, e.g. stopped

• active - campaign is active

• suspended - campaign suspended, e.g. in case of insufficient funds to run campaign

Creative status

Creative status is a string. Creative can be in one of following states:

• draft - creative during creation

• inactive - creative is not active, will not be displayed

• active - creative is active

• rejected - creative is permanently disabled, e.g. does not comply with terms

Campaign object

• id (string) – campaign ID

• createdAt (string) – date of creation

• updatedAt (string) – date of last update

• secret (string) – conversion secret

• conversionClick (string) – type of click conversion, i.e. none, basic, advanced

• conversionClickLink (string, null) – click conversion callback URL, may be null if click conversion is not set

• classifications[].classifier (string) – classifier

• classifications[].status (string) – classification status

• classifications[].keywords (string) – classification result, conforms taxonomy

• status (string) – status

• name (string) – name

• targetUrl (string) – landing URL

• maxCpc (float, null) – maximal CPC in USD

• maxCpm (float, null) – maximal CPM in USD, null for automatic

• budget (float) – budget in USD

• medium (string) – medium

• vendor (string, null) – vendor

• dateStart (string) – date of start in ISO 8601 format

• dateEnd (string, null) – date of end in ISO 8601 format, null for interminable campaign

• targeting (CampaignTargeting) – required and forbidden features, conforms taxonomy

• creatives (Creative[]) – creative

• bidStrategyUuid (string) – bid strategy UUID

• conversions[].uuid (string) – conversion UUID

• conversions[].name (string) – conversion name

• conversions[].limitType (string) – conversion limit type

• conversions[].eventType (string) – conversion event type

• conversions[].type (string) – conversion type

• conversions[].value (integer) – conversion value

• conversions[].isValueMutable (boolean) – indicates that value can change

• conversions[].cost (integer) – conversion cost

• conversions[].occurrences (integer) – number of conversion occurrences

• conversions[].isRepeatable (boolean) – indicates that conversion can be repeated

• conversions[].link (string) – conversion link

CampaignTargeting object

• requires (Targeting) – required features

• excludes (Targeting) – forbidden features

Targeting object

• user (TargetingFeatures) – (optional) user features

• site (TargetingFeatures) – (optional) site features

• device (TargetingFeatures) – (optional) device features

TargetingFeatures object

TargetingFeatures object has selected features. It is a map in which key is a name of TargetingOption, and value is array of selected items. Both key and value must match taxonomy.

Example

{
    "quality": ["high"],
    "domain": ["example.com"]
    "tag": ["nft", "nft-sports", "nft-tickets"]
}

TargetingOption object

TargetingOption object contains features which campaign can require or forbid.

There are two types:

• dictionary - list of supported values

• custom input - values entered by advertiser

Dictionary targeting object

• type (string) – constant dict

• name (string) – name

• label (string) – label

• items (TargetingDictionary) – possible values

TargetingDictionary object

TargetingDictionary object holds possible values. Usually this is a map, where key is an ID and value is a label (string).

In general it is a nested structure. Key is an ID. Value is an object or a string. If value is an object it has fields:

• label (string) - option label

• values (TargetingDictionary object) - possible values

Example

{
    "type": "dict",
    "name": "tag",
    "label": "Tags",
    "items": {
        "nft": {
            "label": "NFTs",
            "values": {
                "nft-sports": "Sports",
                "nft-tickets": "Tickets"
            }
        }
    }
}

Custom input targeting object

• type (string) – constant input

• name (string) – name

• label (string) – label

Example

{
    "type": "input",
    "name": "domain",
    "label": "Domains"
}

Creative object

• id (string) – ID

• createdAt (string) – date of creation in ISO 8601 format

• updatedAt (string) – date of last update in ISO 8601 format

• type (string) – type

• mime (string) – MIME type

• hash (string) – checksum of content

• scope (string) – scope (size, occupied space)

• name (string) – name

• status (integer) – status

• cdnUrl (string, null) – content URL on CDN, may be null if was not uploaded to CDN

• url (string) – content URL

CreativeInput object

• fileId (string) – file ID taken from upload response

• name (string) – name