PUBLISHER API GUIDE - Partnerize · ACCESSING YOUR API CREDENTIALS Partnerize have designed the API...

PUBLISHER API GUIDE Version 1.3 October 2016

AUTHOR: PARTNERIZE CLIENT SERVICES TEAM - [email protected] 1

mailto:[email protected]

Table of Contents Introduction 3 API Overview 4

Accessing your API credentials 4 API Overview report 5 Overview API syntax 5

API Parameters 5 Required API Parameters 5 Optional API Parameters 6 Example of valid overview XML response 7 Example of valid overview PUBREF XML response 9

API Reporting 11 API Direct report 11 Direct report API syntax 11 Required API parameters 11 Optional API parameters 11 Example of valid publisher tracking XML response 16

Creatives 17 Campaign creative 17 Campaign creatives API syntax 17 Required API parameters 17 Example of valid campaign creatives XML response 18

Commission 19 Publisher commission rates 19 Publisher commission API syntax 19 Required API parameters 19 Optional API parameters 19 How to determine which sales have been paid out 22 Direct report API syntax 22

Further reading 23



INTRODUCTION Based on years of industry experience and feedback from hundreds of clients, advertisers and publishers

Partnerize built a unique, user friendly and intuitive management console. All of the features and functionality

that we have developed aim to give you, the user, a greater understanding of your performance based activity

and ultimately provide you with the tools to manage and optimize your campaign activity.

The management console is built on top of our own API, which is a unique feature within the performance

marketing industry. When you are given access to the management console, you are also inherently given

access to our API.

Q) What benefits or advantages does this offer? This means that any screen, interface, data or function that you see within the management console, can be

replicated through the API into your own applications or internal management systems. This provides you with

maximum flexibility and control in how you use and interact with our platform.



ACCESSING YOUR API CREDENTIALS Partnerize have designed the API to be as flexible as possible, implemented in both XML and JSON over

HTTP, using as many of the REST principles as possible.

Every Partnerize API call uses HTTP BASIC authentication over HTTPS providing a very dynamic, and secure

connection for processing your requests. Some programming languages will require you to pass this

authentication as a username and password credentials. In this case, the {API_KEY} is representative of the

username, and the {USER_API_KEY} is representative of the password.

All Partnerize API endpoints conform to the following syntax: https://{API_KEY}:{USER_API_KEY}@api.performancehorizon.com/{API_METHOD}/ To access your API credentials please navigate to Reporting -> Performance and

clicking Download Reports from within the Partnerize console.

Accessing API credentials



From this you will be presented with your unique API URI in a number of formats JSON / XML / CSV. Below outlines the most common API methods Overview report Direct sale report

Obtain tracking link

Obtain campaign creative Commission rates

API OVERVIEW REPORT The overview reports allow you to quickly access aggregated click/sale information, which is useful for

showing a holistic view of all the data generated on your campaign(s). These reports are used to show

overall stats for the chosen metric and they are status aware, allowing you to filter the results (where

applicable) by conversion status.

Overview API Syntax https://{API_KEY}:{USER_API_KEY}@api.performancehorizon.com/reporting/report_publisher/publisher/{PUBLISHER_ID}/overview.{json|xml}?start_date={START_DATE}&end_date={END_DATE} Required API Parameters

PARAMETER DESCRIPTION FORMAT NOTES {PUBLISHER_ID} The id of the String Can be retrieved via the

publisher on which to Partnerize console under generate the report Settings -> publisher

{START_DATE} Not required if YYYY-mm-dd hh:mm:ss You may need to URL

'period' time filter is encode the space. ie chosen YYYY-mm-

dd%20hh:mm:ss

{END_DATE} Not required if YYYY-mm-dd hh:mm:ss If omitted will retrieve up 'period' time filter is to current date chosen

{PERIOD} If 'period' time filter is day|week|month|year chosen



Optional API Parameters PARAMETER DESCRIPTION FORMAT NOTES {PIVOT_TYPE} The attribute upon primary|product|adref|pubref

which we should

pivot

{TIME_FILTER} Filter the result set range|period

by the given method

{RANK_IDENTIFIER How to rank the impression|click|conversion|com } resultset mission|ordervalue

{INTERVAL} If 'range' time filter ISO Standard interval code

is chosen

{STATUSES} Filter the results by approved|mixed|pending|rejected Can accept a status. GET array

statuses[]=pe

nding&statue

s[]=approved

{VERBOSE} Show totals per true|false

status

{TOTALS} Return non- true|false

paginated totals

{RELATED_IDS} Array to restrict Array

output based on

requested entities

{CURRENCY} Filter the results

based on currency

{TIMEZONE} Override the

campaign timezone

{WEEK_START} Override the String

campaign

week_start

Overview Wiki http://apidocs.performancehorizon.com/index.php?title=Reporting_Methods_(Publisher)#Overview_Reports



Example Valid Overview XML Response GET /reporting/report_publisher/publisher/2/overview.xml?start_date=2013-01-01&end_date=2013-06-30 <?xml version="1.0" encoding="UTF-8"?> <campaigns> <start_date_time>2011-01-01

10:00:00</start_date_time>

<end_date_time>2012-06-30

22:00:00</end_date_time>

<total_impression_count>33</total_impression_count>

<total_click_count>249766</total_click_count>

<total_conversion_count>

<GBP>59</GBP> </total_conversion_count> <total_commission_value> <GBP>492.9495</GBP> </total_commission_value> <total_order_value> <GBP>6688.63</GBP> </total_order_value> <total_rejection_rate> <percentage>0</percentage> <all_conversions_count>59</all_conversions_count>

<rejected_conversions_count>0</rejected_conversions_count

>

</total_rejection_rate> <total_quantity>62</total_quantity> <total_clickthrough_rate>756866.6667</total_clickthrough_rate> <total_ordersize_avg>1.0508</total_ordersize_avg> <count>18</count> <campaign>



<impressions>33</impressions> <clicks>249631</clicks> <currency> <GBP> <conversions>57</conversions> <ordervalue>3170.02</ordervalue> <quantity>57</quantity> <commissions>317.019</commissions> <ordervalue_avg>55.6144</ordervalue_avg> <conversion_rate>0.0228</conversion_rate> <earnings_per_click>0.0127</earnings_per_click> <ordersize_avg>1</ordersize_avg> </GBP> </currency> <quantity>57</quantity> <rejection_rate> <percentage>0</percentage> <all_conversions_count>57</all_conversions_count>

<rejected_conversions_count>0</rejected_conversions_count>

</rejection_rate> <clickthrough_rate>756457.5758</clickthrough_rate>

<ordersize_avg>1</ordersize_avg>

<campaign_id>5</campaign_id>

<title>Demo Advertiser Campaign</title> </campaign> ...



Example Valid Overview Pubref XML Response GET /reporting/report_publisher/publisher/2/overview/pubref.xml?start_date=2013-01-01&end_date=2013-06-30 <?xml version="1.0" encoding="UTF-8"

standalone="no"?> <pubrefs>

<start_date_time>2013-01-01

00:00:00</start_date_time>

<end_date_time>2013-06-29

23:00:00</end_date_time>

<total_impression_count>0</total_impression_count>

<total_click_count>1716</total_click_count>

<total_conversion_count>

<GBP>175</GBP> <EUR>148</EUR> <USD>168</USD> </total_conversion_count> <total_commission_value> <GBP>26972.61</GBP> <EUR>23961.04</EUR> <USD>28889.78</USD> </total_commission_value> <total_order_value> <GBP>305409.03</GBP> <EUR>274698.79</EUR> <USD>331492.43</USD> </total_order_value> <total_rejection_rate> <percentage>0</percentage> <all_conversions_count>491</all_conversions_count>



<rejected_conversions_count>0</rejected_conversions_count> </total_rejection_rate> <total_quantity>0</total_quantity> <total_clickthrough_rate>0</total_clickthrough_rate> <total_ordersize_avg>0</total_ordersize_avg> <count>11</count> <pubref> <impressions>0</impressions> <clicks>195</clicks> <currency> <GBP> <commissions>2554.31</commissions> <conversions>18</conversions> <ordervalue>30175.6</ordervalue> <quantity>0</quantity> <ordervalue_avg>1676.4222</ordervalue_avg> <conversion_rate>1083.3333</conversion_rate> <earnings_per_click>0.0065</earnings_per_click> <ordersize_avg>0</ordersize_avg> </GBP> <EUR> <commissions>2764.67</commissions> <conversions>17</conversions> <ordervalue>32494.71</ordervalue> <quantity>0</quantity> <ordervalue_avg>1911.4535</ordervalue_avg> <conversion_rate>1147.0588</conversion_rate> <earnings_per_click>0.006</earnings_per_click> <ordersize_avg>0</ordersize_avg>



</EUR> <USD> <commissions>4511.45</commissions> <conversions>21</conversions> <ordervalue>50920.29</ordervalue> <quantity>0</quantity> <ordervalue_avg>2424.7757</ordervalue_avg> <conversion_rate>928.5714</conversion_rate> <earnings_per_click>0.0038</earnings_per_click> <ordersize_avg>0</ordersize_avg> </USD> </currency> <quantity_all>0</quantity_all> <rejection_rate> <percentage>0</percentage> <all_conversions_count>56</all_conversions_count> <rejected_conversions_count>0</rejected_conversions_count> </rejection_rate> <clickthrough_rate>0</clickthrough_rate> <ordersize_avg>0</ordersize_avg> <pubref>Sample Pubref</pubref> </pubref> …



API DIRECT REPORT The direct reports allow you to access the full data records for the chosen metric (clicks / conversions) for

all approved campaigns. As this usually involves large volumes of data, these reports are paginated. The

pagination allows you to control the number of records to return in each request, whilst sending through the

overall number of records matching your chosen criteria. This allows you to build pagination through the

recordset thus keeping the data transfer times as fast as possible. These methods also allow you to order by

the time of the chosen metric, and filter the results based on status and pivot type.

Direct Report API Syntax https://{API_KEY}:{USER_API_KEY}@api.performancehorizon.com/reporting/report_publisher/publisher/{PUBLISHER_ID}/{REPORT_TYPE}.{json|xml} Required API parameters

PARAMETER DESCRIPTION FORMAT NOTES {PUBLISHER_ID} The unique id of String Can be retrieved via the

you publisher on Partnerize console under which to generate Settings->Publisher the report

{REPORT_TYPE} The type of report conversion|click to be generated

Optional API parameters

PARAMETER DESCRIPTION FORMAT NOTES {STATUSES} Filter the results approved|mixed|pending|r Passed as a GET array.

by status ejected Default approved & pending for conversions

{START_DATE} Not required if YYYY-mm-dd hh:mm:ss You may need to URL 'period' time filter encode the space. ie is chosen YYYY-mm-

dd%20hh:mm:ss

{END_DATE} Not required if YYYY-mm-dd hh:mm:ss 'period' time filter is chosen



Direct API wiki http://apidocs.performancehorizon.com/index.php?title=Reporting_Methods_(Publisher)#Direct_Reports Example Valid Direct XML Response GET /reporting/report_publisher/publisher/2/conversion.xml?start_date=2013-08-01&end_date=2013-08-01%2008:00:00 <?xml version="1.0" encoding="UTF-8"?> <conversions> <total_conversion_count> <GBP>1</GBP> </total_conversion_count> <total_publisher_commission> <GBP>10</GBP> </total_publisher_commission> <total_value> <GBP>600</GBP> </total_value> <start_date_time>2013-08-01 00:00:00</start_date_time> <end_date_time>2013-08-01 08:00:00</end_date_time> <offset>0</offset> <limit>300</limit> <count>1</count> <meta_data> <item>size</item> </meta_data> <conversion_data>



<conversion_id>10l11449484</conversion_id> <campaign_id>5</campaign_id> <publisher_id>2</publisher_id> <conversion_time>2013-08-01 07:01:57</conversion_time> <creative_type>0</creative_type> <creative_id>0</creative_id> <specific_creative_id>0</specific_creative_id> <currency>GBP</currency> <publisher_reference /> <advertiser_reference /> <conversion_reference>AUTO-51fa3216a8139</conversion_reference>

<customer_type>existing</customer_type>

<referer_ip>178.23.130.185</referer_ip> <source_referer />

<country>UK</country> <customer_reference /> <publisher_name>Demo Publisher</publisher_name> <campaign_title>

Demo Advertiser Campaign</campaign_title> <conversion_items>

<conversion_item> <conversion_item_id>10l11988853</conversion_item_id> <sku /> <category>SHOE</category> <item_value>600</item_value> <item_publisher_commission>10</item_publisher_commission> <item_status>pending</item_status> <publisher_self_bill_id /> <reject_reason /> <meta_data> <size>6</size> </meta_data> <voucher_codes />



</conversion_item> </conversion_items> <conversion_value> <conversion_status>pending</conversion_status> <value>600</value> <publisher_commission>10</publisher_commission> </conversion_value> <click> <campaign_id>5</campaign_id> <publisher_id>2</publisher_id> <status>nibbled</status> <set_time>2013-07-01 11:01:44</set_time> <set_ip>178.23.130.185</set_ip> <last_used>1375352176</last_used> <last_ip>178.23.130.185</last_ip> <publisher_reference /> <referer /> <creative_id>0</creative_id> <creative_type>0</creative_type> <specific_creative_id>0</specific_creative_id> </click> <meta_data /> <was_disputed /> <conversion_lag>13</conversion_lag> </conversion_data> </conversions> …



API PUBLISHER TRACKING LINK Every Partnerize campaign you are approved onto will contain your unique tracking link. This is used to drive

traffic from your sites which ultimately allocate sales and commission to your account. The tracking link API

call will return all your campaigns and their respective details in the format you specify (XML, JSON). This

output will contain campaign related data which includes commissions, participation status, etc.

Publisher Tracking Link API Syntax https://{API_KEY}:{USER_API_KEY}@api.performancehorizon.com/user/publisher/{PUBLISHER_ID}/campaign/{CAMPAIGN_STATUS}/{REPORT_TYPE}.{json|xml}

Required API parameters



{CAMPAIGN_STAT This is a reflection a|r|p a = approved US} of your status on r = rejected

the campaign p= pending

{REPORT_TYPE} The type of report tracking to be generated



Example Valid publisher tracking XML Response GET /user/publisher/2/campaign/a/tracking.xml <?xml version="1.0" encoding="UTF-8"?> <campaigns> <count>1</count> <campaign> <campaign_id>5</campaign_id> <title>Demo Campaign</title> <advertiser_id>2</advertiser_id> <status>a</status> <vertical_id>1</vertical_id> <default_override>0</default_override> <reporting_timezone>EST</reporting_timezone> <week_start>Monday</week_start> <conversion_type>sale</conversion_type> <payment_date></payment_date> <network_fee></network_fee> <hidden_campaign>y</hidden_campaign> <created>2013-07-11 22:02:44</created> <created_by>11l1065</created_by> <last_modified>2013-07-22 15:50:11</last_modified> ... … <publisher_status>a</publisher_status> <tracking_link>http://prf.hn/click/camref:{CAMREF}</tracking_link> </campaign> </campaigns>



Highlighted in red is the actual tracking link used to promote that particular campaign. {CAMREF} : campaign reference will be unique per campaign. CAMPAIGN CREATIVE Partnerize advertisers can provide a range of creative to assist publishers promoting their products (text links,

banners, html) To obtain all available creative assets for your active campaigns use the following API below.

Please note the creative links outputted will contain your distinct Partnerize publisher tracking link already so

no additional changes are required.

Campaign Creatives API Syntax https://{API_KEY}:{USER_API_KEY}@api.performancehorizon.com/user/publisher/{PUBLISHER_ID}/campaign/{CAMPAIGN_ID}/{REPORT_TYPE}.{json|xml}

Required API parameters



{CAMPAIGN_ID} The unique id of String Can be found by the campaign on invoking which to generate the report https://{API_KEY}:{USER

_API_KEY}@api.performa ncehorizon.com/user/pu blisher/{PUBLISHER_ID}/ campaign/a

{REPORT_TYPE} The type of report creative to be generated



Example Valid Campaign Creatives XML Response GET /user/publisher/2/campaign/5/creative.xml <?xml version="1.0" encoding="UTF-8"?> <creatives> <count>1</count> <creative> <creative_id>10l1529</creative_id> <campaign_id>10l48</campaign_id> <active>y</active> <creative_type_id>1</creative_type_id> <height>375</height> <width>500</width> <description>Sample Images</description> <destination>http://google.com/</destination> <start_date_time></start_date_time> <end_date_time></end_date_time> <default_specific_creative_id>10l3078</default_specific_creative_id> <advertiser_reference>sample</advertiser_reference> <created_at>2013-07-15 19:19:43</created_at> <created_by>5</created_by> <category_id>6</category_id> <custom_append_url_parameters></custom_append_url_parameters>

<preview>http://creative.prf.hn/preview/creativeref:10l1529</previe

w> <creative_items>

<creative_item> <creative_item_id>20</creative_item_id> <content_type>image/jpeg</content_type> AUTHOR: PARTNERIZE CLIENT SERVICES TEAM - [email protected] 19


<start_date_time></start_date_time> <end_date_time></end_date_time> <active>y</active> <specific_destination></specific_destination> <created_at>2013-07-15 19:20:07</created_at> <created_by>5</created_by> <description>Lake</description> <campaign_id>2</campaign_id> <creative_type_id>1</creative_type_id> <img_url>https://console.partnerize.com/upload/51e44b6129adblake.jpeg</img_url> <creative_remote_hosting>n</creative_remote_hosting> <custom_append_url_parameters></custom_append_url_parameters> <preview>http://creative.prf.hn/preview/screativeref:10l3078</preview> </creative_item> </creative_items>

<creative_tracking_link><script type="text/javascript"

src="http://creative.prf.hn/creative/camref:11l3oQ/creativeref:10l1529"></script></creative_tracking

_link>



PUBLISHER COMMISSION RATES To view the commission rates for a particular campaign and to see your own individual commissions (if

applicable) you can invoke the API end point below. The response will output all commissions across 3 tiers

● campaign_commission - default rate for campaign

● publisher_commission : specific rate if different to campaign

● group_commission : specific rate if you‘re assigned to a publisher group

By default the commission endpoint will include all historic rates, even those that are no longer active (these

can be filtered by including the active flag)

Publisher Commission API Syntax https://{API_KEY}:{USER_API_KEY}@api.performancehorizon.com/user/publisher/{PUBLISHER_ID}/campaign/{CAMPAIGN_ID }/commission.{json|xml} Required API parameters



{CAMPAIGN_ID} The unique id of String This can be found by the campaign on invoking the campaign which to generate API endpoint the report

https://{API_KEY}:{USER_ API_KEY}@api.performa ncehorizon.com/user/pu blisher/{PUBLISHER_ID}/ campaign/a/

Optional API parameters

PARAMETER DESCRIPTION FORMAT NOTES {active} Filter the results y|n Default will include

by active both active and commissions inactive commission

rates



Example Valid Commission XML Response GET /user/publisher/2/campaign/5/commission.xml?active=y <?xml version="1.0" encoding="UTF-8"?> <commissions> <count>3</count> <publisher_commission> <count>0</count> <commissions /> </publisher_commission> <group_commission>

<count>0</count>

<commissions />

</group_commission> <campaign_commission> <count>3</count> <commissions> <commission> <sale_type_info_id>1047031</sale_type_info_id> <campaign_id>5</campaign_id> <reference_id>5</reference_id> <reference_type>campaign</reference_type> <sale_type>bounty</sale_type> <sku /> <cookie_status /> <customer_type /> <category>DVD</category> <country /> <vertical /> <commission_rate /> <commission_value>50.0000</commission_value> AUTHOR: PARTNERIZE CLIENT SERVICES TEAM - [email protected] 22


<override /> <override_value /> <override_or_modify>override</override_or_modify> <start_date_time /> <end_date_time /> <active>y</active> <last_modified_by>331</last_modified_by> <last_modified>2013-08-06 14:01:07</last_modified> <priority /> <update_description /> <advertiser_reference /> <customer_reference /> </commission> <commission> <sale_type_info_id>7033</sale_type_info_id> <campaign_id>5</campaign_id> <reference_id>5</reference_id> <reference_type>campaign</reference_type> <sale_type>bounty</sale_type> <sku /> <cookie_status /> <customer_type /> <category>MUSIC</category> <country /> <vertical /> <commission_rate /> <commission_value>10.0000</commission_value> <override /> <override_value /> <override_or_modify>override</override_or_modify> <start_date_time /> <end_date_time /> <active>y</active> <last_modified_by>331</last_modified_by>



<last_modified>2013-08-06 14:07:49</last_modified> <priority /> <update_description /> <advertiser_reference /> <customer_reference /> </commission> <commission> <sale_type_info_id>10l7034</sale_type_info_id> <campaign_id>5</campaign_id> <reference_id>5</reference_id> <reference_type>campaign</reference_type> <sale_type>bounty</sale_type> <sku /> <cookie_status /> <customer_type /> <category>CD</category> <country /> <vertical /> <commission_rate /> <commission_value>35.0000</commission_value> <override /> <override_value /> <override_or_modify>override</override_or_modify> <start_date_time /> <end_date_time /> <active>y</active> <last_modified_by>331</last_modified_by> <last_modified>2013-08-06 14:08:46</last_modified> <priority /> <update_description /> <advertiser_reference /> <customer_reference /> </commission> </commissions>



HOW TO DETERMINE WHICH SALES HAVE BEEN PAID OUT Within the direct API reports, it is possible for publishers to identify which sales have been paid by advertisers. Direct Report API Syntax https://{API_KEY}:{USER_API_KEY}@api.performancehorizon.com/reporting/report_publisher/publisher/{PUB LISHER_ID}/conversion.{json|xml} Partnerize offers a <payable> node which defines if a sale has received funds. From this, publishers can

withdraw payment into their account.

To clarify, if it is “true” then it means it is available in a self-bill, or you have already been paid. If it is “false”

then it means the advertiser has not yet paid for it i.e. it is not self-billable.

This is what an items node will look like when things are payable (highlighted in red below): <conversion_items> <conversion_item> <conversion_item_id>10l11988853</conversion_item_id>

<sku />

<category>SHOE</category> <item_value>600</item_value> <item_publisher_commission>10</item_publisher_commission> <item_status>approved</item_status> <last_update>2013-01-01 00:00:00</last_update> <publisher_self_bill_id /> <reject_reason /> <meta_data> <size>6</size> </meta_data> <voucher_codes /> <payable>true</payable> To confirm, when it isn’t:



<conversion_items> <conversion_item> <conversion_item_id>10l11988853</conversion_item_id>

<sku />

<category>SHOE</category> <item_value>600</item_value> <item_publisher_commission>10</item_publisher_commission> <item_status>approved</item_status> <last_update>2013-01-01 00:00:00</last_update> <publisher_self_bill_id /> <reject_reason /> <meta_data> <size>6</size> </meta_data> <voucher_codes /> <payable>false</payable> Essentially, a simple Boolean node that will signify when you can class an item as something which you have

received the money for.

FURTHER READING Hopefully you will have a greater understanding of the main Partnerize API methods, if you would like

additional information please refer to the below:

http://apidocs.performancehorizon.com/index.php?title=Reporting_Methods_(Publisher) Or get in touch with our friendly team Email: [email protected] Please note that the API has different methods for Publishers and Advertisers, so please be sure that the call

you are making is associated to your respective role if necessary.




Date post:	24-Apr-2020
Category:	Documents
Upload:	others
View:	16 times
Download:	0 times

PUBLISHER API GUIDE - Partnerize · ACCESSING YOUR API CREDENTIALS Partnerize have designed the API...

Documents