PERFORMANCE HORIZON PUBLISHER API INTRODUCTION

Transcription

1 PERFORMANCE HORIZON PUBLISHER API INTRODUCTION Version 1.0 October 2016

2 WHY USE API S 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 optimise your campaign activity. Our platform is built on top of our own API, which is a unique feature within the performance marketing industry. Why is it beneficial? Using API calls allows users to download reports and data in different file formats through Http requests which can be done through your browser. The API also allow users to integrate data with other marketing tools and applications. How to create a call NETWORK KEY AND USER KEY: Every PH 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 PH API endpoints conform to the following syntax: The API_KEY is the authorisation key for the network that you are working on; The USER_API_KEY is unique to your publisher account and is effectively your API passcode enabling you to access your reporting data. These two keys must be inserted by you, where shown in the example API call.

3 HOW TO FIND YOUR API CREDENTIALS i) Navigate to Reporting>Performance and click on Download Reports as shown below: ii) You should see the all of the API calls with the CSV, JSON and XML links start with these credentials. If you copy and pasted one of the links above from a demo account and examined it: version.csv?start_date= %3a00%3a00&end_date= %3A00%3A00&publisher_id=1l300788&convert_currency=GBP iii) Your Network API Key and User API key can be found in this part of the platform. Once you have found your API credentials these credentials will remain the same for all API requests from your account

4 API Reporting Formats CSV Format If you wish the information to be downloaded in CSV (comma-separated-values) format so that it can be viewed in spreadsheet format with programs like Excel. Insert.CSV before the?start_date= or?text_date= part of the API call. See the Quick Reference API calls for examples. Standard Report vs Item Report The Standard Conversion report will give details of orders at the basket level. In Conversion Item reports you will be able to see details of each item including individual item s commission and value as each item will be listed on its own row within the report. XML and JSON Formats If you wish the data to be shown in JSON (Java Script Object Notation) or XML (Extensible Mark-up Language). You may wish to do this if you want to view the data in another programme or system. Insert.json or.xml as required before the?start_date= or?text_date= part of the API call. See the Quick Reference API calls for examples. Date Formats text_date can take multiple forms i.e text_date=last+week (or) text_date=last+month (or) text date=last+year. It can also be the current time period if you replace last with this. (e.g text_date=this+week) Start_date/End_date will always take the format of YYYY-MM-DD where Y is the year, M is the month and D is the day. You can also add a specific time to the start date or end date YYYY-MM-DD hh:mm:ss where hh is the hour in 24 hour time, mm is the minutes and ss is the seconds. Therefore a start_date= would mean the report start date would be the 2 nd of January at 5 minutes and 1 seconds past midnight. If however you do not include the time or hh:mm:ss part of the call it will default to midnight.

5 QUICK REFERNCE API CALLS This page will give you examples of the most common API calls you are likely to require. Conversions by Week Standard report CSV: ext_date=last+week&publisher_id={publisher_id} Item Report CSV: csv?text_date=last+week&publisher_id={publisher_id} JSON or XML: BLISHER_ID}/conversion.{json/xml}?text_date=last+week Conversions by Custom Standard report CSV: art_date={start_date}&end_date={end_date}&publisher_id={publisher_id} Item report CSV: csv?start_date={start_date}&end_date={end_date}&publisher_id={publisher_id} JSON or XML: BLISHER_ID}/conversion.{json/xml}?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD

6 Commissions by product (Custom) CSV: BLISHER_ID}/overview/primary/range/ordervalue.csv? start_date=yyyy-mm-dd&end_date=yyyy-mm-dd JSON or XML: BLISHER_ID}/overview/primary/range/ordervalue.{json/xml}?start_date=YYYY-MM-DD&end_date=YYYY-MM- DD Campaign Commissions To view the commission applicable to you via the API you will need to know the CAMPAIGN_ID. If you do not have the CAMPAIGN_ID, you can get it by invoking another endpoint: The above will return all campaigns that the provided publisher has access to, either pending, rejected, and/or approved. These can be filtered by the aforementioned statuses as well, and is documented here: ampaigns /{CAMPAIGN_ID}/commission The above will return all commission rates applicable on a specific campaign. As an example, you could get all commissions for all campaigns by looping through the API calls: This above API call with return an array of campaigns. You would then loop through them as follows: /ID1/commission /ID2/commission