Introduction

We provide API for publishers for easier programmatic access to our resources.

Currently API supports running reports based on our "report builder" we use internally in consumable. New features will be added to the API in following period.

Endpoint url: https://publisher-api.consumable.com. In following text consider all mentioned routes as relative to this url.

Authentication

Endpoint: /auth

API requires user to be authenticated in order to execute requests.

Use your login credentials from publisher dash for API authentication.

Authentication is simple - just send your username and password and you will get TOKEN in response which you can use in all following API requests.

Just set authorization header like: Authorization: Bearer [auth-token]

Token looks something like this:

eyJhbGciOiJIUzUxMiJ9eyJzdWIiOiJ0ZXN0QGNvbnN1bWFibGUuY29tIiwicm9sZXMiOlsiUFVCTElTSEVSIl0sInJpZ2h0cyI6W10sImlhdCI6MTU0ODE3ODk5MSwiZXhwIjoxNTUwNzcwOTkxfSDHg1IQEh8oFkVvHDUxfGRvEX1QJBpjUgZKFBV2HUIpbxxbWVBoR3EmaOqhnA==

Examples

Successful Authentication

Curl request

$ curl 'https://publisher-api.consumable.com/auth' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json; charset=UTF-8' \
    -d '{"password":"Consumable12345","email":"john@consumable.com"}'

HTTP request

POST /auth HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8
Host: publisher-api.consumable.com
Content-Length: 60

{"password":"Consumable12345","email":"john@consumable.com"}

Parameters

Path Type Description

Path	Type	Description
`email`	`String`	The user’s email - must not be empty
`password`	`String`	The user’s password - must not be empty

email

String

The user’s email - must not be empty

password

String

The user’s password - must not be empty

Response

[auth-token]

[auth-token] - is the TOKEN you need for for all subsequent requests.

Bad Request

In case you forget to pass username and/or password, bad request 400 will be returned by the server

{"error":{"code":"2001","name":"Unclassified error","messages":["Please provide `email` and `password`"]}}

Invalid credentials

In case of invalid credentials, error code 401 is returned by the server

{"error":{"code":"2009","name":"Forbidden","messages":["Unauthorized Request"]}}

Ad units

Endpoint: /ad-units

Request

$ curl 'https://publisher-api.consumable.com/ad-units' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer [auth-token]'

Response

[ {
  "id" : "1",
  "name" : "test-0001-cnsmbl-container-728x90-ads-dr-d",
  "headerBidding" : false,
  "readyApprovalRequired" : false,
  "usingConfiant" : false,
  "unitCreateRequestSent" : false,
  "unitBuildPending" : false,
  "unitCreateAdstxtOverride" : false,
  "fromPublisherRequest" : false,
  "bidder" : false,
  "videoUnit" : false,
  "videoUnitCompanion" : false,
  "vastUnit" : false,
  "feedType" : "N_A",
  "test" : false,
  "breakoutFromIframe" : false,
  "createPixelUnit" : false,
  "hasPendingUpdateEmails" : false,
  "healthy" : false,
  "serverbid" : false,
  "s2s" : false,
  "bidderCalc" : false,
  "flag" : false,
  "postHealthCheck" : false,
  "waitsToBeActive" : false,
  "enabled" : false
}, {
  "id" : "1",
  "name" : "test-0002-cnsmbl-container-300x250-ads-dr-d",
  "headerBidding" : false,
  "readyApprovalRequired" : false,
  "usingConfiant" : false,
  "unitCreateRequestSent" : false,
  "unitBuildPending" : false,
  "unitCreateAdstxtOverride" : false,
  "fromPublisherRequest" : false,
  "bidder" : false,
  "videoUnit" : false,
  "videoUnitCompanion" : false,
  "vastUnit" : false,
  "feedType" : "N_A",
  "test" : false,
  "breakoutFromIframe" : false,
  "createPixelUnit" : false,
  "hasPendingUpdateEmails" : false,
  "healthy" : false,
  "serverbid" : false,
  "s2s" : false,
  "bidderCalc" : false,
  "flag" : false,
  "postHealthCheck" : false,
  "waitsToBeActive" : false,
  "enabled" : false
} ]

Path Type Description

Path	Type	Description
`[].id`	`String`	Ad unit ID - use it later on in reporting
`[].name`	`String`	Ad unit name

[].id

String

Ad unit ID - use it later on in reporting

[].name

String

Ad unit name

Reporting

Endpoint: /report

Reporting is based on our internal "report builder" which gives you ability to construct any report you want using 3 types of parameters:

Dimensions - the axis on which you are running your report - ex: run by day, ad unit, site etc..
Metrics - exact metrics you are interested in - ex: revenue, impressions, etc
Filters - filter result data by limiting date range, ad unit and/or site

Minimum requirements to run report: at least one dimensions, one metric and date range.

Dimensions

Name Description

Name	Description
`PUBLISHER`	publisher itself - use this dimension when you want top level (total) metrics to be displayed
`DAY`	sum data by day
`MONTH`	sum data by month
`URL`	run report by domain
`AD_UNIT`	run report by ad unit
`DEVICE_PLACEMENT`	possible values: `DESKTOP`, `MW` TBD
`WIDGET_SIZE`	widget size in format width x height
`WIDGET`	ID of a widget

PUBLISHER

publisher itself - use this dimension when you want top level (total) metrics to be displayed

DAY

sum data by day

MONTH

sum data by month

URL

run report by domain

AD_UNIT

run report by ad unit

DEVICE_PLACEMENT

possible values: DESKTOP, MW TBD

WIDGET_SIZE

widget size in format width x height

WIDGET

ID of a widget

Metrics

Name Description

Name	Description
`PUBLISHER`	publisher name
`DAY`	-
`MONTH`	-
`AD_UNIT`	ad unit name
`AD_UNIT_CUSTOM_NAME`	custom ad unit name (if exist)
`URL`	domain url
`PUBLISHER_REVENUE`	Net revenue
`IMPRESSIONS`	number of widget impressions
`DEVICE_PLACEMENT`	-
`IO_CPM`	-
`PUBLISHER_SHARE_REVENUE`	revenue share
`WIDGET_SIZE`	widget size in format width x height
`WIDGET`	ID of a widget
`BIDDER`	`true` if ad unit is bidder.
`ACTIVITY_STATUS`	Unit status. Possible values: `ACTIVE` `INACTIVE`

PUBLISHER

publisher name

DAY

MONTH

AD_UNIT

ad unit name

AD_UNIT_CUSTOM_NAME

custom ad unit name (if exist)

URL

domain url

PUBLISHER_REVENUE

Net revenue

IMPRESSIONS

number of widget impressions

DEVICE_PLACEMENT

IO_CPM

PUBLISHER_SHARE_REVENUE

revenue share

WIDGET_SIZE

widget size in format width x height

WIDGET

ID of a widget

BIDDER

true if ad unit is bidder.

ACTIVITY_STATUS

Unit status. Possible values: ACTIVE INACTIVE

Filters

Name Type Description

Name	Type	Description
`dateFrom`	string	format: YYYY-MM-DD - ex: 2019-01-01
`dateTo`	string	format: YYYY-MM-DD - ex: 2019-01-01
`adUnitIds`	array	Array of ad unit ids - to get a list of ids check ad units route

dateFrom

string

format: YYYY-MM-DD - ex: 2019-01-01

dateTo

string

format: YYYY-MM-DD - ex: 2019-01-01

adUnitIds

array

Array of ad unit ids - to get a list of ids check ad units route

Lets run a couple of examples to see how different combinations are used in practice.

Examples

Publisher Revenue

Request

{
  "version" : "1.0",
  "forceDPDToday" : "0",
  "debug" : "0",
  "logPrefix" : "",
  "metrics" : [ "PUBLISHER_REVENUE" ],
  "dimensions" : [ "PUBLISHER" ],
  "filters" : {
    "dateFrom" : "2019-01-01",
    "dateTo" : "2019-01-07",
    "includeCnsmblData" : false
  }
}

Response

{
  "request" : {
    "metrics" : [ "PUBLISHER_REVENUE" ],
    "dimensions" : [ "PUBLISHER" ],
    "filters" : {
      "dateFrom" : "2019-01-01",
      "dateTo" : "2019-01-07"
    }
  },
  "report" : [ {
    "publisherNetRevenue" : 1000
  } ],
  "total" : {
    "publisherNetRevenue" : 1000
  }
}

Path Type Description

Path	Type	Description
`request`	`Object`	Report request sent from publisher
`report`	`Array`	Generated report based on request. Report can have multiple rows (ex: multiple days), therefore array is used
`total`	`Object`	Total sum of values in `report`. Ex: requested report was `daily for the last week` - in `total` you will find SUM for last week, while in `report` you can find report you requested
`report.[].publisherNetRevenue`	`Number`	Publisher revenue

request

Object

Report request sent from publisher

report

Array

Generated report based on request. Report can have multiple rows (ex: multiple days), therefore array is used

total

Object

Total sum of values in report. Ex: requested report was daily for the last week - in total you will find SUM for last week, while in report you can find report you requested

report.[].publisherNetRevenue

Number

Publisher revenue

Publisher Revenue By Day

Request

{
  "version" : "1.0",
  "forceDPDToday" : "0",
  "debug" : "0",
  "logPrefix" : "",
  "metrics" : [ "DAY", "PUBLISHER_REVENUE" ],
  "dimensions" : [ "DAY" ],
  "filters" : {
    "dateFrom" : "2019-01-01",
    "dateTo" : "2019-01-07",
    "includeCnsmblData" : false
  }
}

Response

{
  "request" : {
    "metrics" : [ "DAY", "PUBLISHER_REVENUE" ],
    "dimensions" : [ "DAY" ],
    "filters" : {
      "dateFrom" : "2019-01-01",
      "dateTo" : "2019-01-07"
    }
  },
  "report" : [ {
    "day" : "2019-01-01",
    "publisherNetRevenue" : 100
  }, {
    "day" : "2019-01-02",
    "publisherNetRevenue" : 200
  }, {
    "day" : "2019-01-03",
    "publisherNetRevenue" : 300
  } ],
  "total" : {
    "publisherNetRevenue" : 600
  }
}

Path Type Description

Path	Type	Description
`report.[].publisherNetRevenue`	`Number`	Publisher revenue
`report.[].day`	`String`	Day

report.[].publisherNetRevenue

Number

Publisher revenue

report.[].day

String

Day

Ad Unit Revenue

Request

{
  "version" : "1.0",
  "forceDPDToday" : "0",
  "debug" : "0",
  "logPrefix" : "",
  "metrics" : [ "AD_UNIT", "PUBLISHER_REVENUE", "BIDDER" ],
  "dimensions" : [ "AD_UNIT" ],
  "filters" : {
    "dateFrom" : "2019-01-01",
    "dateTo" : "2019-01-01",
    "adUnitIds" : [ "e2b65b60-7927-499e-a4b0-cf1b17b94cb8" ],
    "includeCnsmblData" : false
  }
}

notice the adUnitIds filter - if you omit it you will get report for all ad units

Response

{
  "request" : {
    "metrics" : [ "AD_UNIT", "PUBLISHER_REVENUE", "BIDDER" ],
    "dimensions" : [ "AD_UNIT" ],
    "filters" : {
      "adUnitIds" : [ "e2b65b60-7927-499e-a4b0-cf1b17b94cb8" ],
      "dateFrom" : "2019-01-01",
      "dateTo" : "2019-01-01"
    }
  },
  "report" : [ {
    "bridgeAdUnitName" : "test-0001-cnsmbl-container-728x90-ads-dr-d",
    "publisherNetRevenue" : 100,
    "bidder" : true
  } ],
  "total" : {
    "publisherNetRevenue" : 100
  }
}

Path Type Description

Path	Type	Description
`report.[].bridgeAdUnitName`	`String`	Ad unit name
`report.[].publisherNetRevenue`	`Number`	Publisher ad unit revenue

report.[].bridgeAdUnitName

String

Ad unit name

report.[].publisherNetRevenue

Number

Publisher ad unit revenue

Site Revenue By Day

Request

{
  "version" : "1.0",
  "forceDPDToday" : "0",
  "debug" : "0",
  "logPrefix" : "",
  "metrics" : [ "URL", "DAY", "PUBLISHER_REVENUE" ],
  "dimensions" : [ "URL", "DAY" ],
  "filters" : {
    "dateFrom" : "2019-01-01",
    "dateTo" : "2019-01-03",
    "includeCnsmblData" : false
  }
}

Response

{
  "request" : {
    "metrics" : [ "URL", "DAY", "PUBLISHER_REVENUE" ],
    "dimensions" : [ "URL", "DAY" ],
    "filters" : {
      "dateFrom" : "2019-01-01",
      "dateTo" : "2019-01-03"
    }
  },
  "report" : [ {
    "day" : "2019-01-01",
    "url" : "test",
    "publisherNetRevenue" : 100
  }, {
    "day" : "2019-01-02",
    "url" : "test",
    "publisherNetRevenue" : 200
  }, {
    "day" : "2019-01-03",
    "url" : "test",
    "publisherNetRevenue" : 300
  } ],
  "total" : {
    "publisherNetRevenue" : 600
  }
}

Path Type Description

Path	Type	Description
`report.[].url`	`String`	Site url
`report.[].day`	`String`	Day
`report.[].publisherNetRevenue`	`Number`	Publisher site revenue

report.[].url

String

Site url

report.[].day

String

Day

report.[].publisherNetRevenue

Number

Publisher site revenue

Publisher API Docs

Introduction

Authentication

Examples

Successful Authentication

Bad Request

Invalid credentials

Ad units

Request

Response

Reporting

Dimensions

Metrics

Filters

Examples

Publisher Revenue

Request

Response

Publisher Revenue By Day

Request

Response

Ad Unit Revenue

Request

Response

Site Revenue By Day

Request

Response