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.

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

  • 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.

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.

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.
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 int next transactionID, used for pagination.

Result

{
    "current": 752749,
    "next": 344733,
    "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

  • orderID: string
  • status: string rejected, approved
  • orderValue: number (in the same currency as the original transaction)
  • eai: string/empty string
  • orderComment: string/empty string

Example input

Approve the transaction:

{
	"orderID": "123test",
    "status": "approved"
}

Change orderValue:

{
	"orderID": "123test",
    "orderValue": 500
}

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
}