Publisher Stats

Getting started with the TrafficHaus Publisher Stats API is easy! This page will guide you through the process, step-by-step.

Get Your Key

Get your API key below. We recommend keeping this hidden in a safe place, as it is just like your password for the API.

API Key:

Get Your Stats

// set up your URL with the appropriate parameters
$params = "?api_key=b59jght6-1kjd-7775-48ed-00259gr3&start_date=2015-07-01&end_date=2015-07-07&zones=98765,98764,98763&geos=AU,CA,GB,US&group_by=site,zone,date,c1&format=1";
$url = "http://admin.traffichaus.com/api/v1/publisher_stats.php" . $params;

// initiate a cURL request and store the result
$s = curl_init();
curl_setopt($s, CURLOPT_URL, $url);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_CUSTOMREQUEST, "GET");

$response = curl_exec($s);

// for this simple example, we'll just echo the response
echo $response;

We offer API access to your stats via simple HTTP GET requests to our server, using query string parameters.

Type	Parameter	Description
string	api_key	Required. This is where you pass in your API Key, this is required with every call to our TrafficHaus server.
string	start_date	Recommended. Specify a start date for the returned stats. Will default to yesterday if omitted. (Note: Selecting too long of a date range may lead to an error, as we limit the size of each request to 100MB or less.)
string	end_date	Recommended. Specify an end date for the returned stats. Will default to yesterday if omitted. (Note: Selecting too long of a date range may lead to an error, as we limit the size of each request to 100MB or less.)
string	zones	Optional. Include a comma-separated list of zone IDs to get a specific subset of your zones, or just omit to get them all.
string	geos	Optional. Include a comma-separated list of 2-letter country codes to get a specific regional subset, or just omit to include all countries.
string	group_by	Optional. By default, we will return your stats grouped by site and zone. You can also choose your own groupings from the following parameters: site, zone, geo, date and c1
int	format	We offer a variety of formats for your convenience: 0 = raw JSON output (default), 1 = formatted output for dataTables, wrapped in a [data] envelope, 2 = extended output (datatables format plus additional [meta] envelope)

Publisher RTB

Add RTB Site

The site you want to receive ads via RTB will need to be explicitly added and enabled after being added in the Sites tab. You can add your site by going to SITES & ZONES -> RTB Sites, clicking the Add RTB Site button and selecting your site from the list.

Notice the Key column in the table. That key is the RTB site identifier you will use as a param on the endpoint you will send RTB requests to.

RTB requests for that site(using that specific key) won't pass through until the site has been enabled(approved) by an admin.

RTB Request Object

Object: bidrequest

Attribute	Required	Description
id	yes	Unique ID of the bid request.
imp	yes	Array of Imp objects representing the impressions offered.
site	yes	Details via a site object about the publisher's website.
device	yes	Details via a device object about the user's device to which the impression will be delivered.
user	no	Details via a user object about the human user of the device.
tmax	no	Maximum time in milliseconds before considering as a request timeout.

Object: imp

Attribute	Required	Description
id	yes	Unique ID of the impression.
banner	only for banner/iframe imps	A banner object.
bidfloor	no; default 0.001	Minimum bid for this impression expressed in CPM.
ext	yes; if using single endpoint	Placeholder for exchange-specific extensions to OpenRTB.

If banner object is not set, the Traffichaus zone will be defaulted to pop-under type (if using single endpoint)

Supported ext attributes

Attribute	Required	Description
th_location	yes; if using single endpoint	The location of the zone the ad is assigned to. Required to be one of the supported Traffichaus locations based on the zone platform type.
th_zone_platform_type	recommended; if using single endpoint	The platform type of the zone the ad is assigned to. Required to be one of the supported Traffichaus platform types.
zone_id	recommended	The zone ID of the publisher's site for which an impression is requested.

Object: site

Attribute	Required	Description
id	no	Unique ID of the requesting site.
domain	recommended	Domain of the site (e.g., "example.com").
page	no	URL of the page where the impression will be shown.
ref	no	Referrer URL that caused navigation to the current page.
cat	no; default IAB25	The IAB content category of the site.
keywords	no	Comma separated list of keywords about the site.
ext	yes; if using single endpoint	Placeholder for exchange-specific extensions to OpenRTB.

Supported ext attributes

Attribute	Required	Description
th_site_key	yes; if using single endpoint	The RTB site key assigned to the site after being added as a RTB Site to Traffichaus.
zone_id	recommended(if not set in imp object's ext data)	The zone ID of the publisher's site for which the impressions are requested.

Object: device

Attribute	Required	Description
ip	recommended	IP address of device.
ua	yes	Browser user agent string.
language	recommended	Device language. Only ISO 639-1 Alpha-2 or Alpha-3 codes.
geo	recommended	Location of the device defined by a geo object .
os	recommended	Device operating system (e.g., "iOS", "Android", "Linux", "Windows").
devicetype	no	The general type of device.
carrier	no	Carrier or ISP (e.g., "VERIZON").
connectiontype	no	The type of connection the device uses(e.g., Ethernet, 2G, 3G, WiFI) - use integer values as given by the official OpenRTR documentation.
ext	no	Placeholder for exchange-specific extensions to OpenRTB.

Object: geo

Attribute	Required	Description
country	recommended	Country code using ISO 3166-1 alpha-2.
ext	no	Placeholder for exchange-specific extensions to OpenRTB.

Object: banner

Attribute	Required	Description
w	yes	Width of the required ad in pixels.
h	yes	Height of the required ad in pixels.

RTB Response Object

Object: bidresponse

Attribute	Required	Description
id	yes	ID of the bid request to which this is a response.
seatbid	yes	Collection of bids made by the bidder on behalf of a specific seat.

Object: seatbid

Attribute	Required	Description
bid	yes	Array of 1+bid objects each related to an impression. Multiple bids can relate to the same impression.

Object: bid

Attribute	Required	Description
id	yes	Bidder generated bid ID.
impid	yes	ID of the imp object in the related bid request.
price	yes	Bid price expressed as CPM.
nurl	yes	Win notice URL called by the exchange if the bid wins.
adm	yes	The XML ad markup.

RTB Single Endpoint

https://syndication.traffichaus.com/adserve/rtb.php

Perform RTB Requests - Single Endpoint

// Setup endpoint
$url = 'https://syndication.traffichaus.com/adserve/rtb.php';

// initiate a cURL request with a valid RTB JSON object request data object and store the result
$ch = curl_init($url);

$requestData = '{
	"id": "a5298b0f-ad20-4215-98dc-c32aa94f5533",
	"imp": [{
		"id": "1",
		"banner": {
			"w": 300,
			"h": 250
		},
		"bidfloor": 0.05,
		"ext": {
			"th_zone_platform_type": "mobile",
			"th_location": "footer",
			"zone_id": "445566"
		}
	}],
	"site": {
		"id": "66",
		"domain": "www.test.com",
		"page": "http://www.test.com/page",
		"ref": "https://www.test.com/otherpage",
		"keywords": "amateur,tits,blowjob,brunette,caucasian,couple,cowgirl,cum shot,handjob",
		"ext": {
			"th_site_key": "a3e5f7b301ad8c78eae946e74c7da7a7"
		}
	},
	"device": {
		"ua": "Mozilla/5.0 (Linux; Android 9; SM-G950F) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.93 Mobile Safari/537.36",
		"geo": {
			"country": "US"
		},
        "language": "en",
		"ip": "177.105.168.159",
		"devicetype": 2,
		"os": "android",
		"carrier": "VERIZON",
		"connectiontype": 2
	},
	"user": {
		"id": "b9967792-2c50-4da8-8d86-76a367608b81"
	}
}';

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestData);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type:application/json']);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($ch);
curl_close($ch);

// Print the response
print_r($result);

requestData='
{
	"id": "a5298b0f-ad20-4215-98dc-c32aa94f5533",
	"imp": [{
		"id": "1",
		"banner": {
			"w": 300,
			"h": 250
		},
		"bidfloor": 0.05,
		"ext": {
			"th_zone_platform_type": "mobile",
			"th_location": "footer",
			"zone_id": "445566"
		}
	}],
	"site": {
		"id": "66",
		"domain": "www.test.com",
		"page": "http://www.test.com/page",
		"ref": "https://www.test.com/otherpage",
		"keywords": "amateur,tits,blowjob,brunette,caucasian,couple,cowgirl,cum shot,handjob",
		"ext": {
			"th_site_key": "a3e5f7b301ad8c78eae946e74c7da7a7"
		}
	},
	"device": {
		"ua": "Mozilla/5.0 (Linux; Android 9; SM-G950F) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.93 Mobile Safari/537.36",
		"geo": {
			"country": "US"
		},
        "language": "en",
		"ip": "177.105.168.159",
		"devicetype": 2,
		"os": "android",
		"carrier": "VERIZON",
		"connectiontype": 2
	},
	"user": {
		"id": "b9967792-2c50-4da8-8d86-76a367608b81"
	}
}'

echo $requestData | curl --header 'Content-Type: application/json' \
--request POST \
--data @- \
'https://syndication.traffichaus.com/adserve/rtb.php'

{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "seatbid": [
        {
            "bid": [
                {
                    "id": "384878",
                    "impid": 6145298465,
                    "price": 0.064,
                    "nurl": "https:\/\/syndication.traffichaus.com\/adserve\/rtb_notify.php?bidid=8a541a82af5bafa0f3cbd0b1fc5ad6",
                    "adm": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?><ad><iframeAd><url><![CDATA[https:\/\/syndication.traffichaus.com\/adserve\/index.php?rtb&z=42750&ba=175842&rkey=900bb860edffe77f131b0d8975d65e]]><\/url><\/iframeAd><\/ad>"
                }
            ]
        }
    ]
}

If no bid ads are currently available for your specific zone, the expected HTTP response is 204 No Content.

RTB Multiple Endpoints

If you can't set the custom attributes for RTB site key and ad location (th_site_key and th_location) you can use this multiple endpoint method.

Each platform type + ad space type + ad location combo has its own endpoint enabled for RTB requests.

Platform	Ad Space	Ad Location	Endpoint
Desktop	Display	In Player	http://syndication.traffichaus.com/rtb/desktop/display/in-player
			Supported ad sizes: 300x250, 250x250
Desktop	Display	Next to Video	http://syndication.traffichaus.com/rtb/desktop/display/next-to-video
			Supported ad sizes: 300x250, 315x300
Desktop	Display	Leaderboard	http://syndication.traffichaus.com/rtb/desktop/display/leaderboard
			Supported ad sizes: 728x90, 468x60, 480x100
Desktop	Display	Footer	http://syndication.traffichaus.com/rtb/desktop/display/footer
			Supported ad sizes: 900x250, 950x250, 300x250, 600x250, 728x90, 1x1
Desktop	Display	Skyscraper	http://syndication.traffichaus.com/rtb/desktop/display/skyscraper
			Supported ad sizes: 160x600
Desktop	Display	Tower	http://syndication.traffichaus.com/rtb/desktop/display/tower
			Supported ad sizes: 300x600
Desktop	Display	IM Floater	http://syndication.traffichaus.com/rtb/desktop/display/im-floater
			Supported ad sizes: 250x170, 300x250, 30x30, 300x100
Desktop	Display	Index Cube	http://syndication.traffichaus.com/rtb/desktop/display/index-cube
			Supported ad sizes: 320x240, 300x250, 468x60, 160x160, 200x250, 920x360, 300x315, 250x250, 200x200, 155x276
Desktop	Display	Under Video	http://syndication.traffichaus.com/rtb/desktop/display/under-video-
			Supported ad sizes: 720x250, 728x90
Desktop	Display	Header	http://syndication.traffichaus.com/rtb/desktop/display/header
			Supported ad sizes: 300x100
Desktop	Display	Middle Banner	http://syndication.traffichaus.com/rtb/desktop/display/middle-banner
			Supported ad sizes: 600x250, 728x90, 600x400, 600x195, 960x384, 420x580, 345x80
Desktop	Display	Members Dating	http://syndication.traffichaus.com/rtb/desktop/display/members-dating
			Supported ad sizes: 300x250, 300x100, 300x85, 728x90, 160x120, 300x50, 960x150, 510x350, 30x30, 300x350, 600x400
Desktop	Display	Full Page Banner	http://syndication.traffichaus.com/rtb/desktop/display/full-page-banner
			Supported ad sizes:
Desktop	Display	Mainstream	http://syndication.traffichaus.com/rtb/desktop/display/mainstream
			Supported ad sizes:
Desktop	Display	Interstitial	http://syndication.traffichaus.com/rtb/desktop/display/interstitial
			Supported ad sizes: 300x250, 300x350
Desktop	Display	Pixel	http://syndication.traffichaus.com/rtb/desktop/display/pixel
			Supported ad sizes: 1x1
Desktop	Pop Under	Pop Under	http://syndication.traffichaus.com/rtb/desktop/pop-under/pop-under
Desktop	Video Ads	In Stream Pre-Roll	http://syndication.traffichaus.com/rtb/desktop/video-ads/in-stream-pre_roll
Desktop	Video Ads	Video Floater	http://syndication.traffichaus.com/rtb/desktop/video-ads/video-floater
Desktop	Push Notifications	Push Notification	http://syndication.traffichaus.com/rtb/desktop/push-notifications/push-notification
Desktop	Push Notifications	In-Page Push	http://syndication.traffichaus.com/rtb/desktop/push-notifications/in_page-push
Desktop	Postitial	Fullpage Postitial	http://syndication.traffichaus.com/rtb/desktop/postitial/fullpage-postitial
Desktop	Native	Native	http://syndication.traffichaus.com/rtb/desktop/native/native
Desktop	SMS Clicks	SMS Clicks	http://syndication.traffichaus.com/rtb/desktop/sms-clicks/sms-clicks
Mobile	Mobile Redirect	Mobile Redirect	http://syndication.traffichaus.com/rtb/mobile/mobile-redirect/mobile-redirect
Mobile	Display	Header	http://syndication.traffichaus.com/rtb/mobile/display/header
			Supported ad sizes: 300x100, 728x90, 300x75, 320x75, 300x99, 300x250, 300x50, 320x100
Mobile	Display	Middle Banner	http://syndication.traffichaus.com/rtb/mobile/display/middle-banner
			Supported ad sizes: 300x100, 300x250, 375x200
Mobile	Display	IM Floater	http://syndication.traffichaus.com/rtb/mobile/display/im-floater
			Supported ad sizes: 300x100, 300x250
Mobile	Display	Footer	http://syndication.traffichaus.com/rtb/mobile/display/footer
			Supported ad sizes: 300x250, 300x100
Mobile	Display	Interstitial	http://syndication.traffichaus.com/rtb/mobile/display/interstitial
			Supported ad sizes: 300x250
Mobile	Display	Post Roll	http://syndication.traffichaus.com/rtb/mobile/display/post-roll
			Supported ad sizes:
Mobile	Display	Under Player	http://syndication.traffichaus.com/rtb/mobile/display/under-player
			Supported ad sizes: 300x100, 300x250
Mobile	Display	Index Cube	http://syndication.traffichaus.com/rtb/mobile/display/index-cube
			Supported ad sizes: 1080x1920
Mobile	Pop Under	Pop Under	http://syndication.traffichaus.com/rtb/mobile/pop-under/pop-under
Mobile	Video Ads	In Stream Pre-Roll	http://syndication.traffichaus.com/rtb/mobile/video-ads/in-stream-pre_roll
Mobile	Video Ads	Video Floater	http://syndication.traffichaus.com/rtb/mobile/video-ads/video-floater
Mobile	Postitial	Postitial	http://syndication.traffichaus.com/rtb/mobile/postitial/postitial
Mobile	Native	Native	http://syndication.traffichaus.com/rtb/mobile/native/native
Tablet	Display	Index Cube	http://syndication.traffichaus.com/rtb/tablet/display/index-cube
			Supported ad sizes:
Tablet	Display	Next to Video	http://syndication.traffichaus.com/rtb/tablet/display/next-to-video
			Supported ad sizes: 300x250
Tablet	Display	Interstitial	http://syndication.traffichaus.com/rtb/tablet/display/interstitial
			Supported ad sizes: 300x250
Tablet	Display	Footer	http://syndication.traffichaus.com/rtb/tablet/display/footer
			Supported ad sizes: 300x250
Tablet	Display	Tower	http://syndication.traffichaus.com/rtb/tablet/display/tower
			Supported ad sizes:
Tablet	Display	Leaderboard	http://syndication.traffichaus.com/rtb/tablet/display/leaderboard
			Supported ad sizes:
Tablet	Display	Under Video	http://syndication.traffichaus.com/rtb/tablet/display/under-video
			Supported ad sizes: 720x250, 728x90
Tablet	Pop Under	Pop Under	http://syndication.traffichaus.com/rtb/tablet/pop-under/pop-under
Tablet	Video Ads	In Stream Pre-Roll	http://syndication.traffichaus.com/rtb/tablet/video-ads/in-stream-pre_roll
Tablet	Video Ads	Video Floater	http://syndication.traffichaus.com/rtb/tablet/video-ads/video-floater
Tablet	Postitial	Postitial	http://syndication.traffichaus.com/rtb/tablet/postitial/postitial
Tablet	Native	Native	http://syndication.traffichaus.com/rtb/tablet/native/native

Perform RTB Requests - Multiple Endpoints

// Setup endpoint
$url = 'https://syndication.traffichaus.com/rtb/desktop/display/next-to-video?key=YOUR-RTB-SITE-KEY';

// initiate a cURL request with a valid RTB JSON object request data object and store the result
$ch = curl_init($url);

$requestData = '{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "imp": [{
        "id": "6145298465",
        "instl": 0,
        "banner": {
            "w": 300,
            "h": 250
        },
        "bidfloor": 0.05
    }],
    "site": {
        "id": "12345",
        "domain": "www.test.com",
        "cat": ["IAB25-3"],
        "page": "https://www.test.com/page",
        "ext": {
            "exchangecat": 508,
            "idzone": 445566
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
        "ip": "91.126.38.115",
        "geo": {
            "country": "US"
        },
        "language": "en",
        "os": "Linux & UNIX",
        "js": 0,
        "ext": {
            "remote_addr": "91.126.38.115",
            "x_forwarded_for": "",
            "accept_language": "en-GB;q=0.8,pt-PT;q=0.6,en;q=0.4,en-US;q=0.2,de;q=0.2,es;q=0.2,fr;q=0.2"
        }
    },
    "user": {
        "id": "57592f333f8983.043587162282415065"
    }
}';

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestData);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type:application/json']);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($ch);
curl_close($ch);

// Print the response
print_r($result);

requestData='
{
	"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
	"imp": [{
		"id": "6145298465",
		"instl": 0,
		"banner": {
			"w": 300,
			"h": 250
		},
		"bidfloor": 0.05
	}],
	"site": {
		"id": "12345",
		"domain": "www.test.com",
		"cat": ["IAB25-3"],
		"page": "https://www.test.com/page",
		"ext": {
			"exchangecat": 508,
			"idzone": 445566
		}
	},
	"device": {
		"ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
		"ip": "91.126.38.115",
		"geo": {
			"country": "US"
		},
		"language": "en",
		"os": "Linux & UNIX",
		"js": 0,
		"ext": {
			"remote_addr": "91.126.38.115",
			"x_forwarded_for": "",
			"accept_language": "en-GB;q=0.8,pt-PT;q=0.6,en;q=0.4,en-US;q=0.2,de;q=0.2,es;q=0.2,fr;q=0.2"
		}
	},
	"user": {
		"id": "57592f333f8983.043587162282415065"
	}
}'

echo $requestData | curl --header 'Content-Type: application/json' \
--request POST \
--data @- \
'https://syndication.traffichaus.com/rtb/desktop/display/next-to-video?key=YOUR-RTB-SITE-KEY'

{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "seatbid": [
        {
            "bid": [
                {
                    "id": "384878",
                    "impid": 6145298465,
                    "price": 0.064,
                    "nurl": "https:\/\/syndication.traffichaus.com\/adserve\/rtb_notify.php?bidid=8a541a82af5bafa0f3cbd0b1fc5ad6",
                    "adm": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?><ad><iframeAd><url><![CDATA[https:\/\/syndication.traffichaus.com\/adserve\/index.php?rtb&z=42750&ba=175842&rkey=900bb860edffe77f131b0d8975d65e]]><\/url><\/iframeAd><\/ad>"
                }
            ]
        }
    ]
}

Before performing RTB requests, select the endpoint suited for the type of zones you wish to requests ads for and make sure you get your site key.

All endpoints accept only valid RTB JSON POST requests with the following URL params:

Type	Parameter	Description
string	key	Required. This is where you pass your RTB site key you got after adding your site to the RTB Sites list.

If no bid ads are currently available for your specific zone, the expected HTTP response is 204 No Content.

Manage RTB Site Zones

Once a RTB request was successfully received, a new zone will be queued for creation under the site associated to the given key.

You can view your RTB zones under SITES & ZONES -> Zones

RTB Response Codes

Code	Description
400	An invalid JSON RTB request body was received or the you didn't provide all of the required data (first of all check if you set the RTB site key).
403	The provided RTB site key is invalid or the RTB site has not been enabled on Traffichaus by an admin.
500	An internal error has occurred and we're probably looking into it.

Platform Integration: Site, Zone, and Ad

Use this workflow when your platform creates publisher inventory and then sends ads to TrafficHaus for delivery and management. Create the site first, create a zone under the returned site, and then create an ad with a landing-page creative targeting the returned zone.

Keep both API keys on your server. Never place an API key in browser JavaScript, HTML, a mobile application, or a public repository.

Credentials and Ownership

Credential	Used for	TrafficHaus ownership
Publisher API key	Create and retrieve sites and zones.	The site and zone appear under the publisher account associated with this key.
Advertiser API key	Create an ad and its creative in a returned zone_id.	The ad and creative appear under the advertiser account associated with this key.

A successful API response creates normal TrafficHaus records. Staff can manage sites and zones in Sites and Zones Management, and can find ads by the returned ad_id in Ad Manager. Publishers and advertisers see only records allowed by their account and permissions.

Step 1: Create the Site

Send the publisher API key in the query string and the site data as JSON. The response supplies the TrafficHaus site_id required by the next request.

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Content-Type: application/json" \
  --data '{
    "target": "site",
    "action": "create",
    "site_name": "Example Creator Directory",
    "site_url": "https://publisher.example.com"
  }' \
  "https://admin.traffichaus.com/api/v1/v1.php?key=YOUR_PUBLISHER_API_KEY"

Successful response:

{
  "success": 1,
  "site_id": 413279
}

Step 2: Create the Zone

Use the returned site_id. This example creates a dynamic Native Model Widget zone suitable for a model feed; use values supported by your TrafficHaus account for other zone types.

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Content-Type: application/json" \
  --data '{
    "target": "zone",
    "action": "create",
    "site_id": 413279,
    "platform_type": "Desktop",
    "ad_location": "Native",
    "ad_space": "Native",
    "ad_type": "Native Model Widget",
    "zone_name": "Creator model feed",
    "min_cpm": "0.200",
    "is_nsfw": 1,
    "accept_bidding": 1,
    "dynamic": 1,
    "rows": 0,
    "columns": 0
  }' \
  "https://admin.traffichaus.com/api/v1/v1.php?key=YOUR_PUBLISHER_API_KEY"

Successful response:

{
  "success": 1,
  "zone_id": 960771
}

Store the returned zone_id. It identifies the placement in TrafficHaus, is used when creating ads, and is the z value in an ad-serving or model-feed URL.

Step 3: Post a Model Image and Lander to the Zone

Use an advertiser API key for this request. The zone_id connects the advertiser's ad to the publisher's placement. For a Native Model Widget, use a banner creative so TrafficHaus can import the model image and retain its click destination and display metadata.

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Content-Type: application/json" \
  --data '{
    "target": "fixed_ad",
    "action": "create",
    "zone_id": 960771,
    "name": "Creator profile card",
    "ad_type": "Native Model Widget",
    "geo": "Global",
    "is_nsfw": 1,
    "weight": 100,
    "biddable": 0,
    "type": "CPM",
    "cpm": "0.100",
    "creative": {
      "type": "banners",
      "creative_url": "https://publisher.example.com/images/creator-handle.jpg",
      "destination_url": "https://publisher.example.com/models/creator-handle",
      "ad_url": "https://publisher.example.com/models/creator-handle",
      "title": "Creator Name",
      "message": "@creator_handle",
      "weight": 100
    }
  }' \
  "https://admin.traffichaus.com/api/v1/v1.php?key=YOUR_ADVERTISER_API_KEY"

Field	Purpose
zone_id	The TrafficHaus placement created in Step 2.
ad_type	Use Native Model Widget so TrafficHaus stores the model-specific native metadata.
creative.creative_url	A publicly retrievable model image. TrafficHaus imports the image into its creative media records.
creative.destination_url	The click-through lander. Use this field name; creative.url is not accepted for this creative.
creative.ad_url	The model's display or profile URL stored with the Native Model Widget metadata.
creative.title	The model or offer name shown by native placements.
creative.message	The model handle or short description shown by native placements.

Successful response:

{
  "success": 1,
  "ad_id": 1446074,
  "creative_id": 2404633
}

Create one ad per model so every image and lander has its own ad_id and creative_id. A successful response means the records were created. Serving and feed inclusion can still depend on account permissions, approval status, zone status, targeting, weight, pricing, and other TrafficHaus controls. Use the returned IDs to verify the records in TrafficHaus before sending production traffic.

For non-model placements, use the creative type supported by that zone. The Create a Fixed Ad section shows a simple landing-page creative, while the bidding campaign section documents programmatic bid_ad creation.

Save the TrafficHaus IDs

Your platform record	TrafficHaus ID to store	Used for
Publisher site	site_id	Create and retrieve zones; locate the site in TrafficHaus.
Placement or feed	zone_id	Create ads, build serving URLs, and manage the zone.
Ad or model	ad_id	Find, stop, and manage the TrafficHaus ad.
Image or landing page	creative_id	Identify the creative attached to the ad.

Synchronization Rules

1. Store every successful TrafficHaus ID with the corresponding record in your platform.
2. Create a zone only after the site request succeeds and returns a site_id.
3. Create an ad only after the zone request succeeds and returns a zone_id.
4. Do not blindly repeat a create request after an ambiguous timeout. First reconcile using the saved IDs or the TrafficHaus management interface, because create requests do not include an idempotency key and a retry can create a duplicate.
5. Treat HTTP 200 plus "success": 1 as success. Log the response body for any other result without logging API keys.
6. After posting an ad, verify the returned ad_id, creative, status, targeting, and destination in TrafficHaus before enabling production traffic.

For displaying models from the resulting feed, continue to the Model Feed section.

Publisher Sites

Getting started with the TrafficHaus Publishers API is easy! This page will guide you through the process, step-by-step.

Get Your Key

Get your API key below. We recommend keeping this hidden in a safe place, as it is just like your password for the API.

API Key:

Create Site

// Keep the publisher API key in a server-side environment variable.
$params = "?key=" . urlencode(getenv('TRAFFICHAUS_PUBLISHER_API_KEY'));
$url = "https://admin.traffichaus.com/api/v1/v1.php" . $params;

$data_string = '{
    "target": "site", 
    "action": "create",
    "site_name": "Google.com",
    "site_url": "https://www.google.com"
}';

// initiate a cURL request and store the result
$s = curl_init();
curl_setopt($s, CURLOPT_URL, $url);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_CUSTOMREQUEST, "POST");  
curl_setopt($s, CURLOPT_HTTPHEADER, array(                                                                          
    'Content-Type: application/json',                                                                                
    'Content-Length: ' . strlen($data_string))                                                                       
);

$response = curl_exec($s);

// for this simple example, we'll just echo a 200 response or an error response code
echo $response;

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Content-Type: application/json" \
  --data '{"target":"site","action":"create","site_name":"Example Site","site_url":"https://publisher.example.com"}' \
  "https://admin.traffichaus.com/api/v1/v1.php?key=YOUR_PUBLISHER_API_KEY"

Create the site with a publisher API key. TrafficHaus associates the new site with that publisher account and returns the site_id required to create zones.

Successful response: {"success":1,"site_id":413279}. Store the returned ID with the corresponding site in your platform.

GET params

Type	Parameter	Description
string	key	Required. This is where you pass in your API Key, this is required with every call to our TrafficHaus server.

POST params

Type	Parameter	Description
string	target	Required. This is where you send the api target, in this case "site".
string	action	Required. This is the action that you want the api to do, in this case creation.
string	site_name	Required. The name of the site.
string	site_url	Required. The url of the site.

Get Sites

// set up your URL with the appropriate parameters
$params = "?key=b59jght6-1kjd-7775-48ed-00259gr3";
$url = "http://admin.traffichaus.com/api/v1/v1.php" . $params;

$data_string = '{
    "target": "site", 
    "action": "get"
}';

// initiate a cURL request and store the result
$s = curl_init();
curl_setopt($s, CURLOPT_URL, $url);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_CUSTOMREQUEST, "POST");  
curl_setopt($s, CURLOPT_HTTPHEADER, array(                                                                          
    'Content-Type: application/json',                                                                                
    'Content-Length: ' . strlen($data_string))                                                                       
);

$response = curl_exec($s);

// for this simple example, we'll just echo a 200 response or an error response code
echo $response;

We offer API access to retrieve your sites via simple HTTP POST requests to our server, using query string parameters.

GET params

Type	Parameter	Description
string	key	Required. This is where you pass in your API Key, this is required with every call to our TrafficHaus server.

POST params

Type	Parameter	Description
string	target	Required. This is where you send the api target, in this case "site".
string	action	Required. This is the action that you want the api to do, in this case creation.

Publisher Zones

Getting started with the TrafficHaus Publishers API is easy! This page will guide you through the process, step-by-step.

Get Your Key

Get your API key below. We recommend keeping this hidden in a safe place, as it is just like your password for the API.

API Key:

Create Zone

// Keep the publisher API key in a server-side environment variable.
$params = "?key=" . urlencode(getenv('TRAFFICHAUS_PUBLISHER_API_KEY'));
$url = "https://admin.traffichaus.com/api/v1/v1.php" . $params;

$data_string = '{
    "target":"zone", 
    "action": "create",
    "site_id": "413279",
    "platform_type": "Desktop",
    "ad_location": "Native",
    "ad_space": "Native",
    "ad_type": "Native Model Widget",
    "zone_name": "Native model widget 1",
    "min_cpm": "0.2",
    "is_nsfw": 1,
    "accept_bidding": 1,
    "dynamic": 1,
    "rows": 0,
    "columns": 0
}';

// initiate a cURL request and store the result
$s = curl_init();
curl_setopt($s, CURLOPT_URL, $url);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_CUSTOMREQUEST, "POST");  
curl_setopt($s, CURLOPT_HTTPHEADER, array(                                                                          
    'Content-Type: application/json',                                                                                
    'Content-Length: ' . strlen($data_string))                                                                       
);

$response = curl_exec($s);

// for this simple example, we'll just echo a 200 response or an error response code
echo $response;

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Content-Type: application/json" \
  --data '{"target":"zone","action":"create","site_id":413279,"platform_type":"Desktop","ad_location":"Native","ad_space":"Native","ad_type":"Native Model Widget","zone_name":"Creator model feed","min_cpm":"0.200","is_nsfw":1,"accept_bidding":1,"dynamic":1,"rows":0,"columns":0}' \
  "https://admin.traffichaus.com/api/v1/v1.php?key=YOUR_PUBLISHER_API_KEY"

Create the zone with the same publisher API key and a site_id returned by the site creation call. TrafficHaus associates the new zone with that site and publisher account.

Successful response: {"success":1,"zone_id":960771}. Store the returned ID; it is used to post ads, build serving or feed URLs, and locate the zone in TrafficHaus.

GET params

Type	Parameter	Description
string	key	Required. This is where you pass in your API Key, this is required with every call to our TrafficHaus server.

POST params

Type	Parameter	Description
string	target	Required. This is where you send the api target, in this case "zone".
string	action	Required. This is the action that you want the api to do, in this case creation.
string	site_id	Required. The site id.
string	platform_type	Required. The platform type. For example "Desktop".
string	ad_location	Required. The ad location type. For example "Native".
string	ad_space	Required. The Ad Space type. For example "Native"
string	ad_type	Required. The type of the ad zone.
string	zone_name	Required. The Name of the zone.
string	min_cpm	Required. The minimum cpm amount.
string	is_nsfw	Required. If the zone is Not Safe For Work.
string	accept_bidding	Required. If the zone accepts Bidding Ads.
string	dynamic	Optional. If the zone is a Native one, if dynamic is set to 1, the size of the zone is determined by the number of available ads, and the rows and columns params must be set to 0 for this to happen.
string	rows	Optional. If the zone is a Native one, the number of rows that the zone will output.
string	columns	Optional. If the zone is a Native one, the number of columns that the zone will output.

Get Zones

// set up your URL with the appropriate parameters
$params = "?key=b59jght6-1kjd-7775-48ed-00259gr3";
$url = "http://admin.traffichaus.com/api/v1/v1.php" . $params;

$data_string = '{
    "target": "zone", 
    "action": "get",
    "site_id": 43445
}';

// initiate a cURL request and store the result
$s = curl_init();
curl_setopt($s, CURLOPT_URL, $url);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_CUSTOMREQUEST, "POST");  
curl_setopt($s, CURLOPT_HTTPHEADER, array(                                                                          
    'Content-Type: application/json',                                                                                
    'Content-Length: ' . strlen($data_string))                                                                       
);

$response = curl_exec($s);

// for this simple example, we'll just echo a 200 response or an error response code
echo $response;

We offer API access to retrieve your zones via simple HTTP POST requests to our server, using query string parameters.

GET params

Type	Parameter	Description
string	key	Required. This is where you pass in your API Key, this is required with every call to our TrafficHaus server.

POST params

Type	Parameter	Description
string	target	Required. This is where you send the api target, in this case "zone".
string	action	Required. This is the action that you want the api to do, in this case retrieval.
string	site_id	Required. This is the site_id where the needed zones belong to.

Change Ad Count

// set up your URL with the appropriate parameters
$params = "?key=b59jght6-1kjd-7775-48ed-00259gr3";
$url = "http://admin.traffichaus.com/api/v1/v1.php" . $params;

$data_string = '{
    "target": "zone",
    "action": "change_ad_count",
    "zone_id": "445566",
    "ad_count": 3
}';

// initiate a cURL request and store the result
$s = curl_init();
curl_setopt($s, CURLOPT_URL, $url);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($s, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data_string))
);

$response = curl_exec($s);
echo $response;

Sets how many ads should be active in a zone. The platform rebalances the weights of the zone's ads so the requested number are served. If the zone already serves that many ads the call returns an error stating the count is unchanged.

GET params

Type	Parameter	Description
string	key	Required. This is where you pass in your API Key, this is required with every call to our TrafficHaus server.

POST params

Type	Parameter	Description
string	target	Required. In this case "zone".
string	action	Required. In this case "change_ad_count".
int	zone_id	Required. The zone whose active ad count you want to change.
int	ad_count	Required. The number of ads that should be active in the zone.

Publisher Assets

Getting started with the TrafficHaus Publishers API is easy! This page will guide you through the process, step-by-step.

Get Your Key

Get your API key below. We recommend keeping this hidden in a safe place, as it is just like your password for the API.

API Key:

Get Assets

// set up your URL with the appropriate parameters
$params = "?key=b59jght6-1kjd-7775-48ed-00259gr3";
$url = "http://admin.traffichaus.com/api/v1/v1.php" . $params;

$data_string = '{
    "target": "ads",
    "action": "assets",
    "start_timestamp": 1700000000,
    "end_timestamp": 1700086400
}';

// initiate a cURL request and store the result
$s = curl_init();
curl_setopt($s, CURLOPT_URL, $url);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($s, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data_string))
);

$response = curl_exec($s);
echo $response;

Returns the creative assets (media urls and dimensions) for the ads running on your zones within the given time window. Timestamps are UNIX timestamps (seconds).

GET params

Type	Parameter	Description
string	key	Required. This is where you pass in your API Key, this is required with every call to our TrafficHaus server.

POST params

Type	Parameter	Description
string	target	Required. In this case "ads".
string	action	Required. In this case "assets".
int	start_timestamp	Required. Start of the window as a UNIX timestamp (seconds).
int	end_timestamp	Required. End of the window as a UNIX timestamp (seconds).

Model Feed

The TrafficHaus model feed returns the current models assigned to a feed-enabled zone. Use it to display model names, profile images, categories, and TrafficHaus click-through links without maintaining a separate catalogue.

Feed records and tracking links can change when TrafficHaus updates the zone. Refresh the feed at least every five minutes and always use the URLs returned by the latest successful response.

Endpoint

curl --fail --silent --show-error \
  --header "Accept: application/json" \
  --header "Cache-Control: no-cache" \
  "https://oneonone.voyeurhouse.com/adserve/index-th.php?z=960771"

$feedUrl = 'https://oneonone.voyeurhouse.com/adserve/index-th.php?z=960771';

$request = curl_init($feedUrl);
curl_setopt_array($request, array(
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => array(
        'Accept: application/json',
        'Cache-Control: no-cache'
    )
));

$body = curl_exec($request);
$status = (int) curl_getinfo($request, CURLINFO_HTTP_CODE);
$error = curl_error($request);
curl_close($request);

if ($body === false || $status !== 200) {
    throw new RuntimeException('Model feed request failed: ' . $status . ' ' . $error);
}

Replace the hostname with the serving alias assigned to your site and replace 960771 with your feed-enabled zone ID. Feed requests are zone-based and do not use the reporting API key.

GET parameters

Type	Parameter	Description
int	z	Required. The TrafficHaus zone ID configured as a model feed.

Response

A successful response is valid JSON containing either a top-level array of model records or an object with a models array. Consumers should support both envelopes.

[
  {
    "username": "creator_handle",
    "name": "Creator Name",
    "profile_image": "https://cdn1ht.example.com/uploads/path/image.jpg",
    "click_url": "https://ads.example.com/adserve/click.php?data=tracking-token",
    "category": "Category One, Category Two",
    "details": "Optional description",
    "sort": 1
  }
]

Field	Description
username	Stable model handle. Use this value when selecting or matching one model.
name	Display name. Fall back to username when empty.
profile_image	Current model image URL. Legacy records may use image or image_url. Render the returned URL without replacing its host.
click_url	TrafficHaus tracking URL for the model landing page. Legacy records may use url or onlyfans_url. Use the resolved URL exactly as returned.
category	Optional comma-separated categories or keywords.
details	Optional descriptive text supplied by the model feed.
sort	Optional display order. Lower values should be displayed first.

Parse All Models

$payload = json_decode($body, true);
if (json_last_error() !== JSON_ERROR_NONE || !is_array($payload)) {
    throw new RuntimeException('The model feed did not return valid JSON.');
}

$models = isset($payload['models']) && is_array($payload['models'])
    ? $payload['models']
    : $payload;

usort($models, function ($left, $right) {
    return ((int) ($left['sort'] ?? PHP_INT_MAX))
        <=> ((int) ($right['sort'] ?? PHP_INT_MAX));
});

foreach ($models as $model) {
    $username = isset($model['username']) ? ltrim($model['username'], '@') : '';
    $name = !empty($model['name']) ? $model['name'] : '@' . $username;
    $imageUrl = $model['profile_image'] ?? $model['image'] ?? $model['image_url'] ?? null;
    $clickUrl = $model['click_url'] ?? $model['url'] ?? $model['onlyfans_url'] ?? null;

    // Escape display text and validate HTTP/HTTPS URLs before rendering them.
}

# jq example for either supported response envelope
curl --fail --silent --show-error \
  "https://oneonone.voyeurhouse.com/adserve/index-th.php?z=960771" \
  | jq 'if type == "array" then . else .models end | sort_by(.sort // 999999)'

Select One Model

The feed does not require a separate request for each model. Fetch the collection once, then select one record by its exact username. This preserves one refresh schedule and prevents duplicate feed requests.

$requestedUsername = 'creator_handle';
$selectedModel = null;

foreach ($models as $model) {
    $username = isset($model['username']) ? ltrim($model['username'], '@') : '';
    if (strcasecmp($username, ltrim($requestedUsername, '@')) === 0) {
        $selectedModel = $model;
        break;
    }
}

if ($selectedModel === null) {
    // The model is no longer assigned to this zone. Return a normal not-found state.
}

MODEL_USERNAME="creator_handle"
curl --fail --silent --show-error \
  "https://oneonone.voyeurhouse.com/adserve/index-th.php?z=960771" \
  | jq --arg username "$MODEL_USERNAME" \
      '(if type == "array" then . else .models end)
       | map(select(((.username // "") | ltrimstr("@") | ascii_downcase) == ($username | ltrimstr("@") | ascii_downcase)))
       | first'

Refresh and Cache Requirements

1. Fetch the feed on the server when the page or catalogue cache is first requested.
2. Refresh at least every five minutes and use Cache-Control: no-cache or an equivalent no-store request policy.
3. When a user returns to the page after five minutes, request a fresh feed before reusing model records.
4. Replace the cached collection only after receiving HTTP 200 and successfully parsing the complete JSON response.
5. On timeout, non-200 response, or invalid JSON, retain the last known good collection and retry later. Never publish a partial response.
6. Prevent overlapping refreshes so repeated clicks or simultaneous page requests do not create duplicate feed requests.

Images and Click Tracking

• Resolve the image field in this order: profile_image, image, then image_url. Do not replace the returned CDN hostname in application code.
• Resolve the click field in this order: click_url, url, then onlyfans_url. Use it as the model card or image destination without decoding it or replacing it with the final landing page.
• Do not preflight, preload, or request the resolved click URL; open it only after an actual user click.
• Do not retain old click URLs when refreshed model data supplies a replacement.
• It is safe to remember presentation state, such as the number of expanded rows, but fetch current model records and tracking URLs when the feed cache expires.

Error Handling

Condition	Required handling
HTTP 200 with valid JSON	Validate records and atomically replace the cached collection.
HTTP 4xx or 5xx	Keep the last known good collection, log the status, and retry later.
Timeout or connection failure	Keep the last known good collection and use a bounded retry with backoff.
Invalid or incomplete JSON	Reject the entire response. Do not salvage or publish partial model records.
Requested username not found	Treat the model as unavailable for that zone and render a normal not-found state.

Advertiser Stats

Getting started with the TrafficHaus Advertiser Stats API is easy! This page will guide you through the process, step-by-step.

Get Your Key

Get your API key below. We recommend keeping this hidden in a safe place, as it is just like your password for the API.

API Key:

Get Your Stats

// set up your URL with the appropriate parameters
$params = "?api_key=b59jght6-1kjd-7775-48ed-00259gr3&start_date=2016-07-01&end_date=2016-07-07&campaigns=11356,98764,98763&group_by=campaign,date&format=1";
$url = "http://admin.traffichaus.com/api/v1/advertiser_stats.php" . $params;

// initiate a cURL request and store the result
$s = curl_init();
curl_setopt($s, CURLOPT_URL, $url);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_CUSTOMREQUEST, "GET");

$response = curl_exec($s);

// for this simple example, we'll just echo the response
echo $response;

We offer API access to your stats via simple HTTP GET requests to our server, using query string parameters.

Type	Parameter	Description
string	api_key	Required. This is where you pass in your API Key, this is required with every call to our TrafficHaus server.
string	start_date	Recommended. Specify a start date for the returned stats. (Note: Selecting too long of a date range may lead to an error, as we limit the size of each request to 100MB or less.)
string	end_date	Recommended. Specify an end date for the returned stats. (Note: Selecting too long of a date range may lead to an error, as we limit the size of each request to 100MB or less.)
string	campaigns	Optional. Include a comma-separated list of campaign IDs to get a specific subset of your campaigns, or just omit to get them all.
string	group_by	Optional. By default, we will return your stats grouped by campaign and date. You can also choose to pull summary data by campaign or date by passing in one of the following parameters: campaign or date
int	format	We offer a variety of formats for your convenience: 0 = raw JSON output (default), 1 = formatted output for dataTables, wrapped in a [data] envelope, 2 = extended output (datatables format plus additional [meta] envelope)

Advertiser RTB

Add RTB Campaign

You need to add an RTB campaign to start receiving requests.

The RTB campaign should have the following fields :

• A campaign name.
• An endpoint url that will receive the requests.
• Ad type: you can choose either banner or pop under. Video will be available soon. If you choose all, you will receive all available ad types.
• Serever zone : right now we have servers in US and EU. You may choose the best region that fits the location of your servers. Please keep in mind that the max response time is set to 150ms. If you choose all you will get requests from all available regions.
• Exclude publishers : you can remove requests from specific publishers by adding publisher ids separated by comma.
• Frequency : used to set the number of requests per seconds. Putting 0 will give the maximum requests. By default it is capped to 1000 req/s. If you need more please contact us.
• Countries : you can choose requests coming from all countries or you can choose among the list.

RTB Request Object

Object: bidrequest

Attribute	Required	Description
id	yes	Unique ID of the bid request.
imp	yes	Array of Imp objects representing the impressions offered.
site	yes	Details via a site object about the publisher's website.
device	yes	Details via a device object about the user's device to which the impression will be delivered.
user	no	Details via a user object about the human user of the device.
tmax	no	Maximum time in milliseconds before considering as a request timeout.

Object: imp

Attribute	Required	Description
id	yes	Unique ID of the impression.
banner	only for banner/iframe imps	A banner object.
bidfloor	no; default 0.001	Minimum bid for this impression expressed in CPM.
ext	yes; if using single endpoint	Placeholder for exchange-specific extensions to OpenRTB.

If banner object is not set, the Traffichaus zone will be defaulted to pop-under type (if using single endpoint)

Supported ext attributes

Attribute	Required	Description
th_location	yes; if using single endpoint	The location of the zone the ad is assigned to. Required to be one of the supported Traffichaus locations based on the zone platform type.
th_zone_platform_type	recommended; if using single endpoint	The platform type of the zone the ad is assigned to. Required to be one of the supported Traffichaus platform types.
zone_id	recommended	The zone ID of the publisher's site for which an impression is requested.

Object: site

Attribute	Required	Description
id	no	Unique ID of the requesting site.
domain	recommended	Domain of the site (e.g., "example.com").
page	no	URL of the page where the impression will be shown.
ref	no	Referrer URL that caused navigation to the current page.
cat	no; default IAB25	The IAB content category of the site.
keywords	no	Comma separated list of keywords about the site.
ext	yes; if using single endpoint	Placeholder for exchange-specific extensions to OpenRTB.

Supported ext attributes

Attribute	Required	Description
th_site_key	yes; if using single endpoint	The RTB site key assigned to the site after being added as a RTB Site to Traffichaus.
zone_id	recommended(if not set in imp object's ext data)	The zone ID of the publisher's site for which the impressions are requested.

Object: device

Attribute	Required	Description
ip	recommended	IP address of device.
ua	yes	Browser user agent string.
language	recommended	Device language. Only ISO 639-1 Alpha-2 or Alpha-3 codes.
geo	recommended	Location of the device defined by a geo object .
os	recommended	Device operating system (e.g., "iOS", "Android", "Linux", "Windows").
devicetype	no	The general type of device.
carrier	no	Carrier or ISP (e.g., "VERIZON").
connectiontype	no	The type of connection the device uses(e.g., Ethernet, 2G, 3G, WiFI) - use integer values as given by the official OpenRTR documentation.
ext	no	Placeholder for exchange-specific extensions to OpenRTB.

Object: geo

Attribute	Required	Description
country	recommended	Country code using ISO 3166-1 alpha-2.
ext	no	Placeholder for exchange-specific extensions to OpenRTB.

Object: banner

Attribute	Required	Description
w	yes	Width of the required ad in pixels.
h	yes	Height of the required ad in pixels.

RTB Response Object

Object: bidresponse

Attribute	Required	Description
id	yes	ID of the bid request to which this is a response.
seatbid	yes	Collection of bids made by the bidder on behalf of a specific seat.

Object: seatbid

Attribute	Required	Description
bid	yes	Array of 1+bid objects each related to an impression. Multiple bids can relate to the same impression.

Object: bid

Attribute	Required	Description
id	yes	Bidder generated bid ID.
impid	yes	ID of the imp object in the related bid request.
price	yes	Bid price expressed as CPM.
nurl	yes	Win notice URL called by the exchange if the bid wins.
adm	yes	The XML ad markup.

Advertiser Bid Campaign

Getting started with the TrafficHaus Advertiser Stats API is easy! This page will guide you through the process, step-by-step.

What is implemented. The advertiser API currently supports creating a bidding campaign with the bid_ad / create payload documented on this page, plus pausing, resuming and stopping ads, and reading stats. Please do not infer other behaviour, ad locations, ad types, creative types, or bid rules from the TrafficHaus admin UI or the RTB docs — only what is described below is guaranteed by the campaign-create implementation.

Authentication

Campaign creation authenticates with your API key passed in the key query string parameter (api_key is used only by the stats endpoints and is not accepted here):

POST https://admin.traffichaus.com/api/v1/v1.php?key=YOUR_API_KEY

Accepted values — don't guess, ask the API

Several fields are validated against the live TrafficHaus catalog, and the valid set depends on the account, the is_nsfw flag and the targeting you send — so they are not a fixed list. Instead of hard-coding values, send the request: if a value is not accepted the API returns HTTP 400 with the exact list of accepted values for that field. Use that list as the source of truth.

Field	Where the accepted values come back in the 400 response
ad_location	accepted_ad_locations
ad_type	accepted_ad_types (for the chosen ad_location)
creative.type	listed in message: “Accepted creative types for this type of ad are: …”
geo	accepted_geos
languages	accepted_languages
operating_systems	accepted_operating_systems (for the chosen device_type)
browsers	returned in accepted_operating_systems* (requires geo targeting)
carriers	accepted_carriers (for the chosen geo; requires geo targeting)
site_targeting_sites	accepted_site_targeting_sites (when using Premium Site Targeting)

*The browser validation error currently reports its list under the accepted_operating_systems key.

Fixed value sets

These fields accept a fixed set of values:

Field	Accepted values	Default
bid_type	cpm, cpc	cpm
device_type	Desktop, Mobile, Tablet (comma-separated)	all three
site_targeting	Run-of-Network, Premium Site Targeting	Run-of-Network
frequency_cap_type	user, zone, site, none	none
is_nsfw	1, 0	1

Verified working example

This combination is confirmed working for API campaign creation:

ad_location	ad_type	creative.type	bid_type
Native	Native Model Widget	banners	cpm

Other ad locations / ad types accepted by the platform also work, but confirm the exact strings via the accepted_* lists above before relying on them.

Get Your Key

Get your API key below. We recommend keeping this hidden in a safe place, as it is just like your password for the API.

API Key:

Create Bidding Campaign

// set up your URL with the appropriate parameters
$params = "?key=b59jght6-1kjd-7775-48ed-00259gr3";
$url = "http://admin.traffichaus.com/api/v1/v1.php" . $params;

$data_string = '{
    "target":"bid_ad", 
    "action": "create",
    "name": "Campaign name",
    "is_nsfw": "1",
    "geo": "united states",
    "device_type": "desktop, mobile, tablet",
    "ad_location": "Native",
    "ad_type": "Native Model Widget",
    "site_targeting": "Run-of-Network",
    "frequency_cap_type": "site",
    "frequency_cap_value": 2,
    "languages": "english",
    "operating_systems": "ios",
    "browsers": "chrome, firefox",
    "carriers": "sprint pcs",
    "keywords": "gilly, handsome",
    "bid_type": "cpm",
    "bid_amount": "1.3",
    "daily_budget": "100",
    "total_budget":"1000",
    "zone_targeting":"12312,13213",
    "creative":{
        "type":"banners",
        "creative_url":"https://www.example.com/example.png",
        "destination_url":"http://www.google.ro",
        "ad_url":"google.com",
        "title":"Your title",
        "message":"Your message"
    }
}';

// initiate a cURL request and store the result
$s = curl_init();
curl_setopt($s, CURLOPT_URL, $url);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_CUSTOMREQUEST, "POST");  
curl_setopt($s, CURLOPT_HTTPHEADER, array(                                                                          
    'Content-Type: application/json',                                                                                
    'Content-Length: ' . strlen($data_string))                                                                       
);

$response = curl_exec($s);

// for this simple example, we'll just echo a 200 response or an error response code
echo $response;

We offer API access to create bidding ads via simple HTTP POST requests to our server, using query string parameters.

GET params

Type	Parameter	Description
string	key	Required. This is where you pass in your API Key, this is required with every call to our TrafficHaus server.

POST params

Type	Parameter	Description
string	target	Required. This is where you send the api target, in this case a bidding ad.
string	action	Required. This is the action that you want the api to do, in this case creation.
string	name	Required. The name of the campaign.
string	is_nsfw	Required. The type of the campign, safe for work or not.
string	geo	Optional. The full name of the geo targeting. Defaults to Global. Invalid values return accepted_geos.
string	device_type	Optional. The device targeting, comma-separated. Accepted: Desktop, Mobile, Tablet. Defaults to all three.
string	ad_location	Required. The Ad location type.
string	ad_type	Required. The Ad Type based on the selected ad location.
string	site_targeting	Optional. Site targeting, which can be Run-of-Network, or Premium Site Targeting which allows targeting on sites available on the selected ad type. Defaults to Run-of-Network. Premium Site Targeting also requires site_targeting_sites.
string	frequency_cap_type	Recommended. Frequency capping type, which can be site based, zone based, or user based. Defaults to unlimited.
string	frequency_cap_value	Recommended. Frequency capping value, which allows setting up the number of impressions allowed per Frequency capping type.
string	languages	Recommended. Language targeting. Defaults to all. Ex: English
string	operating_systems	Recommended. Operating system targeting. Defaults to all. Ex: IOS
string	browsers	Recommended. Browser targeting. Defaults to all. Ex: Chrome
string	carriers	Recommended. Carrier targeting based on the selected Geo. Defaults to all. Ex: Verizon
string	keywords	Recommended. Keyword targeting. Ex: Man, Woman
string	bid_type	Required. Type of bidding. Can be CPM or CPC.
float	bid_amount	Optional. Bid price. Defaults to 0.2. Ex: 1.2
int	daily_budget	Recommended. Total daily budget. Defaults to unlimited. Ex: 200
int	total_budget	Recommended. Total campaign budget. Defaults to unlimited. Ex: 2000
object	creative	Required. Creative options.

Responses

On success the API returns HTTP 200 with:

{
    "success": 1
}

The created campaign and its creative enter a pending approval state and do not start serving until approved. The response does not currently include the new campaign/ad id.

On a validation failure the API returns HTTP 400 with success: 0, a human-readable message, and — for the catalog-validated fields — the list of accepted values. For example, an unsupported ad location:

{
    "success": 0,
    "message": "Bad ad_location.",
    "accepted_ad_locations": ["native", "pop under", "..."]
}

Other representative error messages: "No creative specified.", "Bad creative type value. Accepted creative types for this type of ad are: banners,destination_url,landing_page.", "Bad bid type. Type must be 'CPC' OR 'CPM'.", and "This is not a valid advertiser api key."

Advertiser Manage Bid Ads

Once a bidding campaign has been created you can pause it, resume it, and list the ads running on a given zone. All requests are HTTP POST to the same endpoint, authenticated with your API key in the key query parameter.

Pause a bid ad

// set up your URL with the appropriate parameters
$params = "?key=b59jght6-1kjd-7775-48ed-00259gr3";
$url = "http://admin.traffichaus.com/api/v1/v1.php" . $params;

// the json object
$data_string = '{"target":"bid_ad","action":"pause","ad_id":"89085"}';

// initiate a cURL request and store the result
$s = curl_init();
curl_setopt($s, CURLOPT_URL, $url);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($s, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data_string))
);

$response = curl_exec($s);
echo $response;

Pauses a bidding ad (and its campaign and creatives). Only ads currently active are affected.

Type	Parameter	Description
string	target	Required. In this case "bid_ad".
string	action	Required. In this case "pause".
int	ad_id	Required. The id of the bid ad you want to pause.

Response: {"success":1}

Resume a bid ad

// set up your URL with the appropriate parameters
$params = "?key=b59jght6-1kjd-7775-48ed-00259gr3";
$url = "http://admin.traffichaus.com/api/v1/v1.php" . $params;

// the json object
$data_string = '{"target":"bid_ad","action":"resume","ad_id":"89085"}';

// initiate a cURL request and store the result
$s = curl_init();
curl_setopt($s, CURLOPT_URL, $url);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($s, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data_string))
);

$response = curl_exec($s);
echo $response;

Resumes a previously paused bidding ad (and its campaign and creatives).

Type	Parameter	Description
string	target	Required. In this case "bid_ad".
string	action	Required. In this case "resume".
int	ad_id	Required. The id of the bid ad you want to resume.

Response: {"success":1}

Get all ads by zone

// set up your URL with the appropriate parameters
$params = "?key=b59jght6-1kjd-7775-48ed-00259gr3";
$url = "http://admin.traffichaus.com/api/v1/v1.php" . $params;

// the json object
$data_string = '{"target":"bid_ad","action":"get_all_ads_by_zone","zone_id":"445566"}';

// initiate a cURL request and store the result
$s = curl_init();
curl_setopt($s, CURLOPT_URL, $url);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($s, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data_string))
);

$response = curl_exec($s);
echo $response;

Returns the bidding ads you own that target a given zone, including each ad's creatives and their resolved details (title, description, url, likes, photos, videos, price).

Type	Parameter	Description
string	target	Required. In this case "bid_ad".
string	action	Required. In this case "get_all_ads_by_zone".
int	zone_id	Required. The zone id to list your ads for.

Response: {"success":1,"zones":[{"ad_id":89085,"name":"Campaign name","status_type_id":1,"creatives":[ ... ]}]}

Advertiser Create Fixed Ad

Create a fixed ad

// Keep the advertiser API key in a server-side environment variable.
$params = "?key=" . urlencode(getenv('TRAFFICHAUS_ADVERTISER_API_KEY'));
$url = "https://admin.traffichaus.com/api/v1/v1.php" . $params;

// the json object
$data_string = '{"target":"fixed_ad","action":"create","zone_id":960771,"name":"Creator profile card","geo":"Global","is_nsfw":1,"weight":100,"biddable":0,"type":"CPM","cpm":"0.100","creative":{"type":"landing_page","destination_url":"https://publisher.example.com/models/creator-handle","weight":100}}';

// initiate a cURL request and store the result
$s = curl_init();
curl_setopt($s, CURLOPT_URL, $url);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_CUSTOMREQUEST, "POST");  
curl_setopt($s, CURLOPT_HTTPHEADER, array(                                                                          
    'Content-Type: application/json',                                                                                
    'Content-Length: ' . strlen($data_string))                                                                       
);

$response = curl_exec($s);

// for this simple example, we'll just echo the response
echo $response;

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Content-Type: application/json" \
  --data '{"target":"fixed_ad","action":"create","zone_id":960771,"name":"Creator profile card","geo":"Global","is_nsfw":1,"weight":100,"biddable":0,"type":"CPM","cpm":"0.100","creative":{"type":"landing_page","destination_url":"https://publisher.example.com/models/creator-handle","weight":100}}' \
  "https://admin.traffichaus.com/api/v1/v1.php?key=YOUR_ADVERTISER_API_KEY"

Create the ad with an advertiser API key. Use the zone_id returned by zone creation to place the ad and its creative in that TrafficHaus zone.

Successful response: {"success":1,"ad_id":1446074,"creative_id":2404633}. Store both IDs so the records can be reconciled and managed in TrafficHaus.

Ad info

Type	Parameter	Description
string	target	Required. Specify the the type of target you are trying to reach. In this case "fixed_ad".
string	action	Required. Specify the the type of action you are trying to make. In this case "create".
int	zone_id	Required. Specify the zone id you are trying to add this ad to.
string	name	Required. The name of the ad you are trying to create. (Ex: "My new ad")
string	geo	Required. The geo you would like to target. (Ex: US, CA)
int	is_nsfw	Required. If the zone is Not Safe For Work. 1 true, 0 false.
int	weight	Required. The weight of the ad.
int	biddable	Required. If this fixed ad is biddable or not. 1 true, 0 false.
string	type	Required. The type of ad delivery. (Ex: Cpm)
string	carrier	Optional. The carrier the ad wants to target. Omit it to avoid carrier-specific targeting.
json	creative	Required. For a fixed ad to show it needs a creative. See the paramters below.

Landing page creative

Type	Parameter	Description
string	type	Required. The type of creative it should create. It most correlate with the types from our platform. (Ex: "landing_page")
string	destination_url	Required. The valid HTTP or HTTPS landing-page URL. The field name is destination_url, not url.

Stop a fixed ad

// Keep the advertiser API key in a server-side environment variable.
$params = "?key=" . urlencode(getenv('TRAFFICHAUS_ADVERTISER_API_KEY'));
$url = "https://admin.traffichaus.com/api/v1/v1.php" . $params;

// the json object
$data_string = '{"target":"fixed_ad","action":"stop","ad_id":"89085"}';

// initiate a cURL request and store the result
$s = curl_init();
curl_setopt($s, CURLOPT_URL, $url);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($s, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data_string))
);

$response = curl_exec($s);
echo $response;

Stops a fixed ad you own. The ad must belong to your account; once stopped it no longer serves.

Type	Parameter	Description
string	target	Required. In this case "fixed_ad".
string	action	Required. In this case "stop".
int	ad_id	Required. The id of the fixed ad you want to stop.

Response: {"success":1,"ad_id":89085,"status":"Stopped"}