# 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. (opens new window)
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
- 2022-11-23 - Updated throttle limit from 100 requests to 30.
- 2022-11-07 - Updated
/transaction/:transactionidto correct endpoint/transactions/:transactionidin documentation. - 2020-10-16 - Adds
/feeds/:channelid. Get feed urls to programs your channel has an approved relation to. - 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
/transactionsand/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 (opens new window).
# 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 30 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://st.adrecord.com/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://st.adrecord.com/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://st.adrecord.com/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 /feeds/:channelid
Get feed urls and details to program your channel has an approved relation to.
# Input parameters
| Parameter | Type | Description |
|---|---|---|
| *id | int | The id of the channel. |
# Result
[
{
"program": {
"id": 906,
"name": "Coolstuff",
"market": "SE"
},
"lastUpdated": "2020-10-16T05:09:25+02:00",
"items": 1886,
"feedUrls": {
"xml": "http:\/\/feed.adrecord.com\/coolstuff.xml?id=token",
"csv": "http:\/\/feed.adrecord.com\/coolstuff.csv?id=token",
"json": "http:\/\/feed.adrecord.com\/coolstuff.json?id=token"
}
}
]
# 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, global. |
| 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.
The field trackingUrl is empty if there is no valid relation to the program.
# 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, global. |
| 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!",
"trackingUrl": null,
"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!",
"trackingUrl": "https://click.adrecord.com/?c=TEST&p=70",
"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 /transactions/: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: 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. |
| 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
}