Affiliate API v2 Documentation

The API allow the affiliate to do common things like listing programs, create and modify channels, extract statistics reports, etc. In order to use the API, you must first logon to your account and generate a private API-key.

You can find a list of available commands below with an example of the output. All output is provided as JSON. If you have any questions regarding the API, feel free to contact api@adrecord.com.

Changelog

  • 2020-05-26 - Adds /user/payments. NOTE! Only for affiliate registered as a company.
  • 2019-09-12 - Adds info about transaction on /uts.
  • 2019-09-06 - Adds option the show relation status to a channel on /programs.
  • 2019-09-04 - Adds more info on changes to a transaction on /transactions.
  • 2019-07-10 - Adds feature to specify desired currency on /transactions and /statistics.
  • 2019-03-22 - Adds endpoint for statistics.
  • 2019-02-27 - Adds support for EPI on trackingUrls.
  • 2019-02-25 - Adds trackingUrl to /coupons.
  • 2019-01-01 - Init.

Introduction

The API-key can be sent as both a GET or POST variable, as well as a HTTP-header named APIKEY, like this:

GET /channels HTTP/1.1
Host: api.v2.adrecord.com
Apikey: <your secret API-key>

HTTP/1.1 200 Found
...

Base URL

The base url for all API endpoints is https://api.v2.adrecord.com

Notes

  • Encoding: Strings passed to the API should be UTF-8 encoded.
  • Date format: All dates are in ISO 8601.

Headers

  • apikey: string to authenticate.

Inputs

The API only supports JSON. So instead of XML, HTTP POST parameters, or other serialization formats, POST and PATCH requests require a valid JSON object for the body.

Errors

Code Description
200 OK Successful request.
400 Bad request The server cannot process the request due to an apparent client error.
401 Unauthorized The request requires authentication.
404 Not Found The requested resource could not be found.
409 Conflict The request could not be processed because of conflict in the current state of the resource.
429 Too Many Requests You have sent too many requests in a given amount of time.
500 Internal Server Error Unexpected behavior on the server level.

Example message for 409:

{
    "status": "error",
    "message": "Wrong status format. Set status to either \"rejected\" or \"approved\"."
}

If you’re seeing a 5xx error, that likely means there’s an error on Adrecord’s side, and you can contact our support team at api@adrecord.com.

Throttling

To improve connections and experiences for all our users, we use some connection limits to avoid overload. Each user is permitted up to 100 request per 30 seconds, and you’ll receive an error message if you reach the limit. The reached limit will be reset after 5 minutes.

Resources

GET /user

View the details of your user.

Result

{
    "userID": 1,
    "firstName": "Michael",
    "lastName": "Scofield",
    "address": "Fox River State Penitentiary",
    "zipcode": "123 45",
    "city": "Fox River",
    "country": "USA",
    "phone": null,
    "email": "michael@example.com",
    "type": "personal",
    "language": "swedish",
    "currency": "SEK"
}

GET /user/payments

View payments for your user. Please note that this endpoint only work for affiliates registerad as a company, at the moment.

The PDF-url will need your apikey to authenticate.

Result

[
    {
        "id": "ADR12345",
        "date": "2020-04-15T08:45:58+02:00",
        "status": "sent",
        "transactions": 39,
        "total": 13170.63,
        "commission": 10536.50,
        "vat": 2634.13,
        "currency": "SEK",
        "pdfUrl": "https://api.v2.adrecord.com/user/payments/123456"
    },
    {
        "id": "ADR12346",
        "date": "2020-03-15T08:45:58+02:00",
        "status": "revoked",
        "transactions": 0,
        "total": 0,
        "commission": 0,
        "vat": 0,
        "currency": null,
        "pdfUrl": null
    }
]

GET /channels

List all channels that is associated with your account.

Result

[
    {
        "channelID": 1,
        "name": "My personal blog",
        "description": "Example of what my blog is about",
        "status": "Approved",
        "type": "Blog",
        "segment": null
        "url": "http:\/\/blog.example.com",
    },
    {
        "channelID": 2,
        "name": "Price comparison",
        "description": "Example of what my comparison website is about",
        "status": "Pending",
        "type": "Web",
        "segment": "comparison"
        "url": "http:\/\/compare.example.com",
    },
    {
        "channelID": 3,
        "name": "Example homepage",
        "description": "Example of what my site is about",
        "status": "Approved",
        "type": "web",
        "segment": null
        "url": "http:\/\/www.example.com",
    }
]

GET /channels/:channelid

View the details of a specific channel.

Input parameters

Parameter Type Description
id int The id of the channel.

Result

{
    "channelID": 1,
    "name": "My personal blog",
    "description": "Example of what my blog is about",
    "status": "Approved",
    "type": "Blog",
    "segment": null,
    "url": "http:\/\/blog.example.com",
    "programs": [
        {
            "programID": 198,
            "programName": "Partykungen"
        },
        {
            "programID": 836,
            "programName": "Avanza"
        }
    ]
}

GET /programs

List all the available programs.

Filters

Parameter Type Description
limit int Limit the result.
category int A comma-separated list of category id-numbers.
market string A comma-separated list of countries: global, se, no, dk, fi.
sortDate string Sort the result by start date, asc or desc

Options

Parameter Type Description
relation int Provide the id for one of your channels to get an extra field showing the relation status: null, approved, pending or rejected.

Result

[
    {
        "id": 198,
        "name": "Partykungen",
        "url": "https:\/\/www.partykungen.se",
        "shortDescription": "Maskeradkläder, partyprylar och roliga presenter.",
        "market": "SE",
        "currency": "SEK",
        "date": "2012-02-15",
        "categories": [
            {
                "id": 15,
                "name": "Gifts & experiences",
            }
        ],
        "logo": "https://www.adrecord.com/img/logos/198.gif",
        "relation": "approved"
    },
    {
        "id": 836,
        "name": "Avanza",
        "url": "https:\/\/www.avanza.se",
        "shortDescription": "Digital plattform för sparande och investeringar.",
        "market": "SE",
        "currency": "SEK",
        "date": "2018-01-01",
        "categories": [
            {
                "id": 5,
                "name": "Economy",
            }
        ],
        "logo": "https://www.adrecord.com/img/logos/836.gif"
    }
]

GET /programs/:programid

View the details of a specific program.

Input parameters

Parameter Type Description
id int The id of the program.

Result

{
    "id": 198,
    "name": "Partykungen.se",
    "url": "https:\/\/www.partykungen.se",
    "description": "Hos Partykungen hittar du maskeradkl\u00e4der, partyprylar och roliga presenter. Vi har ett brett sortiment inom flera olika kategorier vilket g\u00f6r att det finns n\u00e5gonting f\u00f6r alla.\n\nV\u00e5ra kunder befinner sig framf\u00f6rallt i Sverige men vi s\u00e4ljer \u00e4ven till Danmark och Finland. Genomsnittskunden \u00e4r en man mellan 18 och 25 \u00e5r och bor i en storstad. Med det sagt har vi m\u00e5nga kunder i alla \u00e5ldrar och b\u00e5da k\u00f6n.\n\nVi har m\u00e5nga roliga, annorlunda och unika produkter som l\u00e4mpar sig v\u00e4ldigt bra att l\u00e4nka till eller skriva om p\u00e5 sin blogg. M\u00e5nga av v\u00e5ra bes\u00f6kare stannar kvar i shoppen l\u00e4nge och vi har m\u00e5nga \u00e5terkommande kunder.\n\nV\u00e4lkommen som publicist hos Partykungen!\n\nE-postmarknadsf\u00f6ring\nAffiliates med nyhetsbrev f\u00e5r g\u00e4rna kontakta support@adrecord.com f\u00f6r godk\u00e4nnande att marknadsf\u00f6ra Partykungen.se i nyhetsbrevsutskick.",
    "trackingTime": "45 days",
    "logo": "https://www.adrecord.com/img/logos/198.gif",
    "terms": {
        "cashback": false,
        "mail": false,
        "affiliate": true,
        "coupon": false,
        "social": false,
        "paid": [
            {
                "name": "Google Adwords",
                "allow": true,
                "description": null
            },
            {
                "name": "Bing",
                "allow": true,
                "description": null
            },
            {
                "name": "Yahoo!",
                "allow": true,
                "description": null
            },
            {
                "name": "Facebook Ads",
                "allow": true,
                "description": null
            },
            {
                "name": "Twitter Ads",
                "allow": true,
                "description": null
            },
            {
                "name": "Youtube Ads",
                "allow": true,
                "description": null
            },
            {
                "name": "Direct linking",
                "allow": false,
                "description": "It's not allowed to send traffic directly to the advertiser."
            },
            {
                "name": "Brand name as keywords",
                "allow": false,
                "description": "It's not allowed to buy keywords of the brand name or variants of it to drive traffic to the advertiser. Branding-words should also be added as negative keywords."
            },
            {
                "name": "Brand name in ad text",
                "allow": false,
                "description": "It's not allowed to have the brand name in the heading or in the text of the ad."
            },
            {
                "name": "Brand name in display URL",
                "allow": false,
                "description": "It's not allowed to have the brand name in the display URL for the ad."
            }
        ]
    },
    "categories": [
        "Gifts & experiences"
    ],
    "commissions": [
        {
            "name": "Order 15",
            "type": "sale",
            "commission": "15%",
            "range": null,
            "segment": null,
            "startDate": null,
            "stopDate": null
        },
        {
            "name": "iSale 6",
            "type": "isale",
            "commission": "6%",
            "range": null,
            "segment": null,
            "startDate": null,
            "stopDate": null
        }
    ]
}

GET /relations

List all your relations.

Parameters

Parameter Type Description
epi string Adds EPI-value to the trackingUrl.

Filters

Parameter Type Description
limit int Limit the result.
status string pending, approved or rejected.
channel int A comma-separated list of channel id-numbers.
market string A comma-separated list of programs countries: global, se, no, dk, fi.

Result

[
    {
        "channel": {
            "id": 1,
            "name": "My personal blog"
        },
        "program": {
            "id": 198,
            "name": "Partykungen",
            "market": "SE",
            "currency": "SEK",
            "commissions": "10%"
        },
        "trackingUrl": "https://click.adrecord.com/?c=TEST&p=198",
        "status": "approved"
    },
    {
        "channel": {
            "id": 1,
            "name": "My personal blog"
        },
        "program": {
            "id": 836,
            "name": "Avanza",
            "market": "SE",
            "currency": "SEK",
            "commissions": "120 SEK"
        },
        "trackingUrl": null,
        "status": "rejected",
        "date": "2018-10-20T01:13:34+02:00",
        "comment": "We have a strict policy to approve channels with a clear focus on finance and investing.",
    }
]

GET /campaigns

List all active and future campaigns. If a channelID is provided you will get the full affiliate tracking link.

Parameters

Parameter Type Description
channel int Channel id-number, to get trackingUrl.
epi string Adds EPI-value to the trackingUrl.

Filters

Parameter Type Description
limit int Limit the result.
program int A comma-separated list of program id-numbers.
market string A comma-separated list of markets: se, no, dk, fi.
sort string Sort the result by date, asc or desc
from string ISO 8601 date, urlencoded
to string ISO 8601 date, urlencoded

Result

[
    {
        "id": 752749,
        "program": {
            "id": 198,
            "name": "Partykungen",
            "market": "SE",
        },
        "title": "Rabatt hos Partykungen!",
        "description": "20% rabatt på hela sortimentet!",
        "affiliateDescription": null,
        "url": "https:\/\/www.partykungen.se",
        "trackingUrl": null,
        "start": "2018-12-24T15:00:00+02:00",
        "stop": "2019-12-24T23:59:59+02:00",
        "categories": [
            {
                "id": 9,
                "name": "Christmas"
            }
        ],
    },
    {
        "id": 752750,
        "program": {
            "id": 933,
            "name": "ELON",
            "market": "SE"
        },
        "title": "Kom i julstämning med ELON!",
        "description": "Dags att klä trädgården och uteplatsen eller balkongen med stämningsfull säsongsbelysning. Härliga ljusslingor (finns nu även app-styrda sådana så att du slipper gå ut för att tända favoritjusslingan) i olika färg, form och prisklass hittar du i våra butiker med belysning i sortimentet - eller här på vår hemsida.",
        "affiliateDescription": null,
        "url": "https:\/\/www.elon.se\/kampanjer\/julbelysning-hos-elon-3",
        "trackingUrl": "https:\/\/click.adrecord.com\/?c=TEST&p=933&url=https%3A%2F%5Cwww.elon.se%2Fkampanjer%2Fjulbelysning-hos-elon-3",
        "start": "2018-11-06T15:00:00+02:00",
        "stop": "2019-12-23T23:59:59+02:00",
        "categories": [
            {
                "id": 9,
                "name": "Christmas"
            }
        ],
    }
]

GET /coupons

List all active and future coupon codes. All expired coupon codes will be excluded. For individual/custom coupon codes the coupon also holds the channel object.

Parameters

Parameter Type Description
channel int Channel id-number, to get trackingUrl.
epi string Adds EPI-value to the trackingUrl.

Filters

Parameter Type Description
limit int Limit the result.
program int A comma-separated list of program id-numbers.
market string A comma-separated list of markets: se, no, dk, fi.
sort string Sort the result by date, asc or desc
from string ISO 8601 date, urlencoded
to string ISO 8601 date, urlencoded

Result

[
    {
        "id": 752749,
        "program": {
            "id": 198,
            "name": "Partykungen",
            "market": "SE"
        },
        "code": "GODJUL20",
        "description": "20% rabatt på hela sortimentet!",
        "start": "2018-12-24T15:00:00+02:00",
        "stop": "2019-12-24T23:59:59+02:00"
    },
    {
        "id": 752750,
        "program": {
            "id": 70,
            "name": "Upplevelse.com",
            "market": "SE"
        },
        "channel": {
            "id": 1,
            "name": "My personal blog"
        },
        "code": "mellan15",
        "description": "Mellandagsrea hos Upplevelse.com! Få 15% rabatt på allt!",
        "start": "2018-12-25T15:00:00+02:00",
        "stop": "2019-12-31T23:59:59+02:00"
    }
]

GET /transactions

List your latest transactions. By default the limit is set to 10, and the result is sorted by descending date. Manual transactions is added extra money to your account, for example bonuses or prize money in affiliate competitions. They will also come with a comment.

Filters

Parameter Type Description
limit int Limit the result from 1-100.
status string A comma-separated list of statuses: rejected, pending, approved, invoiced, paid-invoice, paid-affiliate.
channel int A comma-separated list of channel id-numbers.
program int A comma-separated list of program id-numbers.
sort string Sort the result by date, asc or desc
from string ISO 8601 date, urlencoded
to string ISO 8601 date, urlencoded
cursor int next transactionID, used for pagination.
currency string Specify which currency you want to get all the transactions in. Available currencies are: SEK, EUR, NOK, DKK, USD and GBP. Please note that the conversion is done on todays exchange rate.

Example

GET /transactions?from=2018-10-20T00%3A00%3A00%2B01%3A00&to=2018-12-31T23%3A59%3A59%2B0%3A00&limit=500&apikey={your API key}

Result

{
    "current": 752749,
    "next": 344733,
    "data": [
        {
            "id": 752749,
            "date": "2018-10-21T01:09:45+02:00",
            "status": "Approved",
            "orderValue": 100,
            "commissionName": "Order 10",
            "commission": 10,
            "currency": "SEK",
            "platform": "mac",
            "orderComment": null,
            "channel": {
                "id": 1,
                "name": "My personal blog"
            },
            "program": {
                "id": 198,
                "name": "Partykungen"
            },
            "click": {
                "date": "2018-10-20T01:09:45+02:00",
                "epi": [
                    "topbanner"
                ],
                "referrer": "https\/\/www.example.com\/party.html",
                "adwords": null
            },
            "changes": [
                {
                    "type": "Changed status",
                    "date": "2018-10-20T01:13:34+02:00",
                    "from": "Pending",
                    "to": "Approved"
                }
            ]
        },
        {
            "id": 744879,
            "date": "2018-11-17T01:09:45+02:00",
            "status": "Paid",
            "orderValue": 321,
            "commissionName": "Order 10",
            "commission": 32.1,
            "currency": "SEK",
            "platform": "mac",
            "orderComment": null,
            "channel": {
                "id": 1,
                "name": "My personal blog"
            },
            "program": {
                "id": 198,
                "name": "Partykungen"
            },
            "click": {
                "date": "2018-11-16T01:09:45+02:00",
                "epi": [
                    "topbanner"
                ],
                "referrer": "https\/\/www.example.com\/party.html",
                "adwords": null
            },
            "changes": [
                {
                    "type": "Changed status",
                    "date": "2018-10-20T01:13:34+02:00",
                    "from": "Pending",
                    "to": "Approved"
                }
            ]
        },
        {
            "id": 344732,
            "date": "2018-12-02T11:09:45+02:00",
            "status": "Rejected",
            "orderValue": 321,
            "commissionName": "Order 10",
            "commission": 32.1,
            "currency": "SEK",
            "platform": "mac",
            "orderComment": "return by customer.",
            "channel": {
                "id": 1,
                "name": "My personal blog"
            },
            "program": {
                "id": 198,
                "name": "Partykungen"
            },
            "click": {
                "date": "2018-12-01T11:09:45+02:00",
                "epi": null,
                "referrer": "https\/\/www.example.com\/party.html",
                "adwords": null
            },
            "changes": [
                {
                    "type": "Changed status",
                    "date": "2018-12-04T11:13:04+02:00",
                    "from": "Pending",
                    "to": "Rejected"
                }
            ]
        }
    ]
}

GET /transaction/:transactionid

View the details of a specific transaction.

Input parameters

Parameter Type Description
id int The id of the transaction.

Result

{
    "id": 752749,
    "date": "2018-10-21T01:09:45+02:00",
    "status": "Approved",
    "orderValue": 100,
    "commissionName": "Order 10",
    "commission": 10,
    "currency": "SEK",
    "platform": "mac",
    "orderComment": null,
    "channel": {
        "id": 1,
        "name": "My personal blog"
    },
    "program": {
        "id": 198,
        "name": "Partykungen"
    },
    "click": {
        "date": "2018-10-20T01:09:45+02:00",
        "epi": [
            "topbanner"
        ],
        "referrer": "https\/\/www.example.com\/party.html",
        "adwords": null
    },
    "changes": [
        {
            "type": "Changed status",
            "date": "2018-10-20T01:13:34+02:00",
            "from": "Pending",
            "to": "Approved"
        }
    ]
}

GET /statistics

List the statistics similar to the channel reports in our control panel. Note that all statistics with zero values are omitted.

Default date interval is latest 30 days.

Filters

Parameter Type Description
status string A comma-separated list of transaction statuses: pending, approved, rejected.
channel int A comma-separated list of channel id-numbers.
program int A comma-separated list of program id-numbers.
group string Group the result by channel, program, month or day
from string ISO 8601 date, urlencoded
to string ISO 8601 date, urlencoded
currency string Specify which currency you want to get all the transactions in. Available currencies are: SEK, EUR, NOK, DKK, USD and GBP. Please note that the conversion is done on todays exchange rate.

Result

{
    "channel": {
        "id": 1,
        "name": "My personal blog"
    },
    "program": {
        "id": 198,
        "name": "Partykungen"
    },
    "impressions": {
        "total": 292,
        "unique": 12
    },
    "clicks": {
        "total": 227,
        "unique": 191
    },
    "transactions": {
        "count": 7,
        "orderValue": 8846.40,
        "commission": 702.13
    },
    "cr": 3,
    "ctr": 78,
    "aov": 1263.77,
    "epc": 3.09,
    "ecpm": 2404.55
}
...

GET /uts

List your latest Untracked Sales. The result is sorted by descending date as default.

Filters

Parameter Type Description
limit int Limit the result.
status string Pending, Approved or Rejected.
channel int A comma-separated list of channel id-numbers.
program int A comma-separated list of program id-numbers.
sort string Sort the result by date created, asc or desc
from string ISO 8601 date, urlencoded
to string ISO 8601 date, urlencoded

Result

 [
    {
        "id": 752749,
        "channel": {
            "id": 1,
            "name": "My personal blog"
        },
        "program": {
            "id": 198,
            "name": "Partykungen"
        },
        "orderID": "#100A2",
        "orderValue": 100,
        "expectedCommission": 10,
        "commission": 10,
        "currency": "SEK",
        "ip": "2870925",
        "reported": "2018-11-02T01:09:45+02:00",
        "click": "2018-10-20T01:09:45+02:00",
        "sale": "2018-10-20T01:11:05+02:00",
        "epi": "abc1234",
        "status": "Approved",
        "comment": null,
        "transaction": null,
        "adrecordComment": "Problem med spårning p.g.a. tillfälligt fel."
    },
    {
        "id": 752744,
        "channel": {
            "id": 1,
            "name": "My personal blog"
        },
        "program": {
            "id": 120,
            "name": "Adrecord"
        },
        "orderID": "#100A5464564",
        "orderValue": 100,
        "expectedCommission": 10,
        "commission": null,
        "currency": null,
        "ip": "2870915",
        "reported": "2018-11-02T01:09:45+02:00",
        "click": "2018-10-20T01:09:45+02:00",
        "sale": "2018-10-20T01:11:05+02:00",
        "epi": null,
        "status": "Pending",
        "comment": null,
        "transaction": null,
        "adrecordComment": null
    },
    {
        "id": 752745,
        "channel": {
            "id": 1,
            "name": "My personal blog"
        },
        "program": {
            "id": 120,
            "name": "Adrecord"
        },
        "orderID": "#100A54FGDA6",
        "orderValue": 250,
        "expectedCommission": 17,
        "commission": null,
        "currency": null,
        "ip": "28709843",
        "reported": "2018-12-31T01:09:45+02:00",
        "click": "2018-12-24T01:09:45+02:00",
        "sale": "2018-21-25T01:11:05+02:00",
        "epi": null,
        "status": "Rejected",
        "comment": null,
        "transaction": null,
        "adrecordComment": "Sale registered with another affiliate"
    }
]

POST /uts

Add a new UTS.

Input parameters

Parameter Type Description
*channel int The channelID.
*program int The programID.
*orderID string The orderID reported from the customer.
*orderValue number The total amount of the purchase excluding VAT.
*expectedCommission number The expected commission value.
*ip string The ip-number for the customer.
*click string ISO 8601 date, urlencoded
*sale string ISO 8601 date, urlencoded
epi string Your EPI.
comment string Additional information you would like to provide.

* = required inputs.

Example input

{
	"channel": 1,
	"program": 198,
	"orderID": "123test",
	"orderValue": 100,
	"expectedCommission": 10,
	"ip": "127.0.0.1",
    "click": "2018-10-20T01:09:45+02:00",
    "sale": "2018-10-20T01:11:05+02:00",
    "epi": "user12"
}

Result

Will return the newly added UTS object.

{
    "id": 752749,
    "channel": {
        "id": 1,
        "name": "My personal blog"
    },
    "program": {
        "id": 198,
        "name": "Partykungen"
    },
    "orderID": "123test",
    "orderValue": 100,
    "expectedCommission": 10,
    "commission": null,
    "currency": null,
    "ip": "2870925",
    "reported": "2018-11-02T01:09:45+02:00",
    "click": "2018-10-20T01:09:45+02:00",
    "sale": "2018-10-20T01:11:05+02:00",
    "epi": "user12",
    "status": "pending",
    "comment": null,
    "adrecordComment": null
}