# 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 parameter cursor depricated.
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 Date and time with offset (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 and time with offset, urlencoded
to	string	ISO 8601 Date and time with offset, 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 and time with offset, urlencoded
to	string	ISO 8601 Date and time with offset, 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 is Return or Fraud (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
}