Revenue API for Managed GAM Accounts

Implementation Guides Advertisement
1

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—ideal when full access isn’t granted or commissions must be subtracted.

Endpoint Overview

All endpoints start with:

/api/site/:siteId/revenue
  • Auth required: Bearer <TOKEN>
  • Only accessible by admin users
  • 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).

Finally, users must specify fallback keys in case Compass could not find the original key in the revenue database.

Only admin accounts with the proper acl can access the revenue API.

As other API sections, all revenue API operations require an authorization token, obtained after logging in (see the specific documentation).

In addition, 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 object contains:

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.

Finally, there is 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

Process each revenue object (key, type, price and optionally currency and source`) of the given data and create or update 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 with the current revenue objects associated to 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" }
]