If you have any question left, please drop a note with the discussion link of this page.
REST V2011-03-01 Incentives
From Wiki.zanox.com
The Incentives RESTful API resource offers Incentivised Offers of advertiser programmes. Primary use case is to download currently running and scheduled offers.
Contents |
How does the incentives resource work?
There are two types of incentives: exclusive and non-exclusive.
Non-exclusive incentives are visible to all zanox publishers, whether or not they have applied to the program offering the incentive. If you do a simple "get all" (i.e. http://api.zanox.com/xml/2011-03-01/incentives?connectid=580599047DF8F5311043), tracking links will be returned as follows:
- if the incentive is for a program you belong to, you get a tracking link for the ad space(s) you used to apply;
- some zanox programs participate in a public ad media pool; if the incentive is in one of these programs, you get a tracking link for each of your ad spaces; and
- if you are not applied to the program and the program does not participate in the ad media pool, you get the incentive without a tracking link.
If you restrict your query to a specific ad space (i.e. http://api.zanox.com/xml/2011-03-01/incentives?&adspace=...&connectid=580599047DF8F5311043), you will only see incentives for the programs you have applied to, and for those participating in the public ad media pool.
Exclusive incentives are a completely different set of incentives, and are only visible to publishers who have been explicitly granted permission to use an incentive by its program. If you are interested in using exclusive incentives, please contact your Account Manager.
GET: Retrieving single Incentive item
Returns a single non-exclusive incentive item.
Parameters
| Name | Necessity | Parameter type | Description |
|---|---|---|---|
| connectid | mandatory | header parameter or query parameter | connectID is required to get your tracking links into the result. |
| incentiveId | mandatory | path parameter | Id of Incentive item. |
| adspace | optional | query parameter | constrain the returned tracking links to a specified adspace |
| callback | optional | query parameter | Supported if format is JSON. Name of the JS function the result is wrapped in. |
Example Request
// REST XML http://api.zanox.com/xml/2011-03-01/incentives/incentive/333?connectid=580599047DF8F5311043 // REST JSON http://api.zanox.com/json/2011-03-01/incentives/incentive/333?connectid=580599047DF8F5311043
// REST JSONP http://api.zanox.com/json/2011-03-01/incentives/incentive/333?connectid=580599047DF8F5311043&callback=handleResponse
Example Response
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <response xmlns="http://api.zanox.com/namespace/2011-03-01/"> <incentiveItem id="333"> <name>TOP Gutscheine</name> <program id="5501">Betten Rid DE</program> <admedia> <admediumItem id="490278"> <name>Logo 124x40</name> <adrank>0.0</adrank> <admediumType>image</admediumType> <program id="5501">Betten Rid DE</program> <title>www.bettenrid.de</title> <height>40</height> <width>124</width> <category id="47929">Logos</category> <trackingLinks> <trackingLink adspaceId="1330998"> <ppv>http://ad.zanox.com/ppv/?123c456</ppv> <ppc>http://ad.zanox.com/ppc/?123c456</ppc> </trackingLink> </trackingLinks> </admediumItem> </admedia> <incentiveType>coupons</incentiveType> <regions> <region>DE</region> </regions> <createDate>2010-12-02T14:48:49.023+01:00</createDate> <modifiedDate>2010-12-07T15:58:20.463+01:00</modifiedDate> <startDate>2010-12-07T00:00:00+01:00</startDate> <endDate>2010-12-30T23:59:59+01:00</endDate> <info4publisher>Im Dezember bietet Betten Rid seinen Partnern attraktive Staffelrabatte an: 10 Euro ab 100 Euro = Code 50752 Diese Aktionen können mit der versandkostenfreien Lieferung ab einem Bestellwert von 20 € kombiniert werden!</info4publisher> <info4customer>Staffelrabatte bei Betten Rid! Bis zu 15 € Rabatt! Versandkostenfreie Lieferung ab 20</info4customer> <couponCode>50752</couponCode> <total>10.0</total> <currency>EUR</currency> <restrictions /> <newCustomerOnly>false</newCustomerOnly> <minimumBasketValue>100.0</minimumBasketValue> <prizes /> </incentiveItem> </response>
GET: Retrieving single Exclusive Incentive item
Returns a single exclusive incentive item.
Parameters
| Name | Necessity | Parameter type | Description |
|---|---|---|---|
| connectid | mandatory | header parameter or query parameter | connectID is required to get your tracking links into the result. |
| timestamp | mandatory | header or query parameter | timestamp is required for authorization to eliminate any possibility of data abuse. |
| nonce | mandatory | header or query parameter | nonce is required for authorization to eliminate any possibility of data abuse. |
| signature | mandatory | header or query parameter | signature is required for authorization to eliminate any possibility of data abuse. |
| incentiveId | mandatory | path parameter | Id of Incentive item. |
| adspace | optional | query parameter | constrain the returned tracking links to a specified adspace |
| callback | optional | query parameter | Supported if format is JSON. Name of the JS function the result is wrapped in. |
Example Request
// REST XML http://api.zanox.com/xml/2011-03-01/incentives/exclusive/incentive/333?connectid=580599047DF8F5311043&date=Mon, 09 Sep 2010 08:17:35 GMT&signature=FN+JGAMxDShoyh3sfayql6jWCRc=&nonce=12345678912345678911
// REST JSON http://api.zanox.com/json/2011-03-01/incentives/exclusive/incentive/333?connectid=580599047DF8F5311043&date=Mon, 09 Sep 2010 08:17:35 GMT&signature=FN+JGAMxDShoyh3sfayql6jWCRc=&nonce=12345678912345678911
GET: Retrieve filtered list of Incentives items
Returns a list of non-exclusive incentive items. Filter Incentives by region, advertiser programme, The result is limited to the top 1000 results sorted by the date of last modification. Paging is not supported right now.
Parameters
| Name | Necessity | Parameter type | Description |
|---|---|---|---|
| connectid | mandatory | header parameter or query parameter | connectID is required to get your tracking links in the result. |
| incentiveType | optional | query parameter | Specifies the type of Incentive. Use "coupons", "bargains", "freeProducts", "samples", "noShippingCosts", "lotteries" |
| region | optional | query parameter | Filter by a specified sales region of the advertiser programme (country). ISO 3166 a2 codes, e.g. "de", "gb", "fr", "es", "nl", "at", "ch". |
| program | optional | query parameter | Filters by given advertiser programme |
| adspace | optional | query parameter | constrain the returned tracking links to a specified adspace |
| items | optional | query parameter | not implemented |
| page | optional | query parameter | not implemented |
| callback | optional | query parameter | Supported if format is JSON. Name of the JS function the result is wrapped in. |
Example Request
// REST XML http://api.zanox.com/xml/2011-03-01/incentives?region=de&connectid=580599047DF8F5311043 // REST JSON http://api.zanox.com/json/2011-03-01/incentives?region=de&connectid=580599047DF8F5311043 // REST JSONP http://api.zanox.com/json/2011-03-01/incentives?region=de&connectid=580599047DF8F5311043&callback=handleProducts
Example Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response xmlns="http://api.zanox.com/namespace/2011-03-01/"> <page>0</page> <items>5</items> <total>5</total> <incentiveItems> <incentiveItem id="123">...</incentiveItem> <incentiveItem id="12312">...</incentiveItem> <incentiveItem id="324">...</incentiveItem> <incentiveItem id="245">...</incentiveItem> <incentiveItem id="234">...</incentiveItem> </incentiveItems> </response>
GET: Retrieve filtered list of ExclusiveIncentives items
Returns a list of exclusive incentives. Filter Incentives by region, advertiser programme. The result is limited to the top 1000 results sorted by the date of last modification. Paging is not supported right now.
Parameters
| Name | Necessity | Parameter type | Description |
|---|---|---|---|
| connectid | mandatory | header parameter or query parameter | connectID is required to get your tracking links in the result. |
| timestamp | mandatory | header or query parameter | timestamp is required for authorization to eliminate any possibility of data abuse. |
| nonce | mandatory | header or query parameter | nonce is required for authorization to eliminate any possibility of data abuse. |
| signature | mandatory | header or query parameter | signature is required for authorization to eliminate any possibility of data abuse. |
| incentiveType | optional | query parameter | Specifies the type of Incentive. Use "coupons", "bargains", "freeProducts", "samples", "noShippingCosts", "lotteries" |
| region | optional | query parameter | Filter by a specified sales region of the advertiser programme (country). ISO 3166 a2 codes, e.g. "de", "gb", "fr", "es", "nl", "at", "ch". |
| program | optional | query parameter | Filters by given advertiser programme |
| adspace | optional | query parameter | constrain the returned tracking links to a specified adspace |
| items | optional | query parameter | not implemented |
| page | optional | query parameter | not implemented |
| callback | optional | query parameter | Supported if format is JSON. Name of the JS function the result is wrapped in. |
Example Request
// REST XML http://api.zanox.com/xml/2011-03-01/incentives/exclusive?region=de&connectid=580599047DF8F5311043&date=Mon, 09 Sep 2010 08:17:35 GMT&signature=FN+JGAMxDShoyh3sfayql6jWCRc=&nonce=12345678912345678911 // REST JSON http://api.zanox.com/json/2011-03-01/incentives/exclusive?region=de&connectid=580599047DF8F5311043&date=Mon, 09 Sep 2010 08:17:35 GMT&signature=FN+JGAMxDShoyh3sfayql6jWCRc=&nonce=12345678912345678911
Example Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response xmlns="http://api.zanox.com/namespace/2011-03-01/"> <page>0</page> <items>5</items> <total>5</total> <incentiveItems> <incentiveItem id="123">...</incentiveItem> <incentiveItem id="12312">...</incentiveItem> <incentiveItem id="324">...</incentiveItem> <incentiveItem id="245">...</incentiveItem> <incentiveItem id="234">...</incentiveItem> </incentiveItems> </response>