igastepniak/Publisher API documentation.md Secret

## Publisher API documentation.md

      
    Raw
  

              Publisher API documentation.md
            
          
    #Publisher API Documentation#
Table of Content:

Transactions Report
Clicks Report
Trades Report
Offers Report
Offer details
Offer ads
Codes
Text and Banner codes
Application for tests
FAQ


This document describe how to work with Publisher API provided by Target Circle platform. API enable to:

fetch Transactions Report
fetch Click Report
fetch Offers report
fetch available Trades


1. Transactions Report

Step A - generate report


URL
/api/transactions


Method:
POST


Header Attribute:
X-Api-Token : <Your account api token>


Payload:


{	
	"from": "2015-06-01T00:00:00Z",
	"to": "2015-12-30T23:59:59Z",
	"currency": "EUR",
	"status": null,
	"offer": null,
	"adInventory": null,
	"reference": null,
	"country": null,
	"limit": 100
}


Required:

from=[String]
to=[String]
currency=[String]


Optional:

status=[String]
offer=[String] - comma separated values (means logic OR)
adInventory=[String] - comma separated values (means logic OR)
country=[String] - comma separated values (means logic OR)
limit=[100] - maximum limit value is 1000. Default is set to 100


Success Response:

Code: 202 Accepted 

Location: /api/transactions/680ffeed-b274-4a59-9219-a7e5ec52346b?page=1


Error Response:

Code: 401 Unauthorized 

Content: No valid account with token = <Given Token>

OR

Code: 408 Request timeout 

Content: Request Time Out


Step B - fetch report

Location header contain URL for generated report.


URL
/api/transactions/


Method:
GET


Header Attribute:
X-Api-Token : <Your account api token>


URL Params
Required:
page=[integer]


Success Response:

Code: 200 Accepted 

Content: {"data":[],"token":"SDhV/+kyKhtuuZAZ+kUuQPFAXRXoD05Q","status":"IN_PROGRESS","pagesNumber":0} 

Location: </api/transactions/249dab52-e495-406b-979d-282ba452c82a?page=2>; rel="next", </api/transactions/249dab52-e495-406b-979d-282ba452c82a?page=1>; rel="first", </api/transactions/249dab52-e495-406b-979d-282ba452c82a?page=10>; rel="last"

There are 3 possbile statutes:

IN_PROGRESS - report is not ready yeat. API should be called once again later (as long as READY or FAILED status will be in response).
FAILED - some error ocure. There wont be report for given report Id
READY - Report was genereated successfuly

data - array with given page of report. By default page containt 10 positions 

pagesNumber - show how many pages report has
Use Location header values for navigation over the report.


Error Response:

Code: 401 Unauthorized 

Content: No valid account with token = <Given Token>

OR

Code: 408 Request timeout 

Content: Request Time Out


Sample Response:


{
	"data": [{
		"conversionStatus": "approved, paid out",
		"slug": "3sdfa",
		"offerName": "SomeWebsite.com",
		"mediaName": "Media",
		"productGroupName": "Some group",
		"transactionType": "lead",
		"trackingMethod": "tmt_cookie",
		"trackingId": "rfh53445-fa27-9a41-4471-14a3a5561723",
		"adLinkName": "Main Page",
		"reference": ["BrandGenerics"],
		"transactionAmount": 0.0,
		"currency": "EUR",
		"commission": 25.0,
		"commissionRep": 25.0,
		"country": "Germany",
		"saved": "2015-12-29T22:37:58Z"
	}],
	"token": "sf3jtsgCUZ123fdg34gfdeCl823f24RFiX",
	"status": "READY",
	"pagesNumber": 1
}


Notes:
Generated report is cached in memory for some time. If new report is required start again from Step A.


2. Clicks Report


URL
/api/clicks


Method:
POST


Header Attribute:
X-Api-Token : <Your account api token>


Payload:


{	
	"from": "2015-06-01T00:00:00Z",
	"to": "2015-12-30T23:59:59Z",
	"adInventory": null,
	"country": null,
	"offer": null,
	"reference": null,
	"country": null,
	"limit": 100
}


Required:

from=[String]
to=[String]


Optional:

offer=[String] - comma separated values (means logic OR)
adInventory=[String] - comma separated values (means logic OR)
country=[String] - comma separated countries - Germany,Norway
limit=[100] - maximum limit value is 1000. Default is set to 100


Success Response:

Code: 202 Accepted 

Location: /api/clicks/680ffeed-b274-4a59-9219-a7e5ec52346b?page=1


Error Response:

Code: 401 Unauthorized 

Content: No valid account with token = <Given Token>

OR

Code: 408 Request timeout 

Content: Request Time Out


Step B - fetch report

Location header contain URL for generated report.


URL
/api/clicks/


Method:
GET


Header Attribute:
X-Api-Token : <Your account api token>


URL Params
Required:
page=[integer]


Success Response:

Code: 200 Accepted 

Content: {"data":[],"token":"SDhV/+kyKhtuuZAZ+kUuQPFAXRXoD05Q","status":"IN_PROGRESS","pagesNumber":0} 

Location: </api/clicks/249dab52-e495-406b-979d-282ba452c82a?page=2>; rel="next", </api/clicks/249dab52-e495-406b-979d-282ba452c82a?page=1>; rel="first", </api/clicks/249dab52-e495-406b-979d-282ba452c82a?page=10>; rel="last"


Error Response:

Code: 401 Unauthorized 

Content: No valid account with token = <Given Token>

OR

Code: 408 Request timeout 

Content: Request Time Out


Sample Response:


{
	"data": [{
		"slug": "3cf504",
		"mediaName": "Media Name",
		"offerName": "AwesomePage.com",
		"reference": ["NL_COMP"],
		"country": "Netherlands",
		"ip": "10.100.10.100",
		"clickDate": "2015-12-29T22:59:40Z"
	}],
	"token": "gsdfds4324GWEwE8NjnXDCl8RXriX",
	"status": "READY",
	"pagesNumber": 1
}


3. Trades Report


URL
/api/trades


Method:
POST


Header Attribute:
X-Api-Token : <Your account api token>


Payload:


{
	"limit": 100,
	"offer": null,
	"adInventory": null,
	"provider": null,
	"category": null,
	"conversionType": null,
	"engagementType": null,
	"vertical": null,
	"adType": null,
	"targetCountries": "Germany,Norway"
}


Optional:

offer=[String] - comma separated values (means logic OR)
adInventory=[String] - comma separated values (means logic OR)
provider=[String] - comma separated values (means logic OR)
category=[String] - comma separated values (means logic OR)
conversionType=[String] - comma separated values (means logic OR)
engagementType=[String] - comma separated values (means logic OR)
vertical=[String] - comma separated values (means logic OR)
adType=[String] - comma separated values (means logic OR)
targetCountries=[String] - comma separated countries - Germany,Norway
limit=[100] - maximum limit value is 1000. Default is set to 100


Success Response:

Code: 202 Accepted 

Location: /api/trades/680ffeed-b274-4a59-9219-a7e5ec52346b?page=1


Error Response:

Code: 401 Unauthorized 

Content: No valid account with token = <Given Token>

OR

Code: 408 Request timeout 

Content: Request Time Out


Step B - fetch report

Location header contain URL for generated report.


URL
/api/trades/


Method:
GET


Header Attribute:
X-Api-Token : <Your account api token>


URL Params
Required:
page=[integer]


Success Response:

Code: 200 Accepted 

Content: {"data":[],"token":"SDhV/+kyKhtuuZAZ+kUuQPFAXRXoD05Q","status":"IN_PROGRESS","pagesNumber":0} 

Location: </api/trades/249dab52-e495-406b-979d-282ba452c82a?page=2>; rel="next", </api/trades/249dab52-e495-406b-979d-282ba452c82a?page=1>; rel="first", </api/trades/249dab52-e495-406b-979d-282ba452c82a?page=10>; rel="last"


Error Response:

Code: 401 Unauthorized 

Content: No valid account with token = <Given Token>

OR

Code: 408 Request timeout 

Content: Request Time Out


Sample Response:


{
	"data": [{
		"id": 11014,
		"type": "legacy",
		"status": "accepted",
		"adInventory": "Some adInventory",
		"offer": {
			"name": "AwesomeStuff.no",
			"href": "/api/offers/691a1d"
		},
		"category": null,
		"provider": "Target Circle AS",
		"verticals": [""],
		"pricings": [{
			"id": 123,
			"commision": 10.0,
			"commisionType": "Fixed",
			"conversionType": "lead",
			"engagementType": "Post click",
			"productGroup": "Default",
			"offerPricingCountries": ["Norway"]
		}, {
			"id": 11238,
			"commision": 310.0,
			"commisionType": "Fixed",
			"conversionType": "lead",
			"engagementType": "Post click",
			"productGroup": "Default",
			"offerPricingCountries": ["Rest of World"]
		}]
	}],
	"token": "S123VDFGFR434Ggse3XoD05Q",
	"status": "READY",
	"pagesNumber": 1
}


4. Offers Report


URL
/api/offers


Method:
GET


Header Attribute:
X-Api-Token : <Your account api token>


URL Params (all values are optional and should be added as GET request params) **
"limit": 100, - - maximum limit value is 1000. Default is set to 100
"offerId”: null,
"offerName": null, - - comma separated values (means logic OR)
"adInventory": null, -- comma separated values (means logic OR)
"status": null, -- comma separated values (means logic OR)
"startDateFrom": null,
"startDateTo": null,
"endDateFrom": null,
"endDateTo": null,
"provider": null, -- comma separated values (means logic OR)
"category": null, -- comma separated values (means logic OR)
"advertiser": null, -- comma separated values (means logic OR)
"vertical": null, -- comma separated values (means logic OR)
"country": null -- comma separated values (means logic OR)


Success Response:


Header Attribute:
X-Api-Token : <Your account api token>


Success Response:

Code: 200 Accepted 


Error Response:

Code: 401 Unauthorized 

Content: No valid account with token = <Given Token>

OR

Code: 408 Request timeout 

Content: Request Time Out


Sample Response:


{
    "token": "S123VDFGFR434Ggse3XoD05Q",
    "data" : [{
        "id" : 122,
        "name" : "zedge.net",
        "offers" : [{
            "id" : 11014,
            "name" : "Diamond Digger Saga (iPhone)",
            "status" : "accepted",
            "startDate" : "2016-04-12",
            "endDate" : "2017-04-23",
            "provider" : "Target Circle",
            "advertiser" : "King.com Limited",
            "vertical" : "Services",
            "catergory" : "Games",
            "tracking" : {
                "deeplinking": true,
                "cookieExpiration": {
                    "value": 0,
                    "unit": "hours"
                },
                "fingerprintExpiration": {
                    "value": 0,
                    "unit": "hours"
                },
                "impressionExpiration": {
                    "value": 0,
                    "unit": "hours"
                }
            },
            "targetedCountries" : ["FR", "DE", "NO", "PL"],
            "policies": [{
                "name": "Deeplinking",
                "group": "permitted",
                "note": null
            }, {
                "name": "Custom creatives",
                "group": "permitted",
                "note": null
            }],
            "termsAndConditions" : "- US Only - No Daily Caps - No Incent - No Adult",
            "currency" : "USD",
            "highestPayout" : 1.95,
            "pricings" : [{
                "countries" : ["FR"],
                "productGroup" : "Default",
                "transactionType" : "Install",
                "engagementType" : "Post click",
                "commissionType" : "Fixed",
                "currency" : "USD",
                "payout" : 0.32,
            }, {
                "countries" : ["DE"],
                "productGroup" : "Default",
                "transactionType" : "Install",
                "engagementType" : "Post click",
                "commissionType" : "Fixed",
                "currency" : "USD",
                "payout" : 0.40,
            }, {
                "countries" : ["NO"],
                "productGroup" : "Default",
                "transactionType" : "Install",
                "engagementType" : "Post click",
                "commissionType" : "Fixed",
                "currency" : "USD",
                "payout" : 0.37,
            }, {
                "countries" : ["PL"],
                "productGroup" : "Default",
                "transactionType" : "Install",
                "engagementType" : "Post click",
                "commissionType" : "Fixed",
                "currency" : "USD",
                "payout" : 0.48,
            }]
        }]
    }]
}


4. Codes


URL
/api/codes


Method:
GET


Header Attribute:
X-Api-Token : <Your account api token>


URL Params (all values except offerId and adInventory are optional and should be added as GET request params) **
"limit": 100, - - maximum limit value is 1000. Default is set to 100
"offerId": null,
"adInventory": null,
"deeplink": null,
"parameters[idfa]": null,
"parameters[gaid]": null,
"parameters[waid]": null,
"parameters[click_id]": null,
"parameters[source_id]": null,
"parameters[ref1]": null,
"parameters[ref2]": null,
"parameters[ref3]": null,
"parameters[ref4]": null,
"parameters[ref5]": null,
"type": null,
"maxHeight": null,
"minHeight": null,
"maxWidth": null,
"minWidth": null,
"maxSize": null,
"minSize": null,


Success Response:


Header Attribute:
X-Api-Token : <Your account api token>


Success Response:

Code: 200 Accepted 


Error Response:

Code: 401 Unauthorized 

Content: No valid account with token = <Given Token>

OR

Code: 408 Request timeout 

Content: Request Time Out


Sample Response:


{
    "data" : [{
        "id" : "8tas1y",
        "name" : "Summer sale 2016",
        "type" : "banner",
        "isDefault" : true,
        "targetedCountries" : ["FR", "DE", "NO", "PL"],
        "clickUrl" : "https://c.trackmytarget.com/27ig76",
        "bannerDetails" : {
            "impressionUrl": "https://i.trackmytarget.com/q67db8",
            "height" : 297,
            "width" : 297,
            "fileSize" : 48988,
            "fileType" : "image/jpeg"
        }
    }, {
        "id" : "9mw769",
        "name" : "Summer sale 2016",
        "type" : "text link",
        "isDefault" : true,
        "targetedCountries" : ["FR", "DE", "NO", "PL"],
        "clickUrl" : "https://c.trackmytarget.com/278g36",
        "bannerDetails" : null
    }]
}


4. Offer details


URL
/api/offers/:slug


Method:
`GET


URL Params
Required:
slug=[string] - offer identifier


Header Attribute:
X-Api-Token : <Your account api token>


Success Response:

Code: 200 

Content:


{
	"slug": "m0496v",
	"name": "Brand new offer",
	"targetUrl": "http://www.awesome.com",
	"general": {
		"adInventory": [{
			"name": "Some Awesome Page",
			"slug": "11326b"
		}],
		"provider": "Some Provider",
		"advertiser": "An Advertiser",
		"vertical": "Travel",
		"category": "Camping"
	},
	"tracking": {
		"deeplinking": true,
		"cookieExpiration": {
			"value": 0,
			"unit": "hours"
		},
		"fingerprintExpiration": {
			"value": 0,
			"unit": "hours"
		},
		"impressionExpiration": {
			"value": 0,
			"unit": "hours"
		}
	},
	"policies": [{
		"name": "Deeplinking",
		"group": "permitted",
		"note": null
	}, {
		"name": "Custom creatives",
		"group": "permitted",
		"note": null
	}],
	"targetedCountries": ["Germany"]
}


5. Offer ads


URL
/api/offers/:slug/ads


Method:
`GET


URL Params
Required:
slug=[string] - offer identifier


Header Attribute:
X-Api-Token : <Your account api token>


Success Response:

Code: 200 

Content:


[{
	"slug": "8tas1y",
	"name": "ad",
	"targetUrl": null,
	"type": "BANNER",
	"bannerDetails": {
		"url": "http://127.0.0.1:8001/banners/1115/img",
		"dimensions": "297x297",
		"size": {
			"value": 36.74,
			"unit": "kB"
		}
	}
}, {
	"slug": "9mw769",
	"name": "VC Blog",
	"targetUrl": "http://www.awesome-page.com",
	"type": "TEXT",
	"bannerDetails": null
}]


6. Text and Banner codes


URL
/api/codes/:type


Method:
POST


URL Params
Required:
type=[string] - ad type: 'banner' or 'text'


Header Attribute:
X-Api-Token : <Your account api token>


Payload:


{
	"offer": "m0496v",
	"adInventory": "11c26b",
	"ads": ["8t171y"]
}


Required:

offer = [String] - offer slug
adInventory = [String] - ad inventory slug
ads = List[String] - list of ad slugs (all have to be same kind as type in url


Success Response:

Code: 200 

Content:


[{
	"id": 1115,
	"slug": "8tf71y",
	"name": null,
	"height": 297,
	"width": 297,
	"dimension": "297x297",
	"fileSize": 48988,
	"type": "image\/jpeg",
	"targetUrl": "http:\/\/www.awesome.com",
	"isDefault": null,
	"imgUrl": "\/banners\/1115\/img",
	"impressionUrl": "https:\/\/i.trackmytarget.com\/q67db8",
	"clickUrl": "https:\/\/c.trackmytarget.com\/q67db8"
}]


7. Application for Tests

Under URL http://54.171.151.134:8090/ there is small application which allows to test API with simple GUI.
First, put Your valid Token into API token field. Then select one of report. Fill in parameters (if necessary). Press Call  api button. After a while press Fetch report button. Result should be shown bellow button. When report is not yet ready Report status label should has value IN_PROGRESS.

FAQ

1. How to start?

Get your publisher account token. Contant with Target Circle team to get valid token.
2. How receive available Offers?

To verify if there are any offers use API testing application (http://54.171.151.134:8090/). In Reports section put your token in Api token field and select Trade Report. Then click Call api and after a while click Fetch report to get results. If you want use API programaticly read Trades Report section.