Important notes

Beta warning

This API definition is still work-in-progress. Specifications may change without any further notice. Do not consider this document final if this banner is present.

Preface

Targeted audience

This guide documents the Affiliboard API and is targeted at those people who want to integrate the Affiliboard data in their own services.

Authentication (mandatory)

Authentication: Token your-auth-token

You need to authenticate any request to the Affiliboard API using your personal authentication token. To authenticate, set the HTTP Authentication header to the value Token X (where X is your token).

You can create such a token in your account settings.

Versioning (optional)

Accept-Version: v1 (default)
Accept-Version: vX

The current version of the Affiliboard API is v1 and described below. We may change the API in the future, i.e. adding methods or alter their behavior. To access a specific version, add an explicit Accept-Version header.

If you omit the version header, you will get the latest available version.

HTTP Method Override (optional)

X-HTTP-Method-Override: overridden-method

Each method described below requires a defined HTTP verb (cf. RFC 2616, Section 9 ). If your client has no capability to use the actual HTTP verb, you may set an X-HTTP-Method-Override header and submit a POST request:

curl -H 'Accept-Version: v1' \
     -H 'Authentication: Token (your-auth-token)' \
     -H 'X-HTTP-Method-Override: PUT' \
     -X POST \
     http://affiliboard.com/api/...

Data format (optional)

Accept: application/json (default)
Accept: text/cvs

The Affiliboard API is primarily a JSON REST API meaning that requesting any data happens via HTTPS requests and returns JSON-formatted data.

Alternatively, you may chose to get a response in CVS format, if you either set the HTTP Accept header to text/cvs or by appending .cvs to the request URL (e.g. /api/sites.cvs). The response data will contain a comma-separated list of values, one line per item and the first line as header.

Please note that any failures still return as JSON formatted data. If you receive a non-2xx status code (see next section) you should not continue processing the response data as CVS.

Response codes

The API server will respond with the usual HTTP response codes (cf. RFC 2616, Section 10 ):

Status code RFC Description
200 OK

The operation was successful.

201 Created

The operation was successful and created a new resource.

400 Bad Request

Some of the required parametes were not present.

401 Unautorized

You are not allowed to perform the operation. This status indicates that your authentication token is invalid.

404 Not Found

You either called a non-existent method, or the resource a method operates on was not found.

422 Unprocessable Entity

This response indicates that your request was vaild, but the submitted data could not be processed. The returned response body contains additional information, e.g.:

{"error":"name can't be blank"}
500 Internal Server Error

This is a generic error, please refer to the response body for further information.

502 Bad Gateway

The server propably undergoes a reboot. Please wait a few moments and try again.

503 Service Unavailable

The server is currently in maintenance mode. Please try again later.

GET /api/accounts

since: v1

Description

Get all accounts as JSON array. The result set may contain 0 or more objects with these keys:

id
Integer
The account's unique ID.
name
String
The account's name.
default_site_id
Integer (or null if not set)
The default site ID for newly discovered channels.
created_at
Date, as ISO 8601 formatted String
The date of creation.
updated_at
Date, as ISO 8601 formatted String
The date of the last update.

Parameters

This method expects no parameters.

Example

curl -H 'Accept-Version: v1' \
     -H 'Authentication: Token (your-auth-token)' \
     http://affiliboard.com/api/accounts

PUT /api/accounts/:id

since: v1

Description

Update a single account. On success, the server responds with a 200 OK code and returns a single JSON object with the updated account (see above for the description of an Account resource).

Parameters

Name Type Default Description Required?
id Integer Account ID yes
account This parameter is a hash type (also known as Map or simply a key/value pair) and not used on its own (there is no valid value for it). Instead, you'll add the following keys.
account[name] String Account name (for display purposes) no
account[default_site_id] Integer If Affiliboard discovers a new channel for this account, the defined Site ID will be assigned. no

Example

curl -H 'Accept-Version: v1' \
     -H 'Authentication: Token (your-auth-token)' \
     -d 'account[name]=...' \
     -d 'account[default_site_id]=...' \
     -X GET \
     http://affiliboard.com/api/accounts/:id

GET /api/sites

since: v1

Description

Get all sites as JSON array. The result set may contain 0 or more objects with these keys:

id
Integer
The site's unique ID.
name
String
The site's name.
url
String
The site's URL (may be empty).
created_at
Date, as ISO 8601 formatted String
The date of creation.
updated_at
Date, as ISO 8601 formatted String
The date of the last update.

Parameters

This method expects no parameters.

Example

curl -H 'Accept-Version: v1' \
     -H 'Authentication: Token (your-auth-token)' \
     http://affiliboard.com/api/sites

PUT /api/sites/:id

since: v1

Description

Update a single site. On success, the server responds with a 200 OK code and returns a single JSON object with the updated site (see above for the description of a Site resource).

Parameters

Name Type Default Description Required?
id Integer Site ID yes
site This parameter is a hash type (also known as Map or simply a key/value pair) and not used on its own (there is no valid value for it). Instead, you'll add the following keys.
site[name] String Site name (for display purposes) no
site[url] String Site URL (for display purposes) no

Example

curl -H 'Accept-Version: v1' \
     -H 'Authentication: Token (your-auth-token)' \
     -d 'site[name]=...' \
     -d 'site[url]=...' \
     -X GET \
     http://affiliboard.com/api/sites/:id

GET /api/channels

since: v1

Description

Get all channels as JSON array. The result set may contain 0 or more objects with these keys:

id
Integer
The channel's unique ID.
key
String
The key used to identify the channel in external networks.
name
String (or null if not set)
The channel's name (uesd primarily for display purposes)
account_id
Integer
The ID of the account this channel belongs to.
site_id
Integer (or null if not set)
The ID of the site this channel is assigned to.

You may filter the result set by specifying one or more of the parameters below.

Note: The parameters are used in conjunction, i.e. specifying two or more parameters will only return those channels, where all conditions are met.

Parameters

Name Type Default Description Required?
account_id Integer Filter: return only channels for given account ID. no
site_id Integer Filter: return only channels for given site ID. no
key String Unique channel identifier of the account. no

Example

curl -H 'Accept-Version: v1' \
     -H 'Authentication: Token (your-auth-token)' \
     -d 'account_id=...' \
     -d 'site_id=...' \
     -d 'key=...' \
     -X GET \
     http://affiliboard.com/api/channels

PUT /api/channels/:id

since: v1

Description

Update a single channel. On success, the server responds with a 200 OK code and returns a single JSON object with the updated site (see above for the description of a Site resource).

Parameters

Name Type Default Description Required?
id Integer Channel ID yes
channel This parameter is a hash type (also known as Map or simply a key/value pair) and not used on its own (there is no valid value for it). Instead, you'll add the following keys.
channel[site_id] String Site ID no

Example

curl -H 'Accept-Version: v1' \
     -H 'Authentication: Token (your-auth-token)' \
     -d 'channel[site_id]=...' \
     -X GET \
     http://affiliboard.com/api/channels/:id

GET /api/annotations

since: v1

Description

Get all annotations as JSON array. The result set may contain 0 or more objects with these keys:

id
Integer
The annotations's unique ID
date
Date, as ISO 8601 formatted String
The date of the annotation.
text
String
The annotation's text.
site_id
Integer
The ID of the site this annotations belongs to.
created_at
Date, as ISO 8601 formatted String
The date of creation.
updated_at
Date, as ISO 8601 formatted String
The date of the last update.

You may filter the result set by specifying one or more of the parameters below.

Note: The parameters are used in conjunction, i.e. specifying two or more parameters will only return those channels, where all conditions are met.

Parameters

Name Type Default Description Required?
start_date Date Return only annotations dated after the start_date (inclusive; ISO 8601 format, YYYY-MM-DD) no
end_date Date Return only annotations dated before the end_date (inclusive; ISO 8601 format, YYYY-MM-DD) no
site_id Integer Return only annotations for given site ID. no

Example

curl -H 'Accept-Version: v1' \
     -H 'Authentication: Token (your-auth-token)' \
     -d 'start_date=...' \
     -d 'end_date=...' \
     -d 'site_id=...' \
     -X GET \
     http://affiliboard.com/api/annotations

PUT /api/annotations/:id

since: v1

Description

Update a single annotation. On success, the server responds with a 200 OK code and returns a single JSON object with the updated annotation (see above for the description of an Annotation resource).

Parameters

Name Type Default Description Required?
id Integer Annotation ID yes
annotation This parameter is a hash type (also known as Map or simply a key/value pair) and not used on its own (there is no valid value for it). Instead, you'll add the following keys.
annotation[site_id] String Site ID no
annotation[date] Date Annotation date no
annotation[text] String Annotation text no

Example

curl -H 'Accept-Version: v1' \
     -H 'Authentication: Token (your-auth-token)' \
     -d 'annotation[site_id]=...' \
     -d 'annotation[date]=...' \
     -d 'annotation[text]=...' \
     -X GET \
     http://affiliboard.com/api/annotations/:id

POST /api/annotations

since: v1

Description

Create an annotation. On success, the server responds with a 201 Created code and returns a single JSON object with the updated annotation (see above for the description of an Annotation resource).

Parameters

Name Type Default Description Required?
annotation This parameter is a hash type (also known as Map or simply a key/value pair) and not used on its own (there is no valid value for it). Instead, you'll add the following keys.
annotation[site_id] String Site ID yes
annotation[date] Date Annotation date (ISO 8601 format, YYYY-MM-DD) yes
annotation[text] String Annotation text yes

Example

curl -H 'Accept-Version: v1' \
     -H 'Authentication: Token (your-auth-token)' \
     -d 'annotation[site_id]=...' \
     -d 'annotation[date]=...' \
     -d 'annotation[text]=...' \
     -X GET \
     http://affiliboard.com/api/annotations

GET /api/reports

since: v1

Description

Produces a generic report as JSON document. The result may contain 0 or more objects with these keys:

date
Date, as ISO 8601 formatted String
The current data point's date.
If the resolution is set to day, the data point points to the given date.
If the resolution is set to week, the data point points to the week, the date lies within.
metric
Numeric
For each metric, the data points are returned
If the metric is a currency value (e.g. earnings), this is a Float.
If the metric is a countable value (sales, ad_views), this is an Integer.
thing_id
Integer
When a dimensioin is specified, the ID of that thing is included.

Parameters

Name Type Default Description Required?
start_date Date Start date of the report range (inclusive; ISO 8601 format, YYYY-MM-DD) yes
end_date Date End date of the report range (inclusive; ISO 8601 format, YYYY-MM-DD) yes
metrics String Comma seperated list of metrics. Allowed values are:
  • ad
  • ad_views
  • clicks
  • earnings
  • earnings_canceled
  • earnings_confirmed
  • earnings_open
  • eepc
  • eepm
  • ept_views
  • ept_visits
  • leads
  • leads_canceled
  • leads_confirmed
  • leads_open
  • sales
  • sales_canceled
  • sales_confirmed
  • sales_open
  • site
  • site_views
  • site_visits
  • sum_earnings
  • sum_leads
  • sum_sales
  • views_visits
yes
resolution String day Temporal resolution. Allowed is one of these:
  • day
  • week
yes
dimension String Comma seperated list of additional dimensions. Allowed values are:
  • account_id
  • channel_id
  • site_id
no

Example

curl -H 'Accept-Version: v1' \
     -H 'Authentication: Token (your-auth-token)' \
     -d 'start_date=...' \
     -d 'end_date=...' \
     -d 'metrics=...' \
     -d 'resolution=...' \
     -d 'dimension=...' \
     -X GET \
     http://affiliboard.com/api/reports