# Advertiser API Documentation
The API allow the advertiser to do common things like list and handle transactions. 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 resources 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-05 - New parameter for pagination on the endpoint
/v1/transactions, which also makes the parametercursordepricated. - 2019-04-02 - New endpoint to get statistics.
- 2019-03-28 - New endpoints to get account and program information.
- 2018-10-08 - Adds filter for tags in transactions endpoint.
- 2018-10-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 /v1/transactions HTTP/1.1
Host: apiadv.adrecord.com
Apikey: <your secret API-key>
HTTP/1.1 200 Found
...
# Base URL
The base url for all API endpoints is https://apiadv.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 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 /v1/account
See all your account information and settings in your Adrecord account.
# Result
{
"id": 19,
"name": "TestAdvertiser",
"email": "example@example.com",
"contact": {
"general": {
"company": "TestAdvertiser AB",
"companyNumber": "123456-7890",
"vatNumber": "SE123456789001",
"address": "Test street 1",
"zipCode": "12345",
"city": "Orebro",
"country": "Sweden"
},
"invoice": {
"email": "invoice@example.com,economy@example.com",
"reference": null,
"address": null
}
},
"applications": {
"autoAllow": false,
"email": "affiliate_applications@example.com"
},
"transactionAudit": {
"email": "economy@exaple.com",
"sendOnDay": 1,
"autoApproveDays": 10
},
"tracking": {
"baseUrl": "https:\/\/example.com",
"trackingUrl": "https:\/\/example.com/adrecord.html",
"trackingTime": "45 days",
"defaultCurrency": "SEK"
},
"productFeed": {
"active": true,
"url": "https:\/\/example.com/products.csv",
"totalProducts": 13484,
"lastCheck": "2019-01-20T00:00:00+02:00",
"lastUpdate": "2019-01-18T00:00:00+02:00"
}
}
# GET /v1/programinfo
See all your program information and settings in your Adrecord account.
# Result
{
"id": 19,
"name": "TestAdvertiser",
"description": "Hos TestAdvertiser hittar du prylar 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 TestAdvertiser!",
"terms": {
"cashback": false,
"mail": false,
"affiliatePurchase": 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."
}
]
}
}
# GET /v1/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.
All monetary values are in the program's default commission, read more in /v1/account.
# Filters
| Parameter | Type | Description |
|---|---|---|
| status | string | A comma-separated list of transaction statuses: pending, rejected, approved, invoiced, paid-invoice, paid-affiliate. |
| channel | int | A comma-separated list of channel id-numbers. |
| group | string | Group the result by channel, month or day |
| from | string | ISO 8601 date, urlencoded |
| to | string | ISO 8601 date, urlencoded |
# Result
{
"channel": {
"id": 1,
"name": "Affiliate website"
},
"impressions": {
"total": 292,
"unique": 12
},
"clicks": {
"total": 227,
"unique": 191
},
"transactions": {
"count": 7,
"orderValue": 8846.40,
"commission": 702.13,
"transactionFee": 215.64
},
"cr": 3,
"ctr": 78,
"aov": 1263.77,
"cpc": 3.09,
"cpm": 2404.55,
"roi": 9.64
}
...
# GET /v1/transactions
List your latest transactions. By default the limit is set to 10, and the result is sorted by descending date.
# Filters
| Parameter | Type | Description |
|---|---|---|
| limit | int | Limit the result from 1-100. |
| status | string | A comma-separated list of statuses: pending, approved, rejected, invoiced, paid-invoice, paid-affiliate. |
| tag | int | A comma-separated list of tag id-numbers. |
| sort | string | Sort the result, asc or desc |
| from | string | ISO 8601 date, urlencoded |
| to | string | ISO 8601 date, urlencoded |
| cursor (depricated) | int | Next transactionID, used for pagination. |
| offset | int | Next offset number, used for pagination. |
# Result
The status in the result differ from the query input, as follows: Approved, Pending, Invoiced, Invoiced Paid, Paid to affiliate, Rejected.
{
"current": 752749,
"next": 344733,
"currentOffset": 0,
"nextOffset": 3,
"data": [
{
"transactionID": 752749,
"channelID": 235,
"commID": 13,
"orderID": "#213765r23167-2",
"orderValue": 100,
"commission": 15,
"transactionFee": 7.5,
"currency": "SEK",
"couponCode": null,
"datetime": "2018-10-20T00:00:00+02:00",
"status": "Invoice Paid",
"eai": null,
"orderComment": null
},
{
"transactionID": 744879,
"channelID": 235,
"commID": 13,
"orderID": "762383274653764",
"orderValue": 2567,
"commission": 2053.6,
"transactionFee": 410.72,
"currency": "USD",
"couponCode": "FREESHIPPING",
"datetime": "2018-10-15T00:00:00+02:00",
"status": "Paid to affiliate",
"eai": null,
"orderComment": null
},
{
"transactionID": 344732,
"channelID": 18546,
"commID": 1255,
"orderID": "44321234z2",
"orderValue": 100,
"commission": 15,
"transactionFee": 0,
"currency": "EUR",
"couponCode": null,
"datetime": "2018-02-19T19:28:15+01:00",
"status": "Paid to affiliate",
"eai": "44321234z2",
"orderComment": null
}
]
}
# GET /v1/transactions/:orderid
Get a specific transaction.
# Input parameters
- orderID: string
# Result
{
"transactionID": 783004,
"channelID": 235,
"commID": 123,
"orderID": "123test",
"orderValue": 10000,
"commission": 1500,
"transactionFee": 450,
"currency": "SEK",
"couponCode": null,
"datetime": "2018-11-14T13:44:38+01:00",
"status": "Pending",
"eai": null,
"orderComment": null
}
# PATCH /v1/transactions/:orderid
Update a specific transaction. You are only able to update transactions with status Pending. If your are updating the orderValue an new commission and transaction fee will be calculated. A history of transaction changes will also be logged.
# Input parameters
- status: string
rejected,approved - orderValue: number (in the same currency as the original transaction)
- eai: string
- rejectReason*: string. Required when status is changed to
rejected. Common reasons isReturnorFraud(Visible to your affiliates).
# Example input
Approve the transaction:
{
"status": "approved"
}
Change orderValue:
{
"orderValue": 500
}
Reject the transaction:
{
"status": "rejected",
"rejectReason": "Return"
}
# Result
Will return the updated transaction object.
{
"transactionID": 783004,
"channelID": 235,
"commID": 123,
"orderID": "123test",
"orderValue": 500,
"commission": 50,
"transactionFee": 15,
"currency": "SEK",
"couponCode": null,
"datetime": "2018-11-14T13:44:38+01:00",
"status": "Approved",
"eai": null,
"orderComment": null
}