# Feed

This API is only available for feed advertisers. If your account is not a feed account, you will receive an error message when calling this API.

# Object description

Before you start using this API endpoint you should know how a feed object looks. You can find out which fields are mandatory to create a new feed below.

# Feed

# Detailed

Property Type Values Description
feed_id String any Reference to the feed
name String any Display name of the feed
ad_type String pop, ppr POP or PPR traffic for your feed
categories Array adult, non-adult Select if you want to receive requests for non-adult and/or adult traffic on your feed
status String active, paused, archived Define if your feed is active, paused or archived
format String json or xml The response type of your feed
bid_container Array of strings any Depending on your response format: if json this must be an array of strings representing the path to your response container or a single xpath when using xml. See the Response Mapping section below.
bid_path Array of strings any See the Response Mapping section below.
url_path Array of strings any See the Response Mapping section below.
costper Integer 1 or 1000 The costper field indicates the format of your bids. We currently support 1 if you bid per click (e.g. 0.01 for 1 cent) or 1000 if you bid per 1000 clicks (e.g. 234 for $ 0.234). We divide the bid we find in your response by this value.
keywords_per_request Integer 1 or null If your system expects only a single keyword per request you can set this value to 1. Please note that setting this value to 1 will multiply the number of requests sent by the amount of keywords. Therefore we highly recommend you to set this value to null. Please note that the options keyword_formatting and keyword_delimiter do not apply when this value is set to 1.
chance Integer 1 <= chance <= 100 You can limit the amount of traffic sent by our system by setting the chance to a number less than 100. Then every request only has a (random) chance of chance% of being sent to your system.
browsers Black/Whitelisting Object of Browsers When blacklisting, only [] is allowed for an implicit any. Black- or whitelisting browsers.
devices Black/Whitelisting Object of Devices When blacklisting, only [] is allowed for an implicit any. Black- or whitelisting devices.
countries Black/Whitelisting Object of Countries Black- or whitelisting countries.
os Black/Whitelisting Object of Operating Systems When blacklisting, only [] is allowed for an implicit any. Black- or whitelisting operating systems.
url URL-Object The url of your system.
ipv6 Boolean true for dualstack (you will receive ipv4 and ipv6 addresses in the %ip% placeholder) or false (only ipv4)

# Response Mapping

For mapping your feed response, we use different approaches for json and xml.

# JSON

If your response is in JSON format, we expect bid_container, bid_path and url_path to be arrays that represent the path where we find your response:

As an example, when having a response in the following format:

{
  	"results": [
	  	{
		  	"bid": 0.001,
		  	"url": "http://mytrackingdomain.com/?foo=bar"
	  	},
	  	{
		  	"bid": 0.002,
		  	"url": "http://mytrackingdomain.com/?bar=baz"
	  	}
  	]
}

Here, the correct value for bid_container would be ["results"], the value for bid_path would be ["bid"], and the value for url_path would be ["url"].

Another example:

{
  	"nested": {
	  	"object": {
		  	"data": {
			  	"results": [
				  	{
						"data": {
							"bid": 0.001,
							"url": "http://mytrackingdomain.com/?foo=bar"
						}
					}
			  	]
		  	}
	  	}
  	}
}

Here, the correct value for bid_container would be ["nested", "object", "data", "results"], the value for bid_path would be ["data", "bid"], and the value for url_path would be ["data", "url"].

Please note that if you send multiple bids in one response we will only process the bid with the highest cpc. When you only send one bid (i.e. there is no array of bids), the bid_container value is usually empty:

{
	"result": "ok",
	"data": {
		"bid_price": 0.123,
		"click_url": "http://mydomain.com/hello?world=123"
	}
}

Here, the correct value for bid_container would be [], the value for bid_path would be ["data", "bid_price"], and the value for url_path would be ["data", "click_url"].

# XML

When you respond in XML format, we expect the values of bid_container, bid_path and url_path to be arrays with only a single value, this value being an XPath (opens new window) expression.

Some examples:

<results>
    <bids>
        <bid>0.02</bid>
        <url>http://test.url.com/ad?id=1234343242</url>
    </bids>
</path>

Here, the correct value for bid_container would be ["/results/bids"], the value for bid_path would be ["//bid/text()"], and the value for url_path would be ["//url/text()"].

<results>
    <item bid="0.02" url="http://test.url.com/ad?id=1234343242" />
</results>

Here, the correct value for bid_container would be ["/results/item"], the value for bid_path would be ["//@bid"], and the value for url_path would be ["//@url"].

If you are not sure about what values to put here, please do not hesitate and contact support with an example response of your system.

# URL

Property Type Values
scheme String http, https
host String any, supports placeholder and custom params
port Integer 0-63535
path Array any, supports placeholder and custom params
query String Object of key value pairs, see placeholder and custom params
# Placeholders

The host, path and query parameter values support the following placeholders:

Name Placeholder Description
Country %country% Country the visitor is from, e.g. DE, FR, IT.
Device %device% e.g. mobile, desktop, tablet
Ad Type %adtype% Traffics Ad type, e.g. PPR, POP.
Traffic Category %traffic_category% e.g. adult, non-adult
Carrier %carrier% e.g. tmob_de
Browser %browser% e.g. chrome, safari
User Agent %ua% User Agent belonging to the visitor.
IP %ip% IP belonging to the visitor.
Click ID %clickid% Unique identifier for each visitor. Optional but mandatory in case of debug requests on log-level.
Keywords %keywords% Keywords tied to the visitor in the format specified using keyword_formatting and keyword_delimiter.
Operating System %os% e.g. windows, android, macintosh
Source ID %sourceid% Unique identifier that represents the origin of the traffic.
Unique Count %uniquecount% Counter representing how unique the visitor is (min. 1)
X-Forwarded-For %xff% The value of the XFF header (usually set by proxies).
XFF/IP %xff_or_ip% Either XFF if it is set or the IP.
Results %results% How many bids we want in the response (currently always set to 1).

All placeholders are properly url-encoded.

# Custom Parameters

If you want to receive other values than our placeholders support, you can use our custom parameters. Valid custom parameters have the following format:

[if_field, condition_value, then_value, else_value]

This can be useful in the following exemplary cases:

  1. Your system wants a different value for adult/non-adult traffic, e.g. 1 for adult, 0 for non-adult:

-> [traffic_category,non-adult,0,1]

  1. You want to receive a different country code for a specific country, e.g. UK instead of GB for the United Kingdom:

-> [country,GB,UK,%25country%25] (note that we use a placeholder in the else value that will be replaced with the actual country; also note that the placeholder %country% is url-encoded.)

Please note the following points:

  • all values must be properly url-encoded!
  • you cannot nest custom parameters

In case you cannot achieve what you want with placeholders and custom parameters, you can try to split a feed into multiple smaller feeds.

# Targeting

The targeting options all have the same structure:

{
	"type": "whitelist" | "blacklist",
	"items": ["valid", "items", "for", "this", "targeting", "option"]
}

Please note that blacklisting is only allowed for countries. All other targeting options have limited options and only accept blacklisting for the usecase where you do not care and want to accept all values, even new ones that might only appear in the future.

# Browsers

We support the following browser values:

  • firefox
  • safari
  • opera
  • internet_explorer
  • edge
  • edge-chromium
  • chrome
  • others
# Devices

We support the following device values:

  • desktop
  • mobile
  • tablet
# Operating Systems

We support the following os values:

  • android
  • ios
  • blackberry
  • macintosh
  • windows
  • mobile_others
  • desktop_others
  • others

# Feed Creation

Creates a feed with the settings sent in the body:

URL: /feed

Method: POST

Request type: Detailed feed

Response type: Detailed feed

# Mandatory Fields

If you want to reread what each field means, go back to Object Description

If a property is mandatory, there is no default value!

Property Mandatory Default
name
ad_type
categories adult and non-adult
status paused
format
bid_container []
bid_path
url_path
costper 1
keywords_per_request null
chance 100
browsers { "type": "blacklist", "items": [] }
devices { "type": "blacklist", "items": [] }
countries { "type": "blacklist", "items": [] }
os { "type": "blacklist", "items": [] }
url
ipv6 false

Request example

This example creates a new PPR feed:

{
  "name": "My cool PPR feed",
  "ad_type": "ppr",
  "categories": [
    "adult",
	"non-adult"
  ],
  "format": "json",
  "keyword_formatting": "delimiter",
  "keyword_delimiter": ",",
  "bid_container": [],
  "bid_path": [
    "bid"
  ],
  "url_path": [
    "redirecturl"
  ],
  "status": "active",
  "costper": 1,
  "keywords_per_request": null,
  "chance": 100,
  "browsers": {
    "type": "blacklist",
    "items": []
  },
  "devices": {
    "type": "blacklist",
    "items": []
  },
  "carriers": {
    "type": "blacklist",
    "items": []
  },
  "countries": {
    "type": "whitelist",
    "items": ["US", "GB", "DE", "FR"]
  },
  "os": {
    "type": "whitelist",
    "items": ["macintosh", "windows"]
  },
  "url": {
    "scheme": "http",
    "host": "feed.mydomain.com",
    "port": 80,
    "path": "/bids",
    "query": {
      "keywords": "%keywords%",
      "ip": "%ip%",
      "sourceid": "%sourceid%",
      "useragent": "%ua%",
      "clickid": "%clickid%"
    }
  },
  "ipv6": true
}

This will return the same data and the newly created feed id:

{
  "name": "My cool PPR feed",
  "ad_type": "ppr",
  "categories": [
    "adult",
    "non-adult"
  ],
  "format": "json",
  "keyword_formatting": "delimiter",
  "keyword_delimiter": ",",
  "bid_container": [],
  "bid_path": [
    "bid"
  ],
  "url_path": [
    "redirecturl"
  ],
  "status": "active",
  "costper": 1,
  "keywords_per_request": null,
  "chance": 100,
  "browsers": {
    "type": "blacklist",
    "items": []
  },
  "devices": {
    "type": "blacklist",
    "items": []
  },
  "carriers": {
    "type": "blacklist",
    "items": []
  },
  "countries": {
    "type": "whitelist",
    "items": [
      "US",
      "GB",
      "DE",
      "FR"
    ]
  },
  "os": {
    "type": "whitelist",
    "items": [
      "macintosh",
      "windows"
    ]
  },
  "url": {
    "scheme": "http",
    "host": "feed.mydomain.com",
    "port": 80,
    "path": "/bids",
    "query": {
      "keywords": "%keywords%",
      "ip": "%ip%",
      "sourceid": "%sourceid%",
      "useragent": "%ua%",
      "clickid": "%clickid%"
    }
  },
  "ipv6": true,
  "feed_id": "60a246d5bd55ef267f4bf3b2"
}

# Feed Edititing

Updates a feed with properties sent in the body:

URL : /feed/:feedId

Method: PATCH

Request type: Detailed feed

Response type: Detailed feed

Request example

This example changes the status of the feed with the specified id to paused:

{
	"status": "paused"
}

Response Example:

{
  "feed_id": "60a246d5bd55ef267f4bf3b2",
  "name": "My cool PPR feed",
  "ad_type": "ppr",
  "categories": [
    "adult",
    "non-adult"
  ],
  "format": "json",
  "keyword_formatting": "delimiter",
  "keyword_delimiter": ",",
  "bid_container": [],
  "bid_path": [
    "bid"
  ],
  "url_path": [
    "redirecturl"
  ],
  "status": "paused",
  "costper": 1,
  "keywords_per_request": null,
  "chance": 100,
  "countries": {
    "type": "whitelist",
    "items": [
      "DE",
      "FR",
      "GB",
      "US"
    ]
  },
  "os": {
    "type": "whitelist",
    "items": [
      "macintosh",
      "windows"
    ]
  },
  "browsers": {
    "type": "blacklist",
    "items": []
  },
  "devices": {
    "type": "blacklist",
    "items": []
  },
  "carriers": {
    "type": "blacklist",
    "items": []
  },
  "url": {
    "scheme": "http",
    "host": "feed.mydomain.com",
    "port": 80,
    "path": "/bids",
    "query": {
      "keywords": "%keywords%",
      "ip": "%ip%",
      "sourceid": "%sourceid%",
      "useragent": "%ua%",
      "clickid": "%clickid%"
    }
  },
  "ipv6": true
}

Please note that as a temporary measure we currently manually approve all changes of active feeds. This also applies when setting a feed to paused and then changing it back to active. There is one exception though: setting your feed to paused always applies the change immediately*.

*changes can take up to 5 minutes to fully take effect

# Feed Statistics

The feed statistics are provided under the same endpoint as the campaign statistics. Just use the feed id as the campaign id.

Last Updated: 5/26/2021, 1:43:45 PM