Skip to content

Instantly share code, notes, and snippets.

@igastepniak
Last active August 15, 2016 13:46
Show Gist options
  • Save igastepniak/eb4570537c1eb819fee37e8fdb8b82b0 to your computer and use it in GitHub Desktop.
Save igastepniak/eb4570537c1eb819fee37e8fdb8b82b0 to your computer and use it in GitHub Desktop.

#Publisher API Documentation#

Table of Content:


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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment