Академический Документы
Профессиональный Документы
Культура Документы
Table of Contents:
1 Introduction ................................................................................................ 2
2 Document History ........................................................................................ 2
3 REST API .................................................................................................... 3
3.1 Affiliate REST API ................................................................................... 3
3.1.1 Authentication and security ............................................................. 3
3.1.2 Methods Implementation ................................................................ 3
3.1.2.1 Method Affiliate:getData ........................................................................ 3
3.1.2.2 Method Affiliate:update ......................................................................... 4
3.1.2.3 Method AffiiateUser:create ..................................................................... 5
3.1.2.4 Method AffiliateUser:update ................................................................... 6
3.1.2.5 Method AffiliateUser:getById .................................................................. 7
3.1.2.6 Method AffiliateUser:getPermission ......................................................... 8
3.1.2.7 Method AffiliateUser:delete .................................................................... 8
3.1.2.8 Method Offer:getById ............................................................................ 9
3.1.2.9 Method Offer:findAll .............................................................................. 9
3.1.2.10 Method Offer:creatives ......................................................................... 11
3.1.2.11 Method Offer:getTargeting .................................................................... 12
3.1.2.1 Method Offer:getCapping ...................................................................... 13
3.1.2.2 Method Offer:generateTrackingLinks ...................................................... 14
3.1.2.3 Method Statistics:getStatistics ............................................................... 14
3.1.2.4 Method Statistics:getReferrals ............................................................... 16
3.1.2.5 Method Login:ExternalAccess ................................................................ 16
3.2 Resources .............................................................................................17
3.2.1 Affiliate resource ...........................................................................17
3.2.2 BillingSettings resource .................................................................17
3.2.3 SignupQuestion resource ...............................................................17
3.2.4 SignupQuestionAnswer resource .....................................................18
3.2.5 AffiliateUser resource ....................................................................18
3.2.6 AdminUser resource ......................................................................18
3.2.7 UserAccessRightResource resource .................................................18
3.2.8 Tracking resource .........................................................................19
3.2.9 PaymentMethod resource ...............................................................19
3.2.10 Offer resource ..............................................................................19
3.2.11 SpecificPayoutSettings resource ......................................................20
3.2.12 VAT resource ................................................................................20
3.2.13 UserLoginResource ........................................................................20
3.3 HTTP Response Statuses ........................................................................20
1(20) PUBLIC
API Description
1 Introduction
Purpose of this document is to give detail description of application programming interfaces of
Affiliate Software.
2 Document History
Date Version Remark
2013-04-24 1.0 Initial version
2013-09-04 1.1 Update responses
2013-10-11 1.2 Update responses and parameters
2014-02-07 1.3 API methods added
2014-02-12 1.4 API methods URL updated
2014-02-24 1.5 Authorization, statuses and resources added
2014-05-16 1.6 Offers updated and conversion link added
2014-06-05 1.7 Statistics method added
2014-08-18 1.8 Affiliate REST API methods added
2014-08-22 1.9 Specific Payout Settings resource added
2014-10-01 1.10 Document updated
2014-12-15 1.11 Specific payout settings added
2015-05-22 1.12 Document updated
2015-06-04 1.13 Methods and parameters improvement
2015-09-22 1.14 Document updated
2015-10-20 1.15 External access login method added
2015-11-26 1.16 Document updated
2016-01-20 1.17 Document updated
2016-06-10 1.18 Methods Offer: getByid and Offer: findAll improved
2016-06-10 1.19 New Offer resource for methods: getByid, findAll added
2016-06-13 1.20 New SpecificPayoutSettingsResource resource added
2016-06-14 1.21 Document updated
2016-09-30 1.22 Document updated
2016-10-17 1.23 Document updated
2017-01-13 1.24 Add option to retrieve offer targeting and offer capping
2(20) PUBLIC
API Description
3 REST API
The goal of the API is to enable a server to sever integration of the AdCumulus platform with other
platforms so that the data transfer and updates can be done automatically. Most of the functions
that are available on the Users Interface can also be found in this API. For each User Interface
there is a dedicated REST API set of methods: Admin, Affiliate and Advertiser REST API. The
network time zone is used as a default time zone for the API.
Next, I will show an example for how one valid authentication should look like:
http://your.gui.domain.com/v1affiliate/service/rest-affiliate/affiliate
3(20) PUBLIC
API Description
"minimalPayoutAmount" : 50.0,
"note" : "",
"paymentMethodId" : 1,
"paymentMethodParameters" : [ { "id" : 1,
"name" : "beneficiary_name",
"value" : "Nekaj"
},
{ "id" : 2,
"name" : "account_number",
"value" : "12345-12345678"
},
{ "id" : 3,
"name" : "bank_account_number",
"value" : "12345-12345678"
},
{ "id" : 4,
"name" : "bank_name",
"value" : "Unknown"
}
],
"phone" : "",
"status" : "ACTIVE",
"vatId" : 2,
"zipCode" : "40319",
"language" : "GERMAN"
}
http://your.gui.domain.com/v1affiliate/service/rest-affiliate/affiliate
4(20) PUBLIC
API Description
{ "id" : 3,
"name" : "bank_account_number",
"required" : "true",
"value" : "12345-12345678"
},
{ "id" : 4,
"name" : "bank_name",
"required" : "true",
"value" : "Unknown"
}
],
"phone" : "",
"vatId" : 2,
"zipCode" : "40319",
"language" : "GERMAN"
}
5(20) PUBLIC
API Description
http://your.gui.domain.com/v1affiliate/service/rest-affiliate/affiliateUser
{ "accessRights" : [ { "id" : 7,
"section" : "offers",
"value" : "READ"
} ],
"firstName" : "TestFirstName",
"lastName" : "testLastName",
"password" : "testPassword",
"status" : "ACTIVE",
"username" : "restaffiliate4@nth.ch"
}
{ "affiliatePayoutType" : "TestAffiliatePayoutType",
"affiliateRights" : { "affiliateRightsParam1 " : "affiliateRightsValue1" },
"categoryList" : "TestCategory1",
"categoryWebList" : null,
{ "accessRights" : [ { "id" : 7,
"section" : "offers",
"value" : "READ"
} ],
"affiliateId" : 2,
"firstName" : "TestFirstName",
"lastName" : "testLastName",
"password" : "testPassword",
"status" : "ACTIVE",
"userId" : 213,
"username" : "restaffiliate4@nth.ch"
}
http://your.gui.domain.com/v1affiliate/service/rest-affiliate/affiliateUser/97
6(20) PUBLIC
API Description
{ "accessRights" : [ { "id" : 7,
"section" : "offers",
"value" : "READ"
},
{ "id" : 8,
"section" : "analytics",
"value" : "READ"
}
],
"firstName" : "TestFirstName1",
"lastName" : "TestLastName2",
"password" : "TestPassword",
"status" : "ACTIVE"
}
{ "accessRights" : [ { "id" : 7,
"section" : "offers",
"value" : "READ"
},
{ "id" : 8,
"section" : "analytics",
"value" : "READ"
}
],
"affiliateId" : 2,
"firstName" : "TestFirstName1",
"lastName" : "TestLastName2",
"password" : "TestPassword",
"status" : "ACTIVE",
"userId" : 97,
"username" : "test1@nth.ch"
}
http://your.gui.domain.com/v1affiliate/service/rest-affiliate/affiliateUser/97
{ "accessRights" : [ { "id" : 7,
"section" : "offers",
"value" : "READ"
7(20) PUBLIC
API Description
},
{ "id" : 8,
"section" : "analytics",
"value" : "READ"
}
],
"affiliateId" : 2,
"firstName" : "TestFirstName1",
"lastName" : "TestLastName2",
"password" : "",
"status" : "ACTIVE",
"userId" : 97,
"username" : "test1@nth.ch"
}
http://your.gui.domain.com/v1affiliate/service/rest-affiliate/affiliateUser/permission
[ { "id" : 7,
"name" : "Offer Management",
"section" : "offers"
},
{ "id" : 8,
"name" : "Analytics Management",
"section" : "analytics"
}
]
8(20) PUBLIC
API Description
http://your.gui.domain.com/v1affiliate/service/rest-affiliate/affiliateUser/97
http://your.gui.domain.com/v1affiliate/service/rest-affiliate/offer/79
{
"id": 360
"name": "Not1 offer"
"description": "Description Not1 offer"
"status": "ACTIVE"
"categoryList": [2]
0: "druga"
1: "Donauschiffartskapitän"
"expirationDate": "19-03-2018 14:33:49"
"requireApproval": true
"previewUrl": "http://google.com"
"payoutType": "PER_ACTION"
"payoutModelType": "ONE_TIME"
"payoutCost": [1]
0: "12"
"terms": "Terms for offer Not1"
"specificSettings": [1]
{
"id": 412
"offerId": 360
"affiliateId": 15018
"event": "ANY_EVENT"
"eventName": null
"cost": [1]
0: "78"
}
"currency": "EUR"
}
9(20) PUBLIC
API Description
http://your.gui.domain.com/v1affiliate/service/rest-affiliate/offer/findAll
[{
"id": 468
"name": "Offer12"
"description": "Offer12 desc"
"status": "ACTIVE"
"categoryList": [0]
"expirationDate": "06-04-2017 03:59:59"
"requireApproval": false
"previewUrl": "http://gizmodo.com"
"payoutType": "PER_ACTION_AND_PER_SALE"
"payoutModelType": "MULTIPLE_CUSTOM_COST"
"payoutCost": [2]
0: "1+2"
1: "3+4"
"terms": null
"specificSettings": [0]
"currency": "EUR"
},
{
"id": 472
"name": "Offer4"
"description": "test desc"
"status": "ACTIVE"
"categoryList": [1]
0: "DS Test"
"expirationDate": "11-03-2017 04:59:59"
"requireApproval": false
"previewUrl": "http://google.com"
"payoutType": "PER_ACTION_AND_PER_SALE"
"payoutModelType": "MULTIPLE_SAME_COST"
"payoutCost": [1]
0: "7+8"
"terms": "Please accept this terms."
"specificSettings": [1]
{
"id": 413
"offerId": 472
"affiliateId": 0
"event": "ANY_EVENT"
"eventName": null
"cost": [1]
0: "9+10"
}
"currency": "EUR"
},
{
"id": 464
"name": "Offer9"
"description": "Description for offer9"
"status": "ACTIVE"
"categoryList": [1]
0: "druga"
"expirationDate": "29-03-2017 03:59:59"
"requireApproval": false
"previewUrl": "http://time.mk"
10(20) PUBLIC
API Description
"payoutType": "PER_SALE"
"payoutModelType": "MULTIPLE_CUSTOM_COST"
"payoutCost": [2]
0: "8"
1: "9"
"terms": "Terms and conditions"
"specificSettings": [0]
"currency": "USD"
},
{
"id": 360
"name": "Not1 offer"
"description": "Description Not1 offer"
"status": "ACTIVE"
"categoryList": [2]
0: "druga"
1: "Donauschiffartskapitän"
"expirationDate": "19-03-2018 14:33:49"
"requireApproval": true
"previewUrl": "http://google.com"
"payoutType": "PER_ACTION"
"payoutModelType": "ONE_TIME"
"payoutCost": [1]
0: "12"
"terms": "Terms for offer Not1"
"specificSettings": [1]
{
"id": 412
"offerId": 360
"affiliateId": 15018
"event": "ANY_EVENT"
"eventName": null
"cost": [1]
0: "78"
}
"currency": "EUR"
}]
http://your.gui.domain.com/v1affiliate/service/rest-affiliate/offer/creatives/2
[ { "creativeType" : "OFFERTHUMBNAIL",
"id" : 11,
"url" : "http://content.mcs-ftn.webslb.com/Affiliate/test/OffersView-
1398855733415.png"
} ]
11(20) PUBLIC
API Description
http://your.gui.domain.com/v1affiliate/service/rest-affiliate/getTargeting/1312
{
"countries": {
"Is one of these": [
"AL",
"AF",
"BA",
"BW",
"TJ",
"YE"
],
},
"regions": {
"Is one of these": [
"[AL] Kuçovë District",
"[AF] Zabul"
],
},
"connectionType": {
"Is": "Mobile"
},
"mobileOperators": {
"Is one of these": [
"Ht-eronet",
"M:tel",
"Bh Mobile"
],
},
"deviceType": {
"Is not": "Mobile"
},
"deviceOS": {
"Is one of these": [
"symbian os",
"android",
"windows phone os",
"ios"
],
},
"deviceOSVersion": {
"Is one of these": [
"symbian os 3",
"android 3.0.1",
"windows phone os 8",
"ios 10.0.2"
],
},
12(20) PUBLIC
API Description
"deviceBrand": {
"Is one of these": [
"3q"
],
},
"deviceModel": {
"Is not one of these": [
"Android 4 Tablet",
"Android 4.1"
],
},
"ipList": {
"Is one of these": [
"DS IP list 1 (7.6k)",
"DE - Berlin IP locations 2"
],
},
"customAffSubParameterTargeting": {
"aff_sub": "test"
}
}
http://your.gui.domain.com/v1affiliate/service/rest-affiliate/getCapping/1312
{
"generalCappingSettings": {
"clickCapping": "Enabled",
"clickLimit": "1999",
"clickLimitPeriod": "DAY",
"conversionCapping": "Disabled",
"conversionLimit": null,
"conversionLimitPeriod": null
},
"specificCappingSettings": [
{
"clickCapping": "Enabled",
"clickLimit": "777",
"clickLimitPeriod": "MONTH",
"conversionCapping": "Enabled",
"conversionLimit": "888",
"conversionLimitPeriod": "TOTALLY",
"affiliate": {
"15018": "Stipi Test j.d.o.o."
}
}
13(20) PUBLIC
API Description
]
}
http://your.gui.domain.com/v1affiliate/service/rest-affiliate/offer/generateTrackingLink
{ "offerIds" : [ 2,
125,
136
] }
[ "http://your.click.domain.com?aff_id=2&offer_id=2",
"http://your.click.domain.com?aff_id=2&offer_id=125",
"http://your.click.domain.com?aff_id=2&offer_id=136"
]
14(20) PUBLIC
API Description
http://your.gui.domain.com/v1affiliate/service/rest-
affiliate/statistics?resultsPerPage=2&page=1&dateFrom=2014-05-11&dateTo=2014-05-
30&offers={2}&dimensions={conversiontype,aff_sub,aff_sub1,aff_sub2,aff_sub3,aff_sub4,aff_s
ub5,country,devicebrand,devicemodel,deviceos,time_hour,creative}&measures={clicks,conversi
ons,impressions,earnings,conversionrates,ctr,epc}
[{
"clicks": "0",
"conversionRates": "N/A",
"conversions": "0",
"earnings": "0.00",
"ctr": "0.00%",
"affSub": "",
"affSub1": "",
"affSub2": "",
"affSub3": "",
"affSub4": "",
"affSub5": "",
"conversionType": "Unknown",
"country": "Croatia",
"deviceManufacturer": "Unknown",
"deviceModel": "Unknown",
"deviceOs": "Unknown",
"date": "06-03-2017 19:00",
"impressions": "5",
"creativeId": "2622",
"creativeName": "testpon3",
"epc": "N/A"
}{
"clicks": "0",
"conversionRates": "N/A",
"conversions": "0",
"earnings": "0.00",
"ctr": "0.00%",
"affSub": "",
"affSub1": "",
"affSub2": "",
"affSub3": "",
"affSub4": "",
"affSub5": "",
"conversionType": "Unknown",
"country": "Croatia",
"deviceManufacturer": "Unknown",
"deviceModel": "Unknown",
"deviceOs": "Unknown",
"date": "06-03-2017 21:00",
"impressions": "2",
"creativeId": "2622",
"creativeName": "testpon3",
"epc": "N/A"
}{
"clicks": "2",
"conversionRates": "0.00%",
"conversions": "0",
"earnings": "0.00",
"ctr": "N/A",
15(20) PUBLIC
API Description
"affSub": "",
"affSub1": "",
"affSub2": "",
"affSub3": "",
"affSub4": "",
"affSub5": "",
"conversionType": "Unknown",
"country": "Croatia",
"deviceManufacturer": "Unknown",
"deviceModel": "Unknown",
"deviceOs": "Unknown",
"date": "13-03-2017 15:00",
"impressions": "0",
"creativeId": "Unknown",
"creativeName": "",
"epc": "0.0000"
}]
http://your.gui.domain.com/v1affiliate/service/rest-affiliate/referrals
http://your.gui.domain.com/v1/service/rest/externalAccess/externalLogin
16(20) PUBLIC
API Description
{"username":"user","password":" ee11cbb19052e40b07aac0ca060c23ee"}
3.2 Resources
3.2.1 Affiliate resource
17(20) PUBLIC
API Description
value List of possible answers to the question (Only used for CHECKBOX, string
RADIO and SELECT question types). Format of the value should be
“value1”;”value2”;”value3”
required If an answer for the question must be provided boolean
18(20) PUBLIC
API Description
19(20) PUBLIC
API Description
3.2.13 UserLoginResource
20(20) PUBLIC