1. Introduction

Welcome to MediumPath's documentation page, an account is required in order to use any of our tools.

2. Creating an app

An application is required to use any of our tools. Once you have created an app you will have an API KEY and a SECRET KEY that will be used for integration purpose (But before it, you will have to wait until your app get approved).

You can create an app easily by following steps below:

1. Login to your MediumPath Account.

2. Navigate to App >> Submit new app.

3. Choose type of app that you are intrested in.

3. Complete the form's fields and press Submit button.

4. You can check your submitted app by navigate to Apps >> My apps

5. Once your app got Approved, you will be able to see the API Key and Secret Key of your app that will be used for integration purpose in the My apps page.

3. Web Offerwall API

Iframe example

<iframe style="width:100%;height:800px;border:0;padding:0;margin:0;" scrolling="yes" frameborder="0" src="https://www.mediumpath.com/api/offerwall/?key=[api_key]&user_id=[user_id]&subid=[subid]&subid2=[subid2]&subid3=[subid3]"></iframe>

Offerwall parameters

[api_key]	*Required. You must replace this parameter by your app's API Key. If you don't have it yet, create an app with type "Web Offerwall" and wait until it's approved to get it.
[user_id]	*Required. You must replace this parameter by user id value of your app.
[subid]	Optional. The value of this parameter will be returned in the postback as subid parameter.
[subid2]	Optional. The value of this parameter will be returned in the postback as subid2 parameter.
[subid3]	Optional. The value of this parameter will be returned in the postback as subid3 parameter.

4. Offers API

JSON

To fetch the offers, make a call to

https://www.mediumpath.com/api/offers/?api_key=[API_KEY]

Change [API_KEY] by your app's API Key to fetch the offers. If you don't have it yet, create an app with type "Offers API" and wait until it's approved to get it.

Note: You should use API Key of "Offers API" app or it will not work.

Possible HTTP Response code

200	Everything is working correctly.
202	The API key is not valid.
203	The API Key is not set.
204	Everything is ok but no offers shown. This indicate some mistake in your filtering value or just no offers for your filtering requirement.

Tracking link parameters

[unique_user]	*Required. You must replace this parameter by user id value of your app.
[transaction]	*Required. The value of this parameter will be returned in the postback as subid parameter.
[subid2]	Optional. The value of this parameter will be returned in the postback as subid2 parameter.
[subid3]	Optional. The value of this parameter will be returned in the postback as subid3 parameter.
[iOS_Advertising_Identifier]	Optional. This is Identifier for Advertisers (IDFA) that created by Apple for advertising purpose and this will be available in iOS devices. If you put the offers in an iOS app then you can get this IDFA value and you should send the user's IDFA to us by replacing this parameter by the user's IDFA.
[Android_Advertising_Identifier]	Optional. This is Google Advertising ID (AAID) that created by Google for advertising purpose and this will be available in Android devices. If you put the offers in an Android app then you can get this AAID value and you should send the user's AAID to us by replacing this parameter by the user's AAID.

Definition of each value in each offer

id	Id of the offer
title	Title of the offer
conversion_goal	Requirement to complete the offer
payout_usd	Earning that will be credited to your account each time the offer completed
tracking_url	URL that will be used in order to access the offer
icon_optimized	Offers's creative that you can use for promotion purpose, and the file size is small (Optimized)
icon_hd	Offers's creative that you can use for promotion purpose, and the file is High Quality
target_countries	Countries that allowed to acces the offer
categories	The offer's categories for filtering and sorting purpose
completion_limit	The offer's completion limit. Example: "3, Daily" mean Max. 3 conversions per user daily. Example 2: "1, Lifetime" mean Max 1 conversion per user.
start_date	The date where the offer started
end_date	The date where the offer will be expired

Filtering (JSON)

categories	You can filter the offers by category, if you wanna show offer from multiple categories just seperate them by comma ','. Example: https://www.mediumpath.com/api/offers/?api_key=[API_KEY]&categories=survey,incent
devices	You can filter the offers by device (Available devices are: Desktop, Phone(android), Tablet(android), Android, iOS, iPad, iPhone, iPod), if you wanna show offer from multiple devices just seperate them by comma ','. Example: https://www.mediumpath.com/api/offers/?api_key=[API_KEY]&devices=desktop,ipad,android
countries	You can filter the offers by country in ISO 3166-2 format (country code with length of 2 characters), if you wanna show offer from multiple countries just seperate them by comma ','. Example: https://www.mediumpath.com/api/offers/?api_key=[API_KEY]&country=us,de

5. Setting up Postback

Whenever a user makes a conversion, we will send you a URL request called 'Server to Server Postback' with some information. Using this information, you can reward the user who performed the action accordingly. The postback will be sent to the postback URL you have defined in your MediumPath's App/Website. in Default we sent all datas in POST method but if you need GET method, you can simply include "pb_method=GET" into your postback URL, example:

https://www.example.com/pb.php?pb_method=GET&var1=var1_value&var2=var2_value

We recommend to you save the transId called in database, if the transId ever called before then you can deny the request cause possibly it's multiple call for same conversion.

Postback Parameters (POST method -- Default)

user_id	This is the app/website's user that complete the offer.
transId	Unique identification code of the transaction made by your user on Mediumpath.
reward	The amount of your virtual currency to be credited to your user.
currency	The name of your virtual currency.
signature	MD5 hash that can be used to verify that the call has been made from our servers. The value is MD5 HASH of user_id + transId + reward + Secret Key.
status	Determines whether to add or subtract the amount of the reward. "SUCCESS" is when the virtual currency should be added to the user and "ERROR" when it should be subtracted. This may be because the advertiser has canceled the user's transaction, either because he/she committed fraud or because it has been a mistake entering the data needed to complete the campaign.
userIp	The user's IP address who completed the action.
campaign_name	Name of the completed offer.
campaign_id	ID of the completed offer.
country	Country (ISO-3166-1: Alpha-2 country code format) from the lead comes.
subid	Custom tracking link parameter.
subid2	Custom tracking link parameter.
subid3	Custom tracking link parameter.

Postback Parameters (GET method)

{user_id}	This is the app/website's user that complete the offer.
{transId}	Unique identification code of the transaction made by your user on Mediumpath.
{reward}	The amount of your virtual currency to be credited to your user.
{currency}	The name of your virtual currency.
{signature}	MD5 hash that can be used to verify that the call has been made from our servers. The value is MD5 HASH of user_id + transId + reward + Secret Key.
{status}	Determines whether to add or subtract the amount of the reward. "SUCCESS" is when the virtual currency should be added to the user and "ERROR" when it should be subtracted. This may be because the advertiser has canceled the user's transaction, either because he/she committed fraud or because it has been a mistake entering the data needed to complete the campaign.
{userIp}	The user's IP address who completed the action.
{campaign_name}	Name of the completed offer.
{campaign_id}	ID of the completed offer.
{country}	Country (ISO-3166-1: Alpha-2 country code format) from the lead comes.
{subid}	Custom tracking link parameter.
{subid2}	Custom tracking link parameter.
{subid3}	Custom tracking link parameter.

We have examples for postback below (intended for understanding only, we recommend you add some additional code for security reason)

PHP example

if(!empty($_POST)){ $user_id = isset($_POST['user_id']) ? $_POST['user_id'] : ''; $transId = isset($_POST['transId']) ? $_POST['transId'] : ''; $reward = isset($_POST['reward']) ? $_POST['reward'] : ''; $currency = isset($_POST['currency']) ? $_POST['currency'] : ''; $signature = isset($_POST['signature']) ? $_POST['signature'] : ''; $status = isset($_POST['status']) ? $_POST['status'] : ''; $userIp = isset($_POST['userIp']) ? $_POST['userIp'] : ''; $campaign_id = isset($_POST['campaign_id']) ? $_POST['campaign_id'] : ''; $country = isset($_POST['country']) ? $_POST['country'] : ''; $secret = "[YOUR_WEBSITE/APP_SECRET_KEY]"; // check your app info at www.mediumpath.com $user_id = isset($_POST['user_id']) ? $_POST['user_id'] : ''; $transId = isset($_POST['transId']) ? $_POST['transId'] : ''; $reward = isset($_POST['reward']) ? $_POST['reward'] : ''; $signature = isset($_POST['signature']) ? $_POST['signature'] : ''; if(md5($user_id.$transId.$reward.$secret) == $signature){ //Here is functions for SUCCESS echo 'ok'; }else{ echo 'error'; exit; } }else{ echo 'error'; }

IP addresses that need to be whitelisted

208.113.144.123

2607:f298:5:117a::1dc:d185

67.205.41.134

173.236.129.24