Revenue API for managed GAM accounts

Overview

NOTE:

This API is only for ad networks , not publishers. For standard GAM revenue integration, use this guide.

Use this API to upload revenue data from managed GAM accounts. It is ideal when full access is not granted or when commissions must be subtracted before reporting.

Endpoint overview

All endpoints start with:

/api/site/:siteId/revenue

• Auth required: Bearer <TOKEN>
• Only accessible by users with the Advertising manager role
• Responses in JSON

Users must provide a set of lineItemId and adUnitPath entries to cover all cases. When specifying the adUnitPath, note that it should take the form /:adnetwork/:ad_unit_level_1/ad_unit_level_2/.../ad_unit_code, just like the one used to configure the slot (eg /123456789/section_1/top_300_600).

Users must also specify fallback keys in case Compass could not find the original key in the revenue database.

All revenue API operations require an authorization token, obtained after logging in (see the specific documentation).

All revenue endpoints begin with /api/site/:siteId/revenue, where :siteId is the identifier of an accessible site. Multi-site accounts can use multiple identifiers, one for each managed site.

All responses are in JSON format.

Revenue object

Each revenue object contains the following fields:

Field	Description
key	ID for revenue (lineItemId or adUnitPath). Add amp suffix for AMP.
type	Revenue type. This is usually the Google Ads line item type (e.g. HOUSE, NETWORK, SPONSORSHIP). Case-insensitive, stored uppercase.
price	Integer in micro-currency units (e.g. 1000 = 0.001 currency)
currency	ISO code. Optional. Defaults to site currency.
source	Origin label. Optional. Default: "api"

AMP requests require a fallback key named -1amp.

Operations

The API lets you create and update revenue objects, one at a time or in batch.

You can also list all the objects, and get the details of a specific object.

There is also a delete operation.

Create or update a revenue object

Creates a new revenue object with the given data (key, type, price and optionally currency and source), and associates it with the given site. Updates an existing revenue object with the given values if it finds the given key.

POST https://api.newsroom.bi/api/site/:siteId/revenue

Headers:

Authorization: Bearer <TOKEN>
Content-Type: application/json

Body:

{ "key": "key", "type": "type", "price": price }

Get or Create Response

A JSON object with all revenue data fields, or a JSON object with the error message.

200: { "key": "key", "type": "type", "price": price, "currency": "currencyISO", "source": "source" } (updated)
201: { "key": "key", "type": "type", "price": price, "currency": "currencyISO", "source": "source" } (created)
400: { "msg": "Some parameters are missing or invalid" }
403: { "msg": "Site cannot be accessed" }
500: { "msg": "Internal server error" }

Get or Create Example

Request:

curl --location --request POST 'http://api.newsroom.bi/api/site/150/revenue' \
--header 'Authorization: Bearer *************' \
--header 'Content-Type: application/json' \
--data-raw '{
    "key": "demo_key",
    "price": 300,
    "type": "HOUSE"
}'

Response:

{
    "key": "demo_key",
    "type": "HOUSE",
    "price": 300,
    "currency": "EUR",
    "source": "api"
}

Create or update multiple revenue objects

Processes each revenue object (key, type, price and optionally currency and source) in the request body and creates or updates them accordingly. The scope of the request is the given site.

POST https://api.newsroom.bi/api/site/:siteId/revenue/bulk

Headers:

Authorization: Bearer <TOKEN>
Content-Type: application/json

Body:

[
  { "key": "key1", "type": "type1", "price": price1 },
  { "key": "key2", "type": "type2", "price": price2, "currency": "currency" },
  { "key": "key3", "type": "type3", "price": price3, "currency": "another_currency", "source": "custom"},
  ...
]

Multiple objects Response

A JSON object that indicates the status of the request, including any error messages.

207: { "msg": "OK" }
207: { "msg": "Partial OK, not all given items are valid" }
400: { "msg": "All given items are invalid" }
403: { "msg": "Site cannot be accessed" }
500: { "msg": "Internal server error" }

Multiple Objects Example

Request:

curl --location --request POST 'http://api.newsroom.bi/api/site/150/revenue' \
--header 'Authorization: Bearer *************' \
--header 'Content-Type: application/json' \
--data-raw '[
  {
    "key": "demo_key_1",
    "type": "HOUSE",
    "price": 100
  },
  {
    "key": "demo_key_2",
    "type": "SPONSORSHIP",
    "price": 200,
    "currency": "USD"
  },
  {
    "key": "demo_key_3",
    "type": "CUSTOM",
    "price": 30000,
    "currency": "JPY",
    "source": "custom"
  }
]'

Response:

{ "msg": "OK" }

List all revenue objects

Returns a list of all current revenue objects associated with the given site.

GET https://api.newsroom.bi/api/site/:siteId/revenue

Headers:

Authorization: Bearer <TOKEN>

List All Response

A JSON array of revenue objects with key, type, price, currency and source, or a JSON object with the error message.

200: [{ "key": "xxxx", "type": "tttt", "price": ####, "currency": "currency", "source": "source" }, ...]
403: { "msg": "Site cannot be accessed" }
500: { "msg": "Internal server error" }

List All Example

Request:

curl --location --request GET 'http://api.newsroom.bi/api/site/150/revenue' \
--header 'Authorization: Bearer ***************'

Response:

[
    {
        "key": "demo_key",
        "type": "HOUSE",
        "price": 300,
        "currency": "EUR",
        "source": "api"
    },
    {
        "key": "demo_key_2",
        "type": "SPONSORSHIP",
        "price": 200,
        "currency": "USD",
        "source": "api"
    },
    {
        "key": "demo_key_3",
        "type": "CUSTOM",
        "price": 30000,
        "currency": "JPY",
        "source": "custom"
    }
]

Get revenue details

Returns the revenue object for the given key belonging to the given site.

GET https://api.newsroom.bi/api/site/:siteId/revenue/:key

Headers:

Authorization: Bearer <TOKEN>

Get Details Response

A JSON object with key, type, price, currency and source, or a JSON object with the error message.

200: { "key": "xxxx", "type": "tttt", "price": ###, "currency": "currency", "source": "source" }
403: { "msg": "Site cannot be accessed" }
404: { "msg": "Revenue data for the given key not found" }
500: { "msg": "Internal server error" }

Get Details Example

Request:

curl --location --request GET 'http://api.newsroom.bi/api/site/150/revenue/demo_key' \
--header 'Authorization: Bearer ***************'

Response:

{
    "key": "demo_key",
    "type": "HOUSE",
    "price": 300,
    "currency": "EUR",
    "source": "api"
}

Delete a revenue object

Finds the revenue object for the given key and deletes it from the given site database. The key is not case-sensitive.

DELETE https://api.newsroom.bi/api/site/:siteId/revenue/:key

Headers:

Authorization: Bearer <TOKEN>

Delete Response

A JSON object that indicates the status of the request, including any error messages.

200: { "msg": "OK" }
403: { "msg": "Site cannot be accessed" }
404: { "msg": "Revenue data for the given key not found" }
500: { "msg": "Internal server error" }

Delete Example

Request:

curl --location --request DELETE 'http://api.newsroom.bi/api/site/150/revenue/demo_key' \
--header 'Authorization: Bearer ***************'

Response:

{
    "msg": "OK"
}

Full example

Set of keys with lineitemId and adUnitPath (including AMP), and the fallback

[
  { "key": "-1amp", "type": "amp", "price": 150 },
  { "key": "/123456789/default/topamp", "type": "amp", "price": 350 },
  { "key": "/123456789/people/top_1_1amp", "type": "amp", "price": 120 }
  { "key": "55551", "type": "price_priority", "price": 1000 },
  { "key": "55552", "type": "sponsorship", "price": 383 },
  { "key": "55553", "type": "house", "price": 0 },
  { "key": "55554", "type": "network", "price": 400 },
  { "key": "55555", "type": "custom", "price": 123 },
  { "key": "/123456789/default/home_top", "type": "NETWORK", "price": 180 },
  { "key": "/123456789/default/home_mid_2_2", "type": "NETWORK", "price": 75 }
]

Same data, but specifying the currency and the source.

[
  { "key": "-1amp", "type": "amp", "price": 150, "currency": "EUR", "source": "calculated" },
  { "key": "/123456789/default/topamp", "type": "amp", "price": 350, "currency": "EUR", "source": "dfp1" },
  { "key": "/123456789/people/top_1_1amp", "type": "amp", "price": 120, "currency": "EUR", "source": "dfp1" }
  { "key": "55551", "type": "price_priority", "price": 1000, "currency": "USD", "source": "dfp2"},
  { "key": "55552", "type": "sponsorship", "price": 383, "currency": "USD", "source": "dfp2" },
  { "key": "55553", "type": "house", "price": 0, "currency": "USD", "source": "dfp2" },
  { "key": "55554", "type": "network", "price": 400, "currency": "USD", "source": "dfp2" },
  { "key": "55555", "type": "custom", "price": 123, "currency": "USD", "source": "dfp2" },
  { "key": "/123456789/default/home_top", "type": "NETWORK", "price": 180, "currency": "EUR", "source": "dfp1" },
  { "key": "/123456789/default/home_mid_2_2", "type": "NETWORK", "price": 75, "currency": "EUR", "source": "dfp1" }
]