API post linkbuilder

From Wiki

Jump to: navigation, search

Contents

POST generate tracking link

Publishers are able to post a destination URL for an advertiser to generate an Awin tracking link. This endpoint allows you to either generate a single tracking link or batches of up to 100 tracking links.

Who can use it?

Publishers

Authentication

You need to provide a valid token. Please see our page about authentication and authorization API authentication and authorization for further details.

Generating a single tracking URL

Endpoint (POST)

https://api.awin.com/publishers/{publisherId}/linkbuilder/generate

JSON request Body

{
  "advertiserId": 1111,
  "destinationUrl": "https://www.awin.com",
  "parameters": {
    "campaign": "",
    "clickref": "",
    "clickref2": "",
    "clickref3": "",
    "clickref4": "",
    "clickref5": "",
    "clickref6": ""
  },
  "shorten": false
}


Field name Required? Type Description
advertiserId Yes Interger ID of the advertiser you are creating a link to
destinationUrl No String The specific page you wish to link to. If not provided, the advertiser’s default landing page is used.
parameters No Object This can contain any of the Awin click parameters.
shorten No Boolean If set to true, will response will return a shortened link URL along with the standard long link.


Response

If successful, a 200 response code is given, along with JSON of the following form:

{ 
  "url": "https://www.awin1.com/....", 
  "shortUrl": "https://tidd.ly/...." //if shorten true
}


If the response contains "description": "Unknown error! Please try again later!" for some single advertisers, they do not allow the link builder.

Generating a multiple tracking URLs

Endpoint (POST)

https://api.awin.com/publishers/{publisherId}/linkbuilder/generate-batch

A separate endpoint allows for multiple tracking links to be created with a single call (up to a maximum of 100 in the batch).

The body is a JSON object containing a single field: requests. This should be an array of requests in the same format described for the single request described above.

JSON request Body

{
  "requests": [
    {
      "advertiserId": 1111,
      "destinationUrl": "https://www.awin.com",
      "parameters": {
        "clickref": "foo"
      }
    },
    {
      "advertiserId": 2222,
      "destinationUrl": "https://www.example.com",
      "parameters": {
        "clickref": "foo"
      }
    }
  ]
}


Response

The response is a JSON object containing a single field “responses” which is an array of objects. Each of those objects contains 2 fields: status (indicating the HTTP status code which would have resulted from the corresponding request being sent singularly), and body. The body is as detailed for a single request above. Additionally, this contains a request field, containing the corresponding request payload, to aid in correlating the responses with the original requests.

{
  "responses": [
    {
      "status": 200,
      "body": {
        "url": "https://www.awin1.com/...",
        "request": {
          "publisherId": 12345,
          "advertiserId": 1111,
          "destinationUrl": "https://www.awin.com/",
          "parameters": {
            "clickref": "foo"
          }
        }
      }
    },
    {
      "status": 200,
      "body": {
        "url": "https://www.awin1.com/...",
        "request": {
          "publisherId": 12345,
          "advertiserId": 2222,
          "destinationUrl": "https://www.example.com/",
          "parameters": {
            "clickref": "foo"
          }
        }
      }
    }
  ]
}


If the response contains "status": 400, "destinationUrl": "deeplinkNotPermitted" for single advertisers, they do not allow the link builder.

It's currently not possible to generate short links via the batch generate endpoint

Retrieving short link quota

Endpoint (GET)

https://api.awin.com/publishers/{publisherId}/linkbuilder/quota

Response

{
  "shorten": {
    "publisherId": 1234,
    "limit": 100,
    "usage": 0
  }
}


Field name Type Description
publisherId String Awin publisher Id
limit String Max number of short links this publisher account can generate in 24hrs
usage Integer Number of short links current generated in last 24hrs

Privacy

Due to new European legislation regarding how websites store information about you, AWIN is updating its privacy policy. You can see the new version of our policy here. If you would like to see the information we capture on this website, please click here for further details. In order to accept cookies on this site please click the 'I ACCEPT' button