Addrevenue API reference

Addrevenue API reference

Our REST API has been developed to support the needs of affiliates and advertisers. It uses OAuth 2.0 and you generate a life-time API token manually in our user interface. This Bearer token is then sent as an Authorization header.

 

API Base URL

All endpoints starts with the base url:

https://addrevenue.io/api/v2

Make sure to always use the HTTPS protocol.

 

Authentication

To generate an API login to Addrevenue and click on API tokens and then Generate a new API token. This will create a unique life-time API token for the logged in user, authorizing the client to act on behalf of this user.

The token should then be sent as a Bearer token in all requests to any API endpoints.

Example of a header:

Authorization: Bearer 1892cd44-c59c-42bf-9f1d-a5316ea695cc
Content-type: application/json

 

Errors

Sending an empty or invalid Bearer token will result in any of these http errors:

403 Authorization header not found
This indicates that the Authorization header is missing, or malformed in some way, for example missing the "Bearer" string.

403 Invalid token
The header is correctly formatted, but the provided API token does not exist.

403 Inactive account
The header is correctly formatted and the provided API token exists, but it belongs to an account that is not active.

 

Responses

All responses are in JSON format and contains http_code (same as in response header), count (number of result items) and results (an array of result items).

Example (shortened):

{
    "http_code": 200,
    "count": 2,
    "results": [
        {
            "id": 1000,
            "description": "Sample campaign A"
        },
        {
            "id": 1001,
            "description": "Sample campaign B"
        }
    ]

 

API Endpoints

Since this API is still a beta version under development, we have postponed the exact documentation of the response body of all endpoints.

• Advertisers
• Banners
• Campaigns
• Channels
• Events
• Payouts
• Products
• Product feeds
• Relations
• Stats
• Transactions

 

Request parameters

In general you are able to send request parameters in the query string with the same names as in the response to filter the request. For example if you want to fetch only the clicks for clickId 6230fe5f0fc866.4851567a, the request would look like this /events?type=Click&clickId=6230fe5f0fc866.4851567a.

 

Date intervals

For some endpoint it is applicate to provide date interval request parameters, such as for transactions and events. These are provided by using fromDate and/or toDate. They can be used together to set an interval or only one of them.

 

 

Get advertisers

GET /advertisers

If authenticated as an affiliate account the response includes an array of all active advertisers. If a channelId is provided, the response will only include advertisers with any type relations (active, pending or rejected). The relation status will be returned as relationStatus.

If authenticated as an advertiser account the response includes only the authenticated advertiser account itself.

Request parameters:

Parameter	Description
channelId integer	Optional. If a Channel ID is provided, the response will only include advertisers with any type relations to the given channel.

 

Get banners

GET /banners

This endpoint returns an array of all banner groups and its banners.

If authenticated as an affiliate account the response includes an array of all banner groups and its banners for all advertisers. If a channelId is provided and there is an approved relation between the channel and the advertiser, a tracking code for every banner will be included in the response.

If authenticated as an advertiser account the response include an array of all banner groups and its banners for this advertiser.

Request parameters:

Parameter	Description
channelId integer	Optional. If a Channel ID is provided, tracking codes for all banners will be included in the response.

 

 

Get campaigns

GET /campaigns

This endpoint returns an array of all campaigns (discount codes and offers).

If authenticated as an affiliate account the response includes all public active campaigns for all advertisers plus all exclusive campaigns for channels belonging to this specific affiliate. If a channelId request parameter is provided only campaigns for advertisers with approved relation to the channel will be returned and a trackingLink for every campaign will be included in the response.

If authenticated as an advertiser account the response include all campaigns (both active and non-active, and both public and channel exclusive) for this advertiser.

Request parameters:

Parameter	Description
channelId integer	Optional. If a Channel ID is provided, only campaigns for advertisers with approved relations to the channel will be included. Channel specific tracking links for all campaigns will be included in the response.

 

 

Get channels

GET /channels

If authenticated as an affiliate account the response includes an array of all channels belonging to the authenticated account.

If authenticated as an advertiser account the a 403 Forbidden response header will be returned.

 

 

Get events

GET /events

Returns all tracking events for the authenticated account.

 

 

Get payouts

GET /payouts

Returns all payouts for the authenticated affiliate account. If the authenticated account is not an affiliate, 403 Forbidden is returned.

 

 

Get products

GET /products

Returns all products in the product catalog. The response is paginated.

Request parameters:

Parameter	Description
productsPerPage integer	Optional. Number of products in the response. Default is 25. Maximum is 100.
selectedPage integer	Optional. The offset of the pagination. Default is 0, which gets the productsPerPage first products. Passing 1, returns the next productsPerPage results.

Example:

/products?productsPerPage=50&selectedPage=3

 

 

Get product feeds

GET /productfeeds?channelId=xxxxxxx

This endpoint returns an array of all product feeds, for the specified channel.

If authenticated as an advertiser account there will be a 403 Forbidden response, as this endpoint is intended for affiliates only..

Request parameters:

Parameter	Description
channelId integer	Required. The Channel ID is required, as it will be included in the generated product feed urls.

 

 

Get relations

GET /relations

Returns all relations between channels and advertisers for the authenticated account.

 

 

Get stats

GET /stats

Returns aggregated statistics such as banner impressions, clicks, transactions etc for the authenticated account.

Request parameters:

Parameter	Description
groupBy string	Optional. If included, the response will be aggregated on the groupBy level. Accepted options for groupBy are date, advertiser, channel and program. If not provided the response will be aggregated into one single chunk. To group on multiple dimensions you can use a comma sign as delimiter.

 

 

Get transactions

GET /transactions

Returns all transactions for the authenticated account.

Request parameters:

Parameter	Description
includeClicks integer	Optional. If included and set to 1, the response will also include an array of all the clicks that preceeded the transaction.

 

Under development!!!

When more endpoints will be added this API reference will be updated. Please note that this API is in beta version and documentation of request responses are postponed.

 

Change log

2022-05-12: Added new /payouts endpoint for affiliates to retrieve all payouts.

2022-04-28: Added new /productfeeds endpoint for affiliates to retrieve a list of all product feed urls.

2022-04-27: Added new /relations endpoint to list your relations between channels and advertisers.

2022-04-22: Added the possibility to group /stats on multiple dimensions

2022-04-21: Added channelId as a request parameter to /advertisers endpoint, to limit the response to advertisers with relations to the given channel.

2022-04-20: Added the /stats endpoint to get aggregated statistics.

2022-04-19: Added the possibility to send limit the responses of certain endpoints such as transactions and event by using query string parameters fromDate and/or toDate.

2022-03-22: When sending channelId to /campaigns endpoint, now only campaigns for advertisers with an approved relation to the channel will be shown.

2022-03-19: Added includeClicks request parameter to /transactions endpoint, to include all preceeding clicks in an array.

2022-03-18: Added trackingLink in the response from the /campaigns endpoint, if parameter channelId is provided.

2022-03-18: Added advertiserName in the response from the /campaigns endpoint.

2022-03-18: Added advertiserName in the response from the /banners endpoint.