GET /2015-03-01/member/partnership

Advertiser API overview
Updated on
 
This method checks and resolves a given list of partner codes. 
 
The returned object contains either publisher, adspace and admedia details. I case that the authentication does not belong to a requested partner code the return value will be user ID and adspace ID only and without further details. For invalid partner codes an additional error list is returned. The amount of partner codes is limited to 25 items per request.
 
The example response below gives a full list of returned values.
 
We have also developed an example Java and PHP client, which you can use for your own development or test the features of the API from the command line.
 
If you only need user ID and adspace ID you can also use the public version of this API.
 
 
Getting started

In order to use this API, you will first need:

  1. Your zanox Connect ID
  2. Your zanox Secret Key
  3. One or more partnerCodes

The connect ID and secret key you can get in the section "Links and Tool" under "Web Services".

Once you have connect ID and secret key you can generate your signature for authentication as described in the Authentication section below.
 

Resource URL

https://advertiser.api.zanox.com/advertiser-api/2015-03-01/member/partnership

 

Parameters

 

Request
partnerCode
required

URL path parameter. A comma separated list of partner codes.

Value Type: String

max number of values: 25

 

Separator: comma (,)

 

Example Value:
23323443C69317236,24834593C69315636
connectId
required ( see authentication )

URL path parameter / Header variable

Value Type: String

Example Value:
04345C04A2341DB3CAC7
date
required ( see authentication )

URL path parameter / Header variable

Timestamp - In GMT in the format "EEE, dd MMM yyyy HH:mm:ss GMT"

Value Type: String

Example Value:

Thu%2C+03+Sep+2015+10%3A02%3A54+GMT

nonce
required ( see authentication )

URL path parameter / Header variable

A unique random string, generated at the time of request, valid once, 20 or more characters

Value Type: String

number of values: 20 or more characters

Example Value:

C0CC02AB4DA7D6BCFFB379B8BFABF924
signature
required ( see authentication )

URL path parameter / Header variable

Value Type: String

Example Value:
0TBobc13S9vrsnH32sfzEv8whEk%3D

 

Response
partnerCode

Requested partner code.

Value Type: String
userId

ID of the publisher

Value Type: Integer
adspaceId

ID of the publishers adspace

Value Type: Integer

partnerCodeStatus

optional

Status of the partner code.

Value Type: String

Possible values:

ACTIVE
INACTIVE
PROGRAM_DEACTIVATED_BY_USER
PROGRAM_PENDING
PROGRAM_DEACTIVATED_BY_ADMIN
DELETED

userName

optional

Account name of the user

Value Type: String

userStatus

optional

Status of the user

Value Type: String

Possible values:

ACTIVE
LOCKED
PREDELETED
DELETED

adspaceName

optional

 Value Type: String

adspaceUrl

optional

 Value Type: String

adspaceStatus

optional

Status of the adspace

Value Type: String

Possible values:

ACTIVE
INACTIVE
DELETED

admediaId

optional

ID of the admedia provided by the advertiser

Value Type: Integer

admediaName

optional

 

Value Type: String

admediaStatus

optional

Status of the admedium

Value Type: String

Possible values:

ACTIVE
DEACTIVATED
TESTING
DELETED

Fields marked as optional are only returned if the partnercode belongs to the program of the authenticated advertiser.

 

Authentication

API authentication implementation includes the connect ID, secured mhash key (signature) and the timestamp inside the HTTP header or as URL query parameters. The actual building of the signature is taken from the RFC2104 specification.

The signature is built by applying a keyed-HMAC (Hash Message Authentication Code) algorithm to the UTF-8 encoded StringToSign. The secret key has to be provided as a parameter to the keyed-HMAC method.

The signature will be valid for 30 miuntes and can be used just one time. Once you used a signature and nonce to optain data, you need to generate a new one.

Here is the simple explanation of how to generate a signature.

1
Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( StringToSign ) ) );

The StringToSign consists of a couple of elements that are concatenated:

1
HTTP-Verb + URI + timestamp + nonce

Where:

  • HTTP Verb - GET, POST, PUT or DELETE
  • URI - The path of specific request, excluding the protocol and domain name, together with path parameters.For example, for the URL 'https://advertiser.api.zanox.com/advertiser-api/2015-03-01/report/program/1803' the URI would be '/report/program/1803'.
  • Timestamp - In GMT in the format "EEE, dd MMM yyyy HH:mm:ss GMT"
  • Nonce - A unique random string, generated at the time of request, valid once, 20 or more characters

To successfully authenticate, connect ID, timestamp, nonce and signature have to be passed either as URL query parameters or as HTTP Headers. The query parameter names are connectid, date, nonce and signature respectively (line breaks added for clarity):

1
2
3
4
5
http://advertiser.api.zanox.com/advertiser-api/2015-03-01/member/partnership?partnerCode=32506328C1086151649T,23268341C1393895T,20569388C42814842T
&connectid=01234C04D1AA1ACD3AC5
&date=Thu%2C+03+Sep+2015+10%3A02%3A54+GMT
&nonce=C0CC02AB4DA7D6BCFFB379B8BFABF924
&signature=0TBobc13S9vrsnH32sfzEv8whEk%3D

As headers, the authentication values must be set in the following way:

1
2
3
Authorization: ZXWS connectid:signature
Date: timestamp
nonce: nonce

Example Request

REST authentication information in our example is added as query parameters

Get details for partner codes: 32506328C1086151649T, 23268341C1393895T, 20569388C42814842T

1
 http://advertiser.api.zanox.com/advertiser-api/2015-03-01/member/partnership?partnerCode=32506328C1086151649T,23268341C1393895T,20569388C42814842T&connectid=01234C04D1AA1ACD3AC5&date=Thu%2C+03+Sep+2015+10%3A02%3A54+GMT&nonce=C0CC02AB4DA7D6BCFFB379B8BFABF924&signature=0TBobc13S9vrsnH32sfzEv8whEk%3D

Please note that the displayed URL above is an example and will not work as it is because it is using an example signatue.

JSON Example Response

{
validPartnerCodes:
[
{
partnerCode: "32506328C1086151649T",
userId: 789988,
adspaceId: 784330
},
{
partnerCode: "23268341C1393895T",
userId: 1398869,
adspaceId: 1455395,
partnerCodeStatus: "ACTIVE",
userName: "TEST RND user 1",
userStatus: "ACTIVE",
adspaceName: "Test Adspace1 RnD U1",
adspaceUrl: "http://www.TestAdspace1RnDU1.de.vu",
adspaceStatus: "ACTIVE",
admediaId: 653292,
admediaName: "Productdata",
admediaStatus: "ACTIVE"
},
{
partnerCode: "20569388C42814842T",
userId: 1398869,
adspaceId: 1455395,
partnerCodeStatus: "ACTIVE",
userName: "TEST RND user 1",
userStatus: "ACTIVE",
adspaceName: "Test Adspace1 RnD U1",
adspaceUrl: "http://www.TestAdspace1RnDU1.de.vu",
adspaceStatus: "ACTIVE",
admediaId: 627708,
admediaName: "Homepage",
admediaStatus: "ACTIVE"
}
]
}
       

Java and php Advertiser Client

https://github.com/zanox/advertiser-api-client-java

https://github.com/zanox/advertiser-api-client-php

 

Resource Information

Rate Limited? No
Authentication

Requires signature.

See Authentication section.
Response Formats json
HTTP Methods GET
Resource family member
Response Object partnerCodeList
API Version 2015-03-01