NAV
http shell

Introduction

Welcome to the Rise API documentation! Here you will find all that you need in order to use our various API's according to your specific needs.

We have language bindings in Shell and HTTP! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Reports API - Custom Reports

API Endpoint

https://reports-api.yellowblue.io

Using our custom reports API you are able to generate custom reports based on different dimensions, metrics and filters.

As it may take time to generate the report after sending the initial create-report request, there are two options available to choose from to use in order to know when the report is ready.

Callback Url

Polling

Authentication

The request header should look like this

GET /reports HTTP/1.1
Host: reports-api.yellowblue.io
x-api-key: fb41b2cb-e0b2-4343-87a3-e61c476ec184
Content-Type: application/json

curl --location --request GET 'https://reports-api.yellowblue.io/reports' \
--header 'x-api-key: fb41b2cb-e0b2-4343-87a3-e61c476ec184'

The Report-API uses API keys for authentication. You will be granted a new API key from your account manager.

The API key is expected in all requests and must be included in the header.

Example:

x-api-key: fb41b2cb-e0b2-4343-87a3-e61c476ec184

Rate limiting

In order to maintain a highly available and stable API we have implemented Rate Limiting. This will ensure that there is no resource starvation.

In the response headers for every request you will find the following fields:

Key Description
X-RateLimit-Limit The maximum number of requests you're permitted to make
X-RateLimit-Remaining The number of requests remaining in the current rate limit window
X-RateLimit-Reset The time at which the current rate limit window resets in UTC time

Generate a new Custom Report

POST /reports HTTP/1.1
Host: reports-api.yellowblue.io
x-api-key: fb41b2cb-e0b2-4343-87a3-e61c476ec184
Content-Type: application/json
Content-Length: 1061

{
    "name": "My custom report",
    "activityType": "s2s",
    "dimensions": ["date", "supplySource", "browser", "country"],
    "metrics": ["bids", "requests"],
    "filters": [
        {
            "filters": [
                {
                    "key": "clicks",
                    "rel": "gt",
                    "values": [
                        "6"
                    ]
                },
                {
                    "key": "bids",
                    "rel": "gt",
                    "values": [
                        "1"
                    ]
                },
                {
                    "key": "browser",
                    "rel": "eq",
                    "values": [
                        "edge",
                        "chrome"
                    ]
                }
            ]
        }
    ],
    "timeZone": "Etc/UTC",
    "endDate": "2021-03-01",
    "startDate": "2021-02-01",
    "callbackUrl": "https://cb.myservice.com"
}

curl --location --request POST 'https://reports-api.yellowblue.io/reports' \
--header 'x-api-key: fb41b2cb-e0b2-4343-87a3-e61c476ec184' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "My custom report",
    "activityType": "s2s",
    "dimensions": ["date", "supplySource", "browser", "country"],
    "metrics": ["bids", "requests"],
    "filters": [
        {
            "filters": [
                {
                    "key": "clicks",
                    "rel": "gt",
                    "values": [
                        "6"
                    ]
                },
                {
                    "key": "bids",
                    "rel": "gt",
                    "values": [
                        "1"
                    ]
                },
                {
                    "key": "browser",
                    "rel": "eq",
                    "values": [
                        "edge",
                        "chrome"
                    ]
                }
            ]
        }
    ],
    "timeZone": "Etc/UTC",
    "endDate": "2021-03-01",
    "startDate": "2021-02-01",
    "callbackUrl": "https://cb.myservice.com"
}'

The above command returns JSON structured like this:

{
  "id": "AXJ4vLeVzGbLE9ha4FN0qGsRDiB3BM",
  "name": "My custom report",
  "active": true,
  "reportType": 1,
  "createdOn": "2021-03-23T14:04:44.8251272+02:00",
  "modifiedOn": "2021-03-23T14:04:44.8251272+02:00",
  "createdBy": "49ad9f0f",
  "callbackUrl": "https://cb.myservice.com",
  "metrics": [
    "bids",
    "requests"
  ],
  "dimensions": [
    "date",
    "supplySource",
    "browser",
    "country"
  ],
  "filters": [
    {
      "filters": [
        {
          "key": "clicks",
          "rel": "gt",
          "values": [
            "6"
          ]
        },
        {
          "key": "bids",
          "rel": "gt",
          "values": [
            "1"
          ]
        },
        {
          "key": "browser",
          "rel": "eq",
          "values": [
            "edge",
            "chrome"
          ]
        }
      ]
    }
  ],
  "startDate": "2021-02-01",
  "endDate": "2021-03-01",
  "reportStatus": "GENERATING"
}

Example with exactDate

curl --location --request POST 'https://reports-api.yellowblue.io/reports' \
--header 'x-api-key: fb41b2cb-e0b2-4343-87a3-e61c476ec184' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Test report 1",
  "activityType": "s2s",
  "dimensions": [
    "date",
    "supplySource",
    "country"
  ],
  "metrics": [
    "bids",
    "requests"
  ],
  "filters": [
    {
      "filters": [
        {
          "key": "country",
          "rel": "eq",
          "values": [
            "US"
          ]
        }
      ]
    }
  ],
  "timeZone": "Etc/UTC",
  "exactDate": "2021-03-01"
}'

POST /reports HTTP/1.1
Host: reports-api.yellowblue.io/reports
x-api-key: fb41b2cb-e0b2-4343-87a3-e61c476ec184
Content-Type: application/json
Content-Length: 432

{
  "name": "Test report 1",
  "activityType": "s2s",
  "dimensions": [
    "date",
    "supplySource",
    "country"
  ],
  "metrics": [
    "bids",
    "requests"
  ],
  "filters": [
    {
      "filters": [
        {
          "key": "country",
          "rel": "eq",
          "values": [
            "US"
          ]
        }
      ]
    }
  ],
  "timeZone": "Etc/UTC",
  "exactDate": "2021-03-01"
}

When creating a new custom report you are able to choose your dimensions (col names), metrics and filters. This allows you to take full advantage of numerous metrics that are already calculated by us for the desired activity type. Further details on these in the validation sections.

Data Parameters

Parameter Type Required Validations
name String Yes Name validation
activityType String Yes Activity validation
dimensions String Array Yes Dimensions validation
metrics String Array Yes Metrics validation
filters Object Array Yes Filters validation
timeZone String Yes TimeZone validation
exactDate String Yes* Date validation
startDate String Yes* Date validation
endDate String Yes* Date validation
callbackUrl String No URL validation

*You can send either exactDate or startDate AND endDate

Callback and Polling

Callback

By adding the callbackUrl field to the create report request will enable us to notify you once the report generation is complete

The callback will be sent as a POST request

Example: Callback request body

{
  "reportId": "UxeoXh49vqvQ5qWEdDNvhDnpiPMxFm",
  "reportStatus": "DONE",
  "totalRows": 52865
}

Polling

If you do not choose to add the callbackUrl field as mentioned above you will need to use polling in order to check if the report is ready for retrieval. In order to poll for the data you can make a request for the report data as explained HERE

If the report is ready you will receive the data as explained below. If the data is not yet ready you will receive a response with the status field

Example: Polling response, data not yet ready

{
  "status": "RUNNING"
}

Retrieve report data

curl --location --request GET 'https://reports-api.yellowblue.io/reports/UxeoXh49vqvQ5qWEdDNvhDnpiPMxFm' \
--header 'x-api-key: fb41b2cb-e0b2-4343-87a3-e61c476ec184'

GET /reports/UxeoXh49vqvQ5qWEdDNvhDnpiPMxFm HTTP/1.1
Host: reports-api.yellowblue.io
x-api-key: fb41b2cb-e0b2-4343-87a3-e61c476ec184

Response

{
  "data": [
    {
      "bids": 1214735,
      "country": "US",
      "date": "2020-12-15",
      "supplySource": "s2s",
      "requests": 4234761,
      "browser": "chrome"
    },
    {
      "bids": 1116120,
      "country": "US",
      "date": "2020-12-11",
      "supplySource": "s2s",
      "requests": 4060829,
      "browser": "chrome"
    },
    {
      "bids": 932853,
      "country": "US",
      "date": "2020-12-26",
      "supplySource": "s2s",
      "requests": 3582549,
      "browser": "chrome"
    }
  ],
  "nextPageToken": "BEUTVSRUPAAQAAASAUIIBAEAAUNAICAFCACSB77777777777757SUAA=",
  "totalRows": 52865
}

Retrieve the table data that has been generated by the create-report request.

The results will be returned by pages. A page is a subset of the total number of rows. If your results are more than one page of data, the response will contain a nextPageToken property.

To retrieve the next page of results, make another call and include the token value as a URL query parameter named pageToken.

All reports are limited to 500,000 rows. If you need to increase this limit, please contact your account manager.

If the generated report has zero rows, upon request you will receive the following response:

{ "status": "DONE", "message": "Report has zero rows" }

HTTP Request

GET /reports/:reportId

Query Parameters

Parameter Default Type Description
pageToken Empty String string Retrieve the next page of results

HTTP Request with next page token

GET /reports/:reportId?pageToken=BEUTVSRUPAAQAAASAUIIBAEAAUNAICAFCACSB77777777777757SUAA=

Retrieve report configuration

GET /reports/config/C3RPCIOGSDpqTEtaS4xR3OWfj6ORVk HTTP/1.1
Host: reports-api.yellowblue.io
x-api-key: fb41b2cb-e0b2-4343-87a3-e61c476ec184

curl --location --request GET 'https://reports-api.yellowblue.com/reports/config/C3RPCIOGSDpqTEtaS4xR3OWfj6ORVk' \
--header 'x-api-key: fb41b2cb-e0b2-4343-87a3-e61c476ec184

Example: Report configuration response

{
  "id": "C3RPCIOGSDpqTEtaS4xR3OWfj6ORVk",
  "name": "My custom report",
  "active": true,
  "createdOn": "2021-03-23T14:15:58.0783362+02:00",
  "modifiedOn": "2021-03-23T14:15:58.0783362+02:00",
  "callbackUrl": "https://cb.myservice.com",
  "metrics": [
    "bids",
    "requests"
  ],
  "dimensions": [
    "date",
    "supplySource",
    "browser",
    "country"
  ],
  "filters": [
    {
      "filters": [
        {
          "key": "clicks",
          "rel": "gt",
          "values": [
            "6"
          ]
        },
        {
          "key": "bids",
          "rel": "gt",
          "values": [
            "1"
          ]
        },
        {
          "key": "browser",
          "rel": "eq",
          "values": [
            "edge",
            "chrome"
          ]
        }
      ]
    }
  ],
  "startDate": "2021-02-01",
  "endDate": "2021-03-01",
  "lastQueried": "2021-03-23T14:16:29+03:00",
  "reportStatus": "DONE"
}

Retrieve the report configuration from the database by the reportId.

HTTP Request

GET /reports/config/:reportId HTTP/1.1

Retrieve all report configurations

curl --location --request GET 'https://reports-api.yellowblue.io/reports/config' \
--header 'x-api-key: fb41b2cb-e0b2-4343-87a3-e61c476ec184'

GET /reports/config HTTP/1.1
Host: reports-api.yellowblue.io
x-api-key: fb41b2cb-e0b2-4343-87a3-e61c476ec184

Response

[
  {
    "id": "A9HhVDqbseH27fPXyqiqf5erGN7p2L",
    "name": "Test report",
    "active": true,
    "reportType": 1,
    "createdOn": "2021-03-15T13:33:39.6456637+02:00",
    "modifiedOn": "2021-03-15T13:33:39.6456637+02:00",
    "callbackUrl": "https://cb.myservice.com",
    "metrics": [
      "bids",
      "requests"
    ],
    "dimensions": [
      "date",
      "supplySource",
      "browser",
      "country"
    ],
    "filters": [
      {
        "filters": [
          {
            "key": "country",
            "rel": "eq",
            "values": [
              "US"
            ]
          }
        ]
      }
    ],
    "startDate": "2020-02-01",
    "endDate": "2021-03-01",
    "lastQueried": "2021-03-15T13:33:29+03:00",
    "reportStatus": "DONE"
  },
  {
    "id": "kmgDs0nG4Kdr9Ew3pIwLO4NNLLo3aO",
    "name": "Test report",
    "active": true,
    "reportType": 1,
    "createdOn": "2021-03-15T13:34:51.991555+02:00",
    "modifiedOn": "2021-03-15T13:34:51.991555+02:00",
    "callbackUrl": "https://cb.myservice.com",
    "metrics": [
      "bids",
      "requests"
    ],
    "dimensions": [
      "date",
      "supplySource",
      "browser",
      "country"
    ],
    "filters": [
      {
        "filters": [
          {
            "key": "country",
            "rel": "eq",
            "values": [
              "US"
            ]
          }
        ]
      }
    ],
    "startDate": "2020-02-01",
    "endDate": "2021-03-01",
    "lastQueried": "2021-03-15T13:34:29+03:00",
    "reportStatus": "DONE"
  }
]

Retrieve a list of all the report configurations associated with your given API key.

HTTP Request

GET /reports/config

Reports API - Validations

Validation rules for our various APIs.

Name validation

Activity validation

Must be one of the following values:

Dimensions validation

A list of strings of the desired dimensions (column names) from the below table.

You are required to send dimensions, and this list cannot be left empty.

Name Type S2S Activity SDK Activity HB Activity TAM Activity PBS Activity EC Activity VAST Activity
adUnit string Yes Yes Yes Yes Yes Yes Yes
advertiserDomain string Yes No Yes Yes Yes Yes Yes
browser string Yes Yes Yes Yes Yes Yes Yes
demandPartner string No Yes No No No Yes No
country string Yes Yes Yes Yes Yes Yes Yes
date string Yes Yes Yes Yes Yes Yes Yes
deviceType string Yes Yes Yes Yes Yes Yes Yes
domain string Yes Yes Yes Yes Yes Yes Yes
env string Yes Yes Yes Yes Yes Yes Yes
hour integer Yes Yes Yes Yes Yes Yes Yes
orgName string Yes Yes Yes Yes Yes Yes Yes
placement (gpid/tagid) string Yes No Yes Yes Yes No Yes
gpId string Yes No Yes Yes Yes No Yes
tagId string Yes No Yes Yes Yes No Yes
os string Yes Yes Yes Yes Yes Yes Yes
state string Yes Yes Yes Yes Yes Yes Yes
supplySource string Yes No Yes Yes Yes No Yes
integrationType string No Yes No No No No No
playerName string No Yes No No No No No
mediaType string Yes Yes Yes Yes Yes Yes Yes
placementId string Yes No Yes Yes Yes Yes Yes
title (App Name) string Yes No No Yes Yes No Yes
bundleId (InApp Only) string Yes No No Yes Yes No Yes
adSize (InApp Only) string Yes No No Yes Yes No Yes

Metrics validation

List of strings containing values from the below table.

If you do not wish to add metrics, you are required to send an empty list as the value of the metrics field: {"metrics": []}

Key S2S Activity SDK Activity HB Activity TAM Activity PBS Activity EC Activity VAST Activity
bidRate Yes Yes Yes Yes Yes Yes Yes
bids Yes Yes Yes Yes Yes Yes Yes
clicks Yes Yes Yes Yes Yes No Yes
completionRate Yes Yes Yes Yes Yes No Yes
completions Yes Yes Yes Yes Yes No Yes
cpm Yes Yes Yes Yes Yes Yes Yes
ecpm Yes Yes Yes Yes Yes Yes Yes
fillRate Yes Yes Yes Yes Yes Yes Yes
impressions Yes Yes Yes Yes Yes Yes Yes
playerLoads No Yes No No No No No
requests Yes Yes Yes Yes Yes Yes Yes
revenue Yes Yes Yes Yes Yes Yes Yes
start Yes Yes Yes Yes Yes No Yes
successRate Yes Yes Yes Yes Yes Yes Yes
wins No Yes No No No Yes No
net No Yes No No No Yes Yes
billingRevenue No No No No No Yes No
cost No No No No No Yes Yes

Filters validation

By adding filters, you are able to select only those records that match certain criteria.

The filters field is made up of a list of objects that each can contain another list of objects.

It is important to note that all filter objects within a filter list have the relationship of OR between them, and all filter objects within the parent filter-list have the AND relationship between them

This value is a JSON object in the format as can be seen on the right

Example 1

{
  "filters": [
    {
      "filters": [
        {
          "key": "country",
          "rel": "eq",
          "values": [
            "US"
          ]
        },
        {
          "key": "bids",
          "rel": "gt",
          "values": [
            "1"
          ]
        }
      ]
    }
  ]
}

Example 2

{
  "filters": [
    {
      "filters": [
        {
          "key": "bids",
          "rel": "gt",
          "values": [
            "1"
          ]
        }
      ]
    },
    {
      "filters": [
        {
          "key": "ecpm",
          "rel": "gt",
          "values": [
            "1"
          ]
        }
      ]
    }
  ]
}

If you do not wish to include any filters, you are required to send an empty list as the filters value as follows:

{ "filters": [] }

Key S2S Activity SDK Activity HB Activity TAM Activity PBS Activity EC Activity VAST Activity Relation Values
bids Yes Yes Yes Yes Yes Yes Yes eq/gt/lt a number
browser Yes Yes Yes Yes Yes Yes Yes eq/neq comma separated values of: chrome, ie, firefox, safari, facebook, amazon, android browser, avant, chromium, comodo dragon, edge, icedragon, iceweasel, iemobile, iron, maxthon, midori, miui browser, mobile safari, mozilla, netscape, opera, opera mini, rockmelt, seamonkey, silk, ucbrowser, vivaldi,webkit, yandex
clicks Yes Yes Yes Yes Yes No Yes eq/gt/lt a number
completionRate Yes Yes Yes Yes Yes No Yes eq/gt/lt a number
completions Yes Yes Yes Yes Yes No Yes eq/gt/lt a number
country Yes Yes Yes Yes Yes Yes Yes eq/neq country codes
cpm Yes Yes Yes Yes Yes Yes Yes eq/gt/lt a number
ecpm Yes Yes Yes Yes Yes Yes Yes eq/gt/lt a number
env Yes Yes Yes Yes Yes Yes Yes eq comma separated values of: desktop, mobile_app, mobile_web, ctv, connected_tv
fillRate Yes Yes Yes Yes Yes Yes Yes eq/gt/lt a number
hour Yes Yes Yes Yes Yes Yes Yes eq/neq comma separated hours. Eg: 1, 13, 21, 23
impressions Yes Yes Yes Yes Yes Yes Yes eq/gt/lt a number
os Yes Yes Yes Yes Yes Yes Yes eq/neq comma separated values of: macos, windows phone, windows, linux, chromium, mac os x, other, ubuntu, android
playerLoads No Yes No No No No No eq/gt/lt a number
requests Yes Yes Yes Yes Yes Yes Yes eq/gt/lt a number
revenue Yes Yes Yes Yes Yes Yes Yes eq/gt/lt a number
start Yes Yes Yes Yes Yes No Yes eq/gt/lt a number
successRate Yes Yes Yes Yes Yes Yes Yes eq/gt/lt a number
wins No Yes No No No No No eq/gt/lt a number
mediaType Yes Yes Yes Yes Yes Yes Yes eq/neq comma separated values of: video, banner

Timezone validation

Must be one of the following timezones

Date validation

URL validation

Reports API - Errors

The Reports API uses the following error codes:

Error codes

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The requested is hidden for administrators only.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a report with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- You are making too many requests! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Response Body

Some errors will be returned with an informative JSON response body in the following format:

{
  "message": "",
  "error": ""
}

RTB S2S - Integration

This guide provides the tools you need to contribute to and engage with Rise RTB Seller

RTB Endpoints

Web:

https://s2s.yellowblue.io/rtb?publisher_id={{publisher_id}}

InApp:

https://inapp-rtb.yellowblue.io/rtb?publisher_id={{publisher_id}}

CTV:

https://ctv-rtb.yellowblue.io/rtb?publisher_id={{publisher_id}}

Placement-id (Optional)

Web:

https://s2s.yellowblue.io/rtb?publisher_id={{publisher_id}}&placement_id={{placement_id}}

InApp:

https://inapp-rtb.yellowblue.io/rtb?publisher_id={{publisher_id}}&placement_id={{placement_id}}

CTV:

https://ctv-rtb.yellowblue.io/rtb?publisher_id={{publisher_id}}&placement_id={{placement_id}}

https://cs-server-s2s.yellowblue.io/sync-iframe?gdpr={{gdpr}}&gdpr_consent={{gdpr_consent}}&us_privacy={{us_privacy}}&gpp={{gpp}}&gpp_sid={{gpp_sid}}&redirect={{redirect_url}}

The RiseID macro needed to implement in the redirect is: {partnerId}

Authentication

The publisher_id query parameter will be provided to you by your Rise account manager.

The request header should look like this

POST /rtb HTTP/1.1
Host: s2s.yellowblue.io
publisher_id: 5dg6876d8h3h87hd
Content-Type: application/json

Bid Request

The bid object that needs to be sent in body request

{
  "imp": [
    {
      "video": {
        "mimes": [
          "string"
        ],
        "minduration": 0,
        "maxduration": 0,
        "protocols": [
          0
        ],
        "w": 0,
        "h": 0,
        "placement": 0,
        "skip": 0,
        "playbackmethod": [
          0
        ],
        "pos": 0,
        "api": [
          0
        ]
      },
      "bidfloor": 0,
      "bidfloorcur": "string",
      "secure": 0,
      "exp": 0
    }
  ],
  "site": {
    "domain": "string",
    "page": "string",
    "publisher": {
      "id": "string",
      "name": "string"
    },
    "content": {
      "url": "string",
      "title": "string"
    }
  },
  "device": {
    "ua": "string",
    "geo": {
      "lat": 0,
      "lon": 0,
      "type": 0,
      "ipservice": 0,
      "country": "string",
      "region": "string",
      "metro": "string",
      "city": "string",
      "zip": "string"
    },
    "ip": "string",
    "dnt": 0,
    "devicetype": 0,
    "make": "string",
    "model": "string",
    "os": "string",
    "osv": "string",
    "carrier": "string",
    "connectiontype": 0
  },
  "user": {
    "id": "string",
    "buyeruid": "string"
  },
  "at": 0,
  "tmax": 0,
  "wseat": [
    "string"
  ],
  "bcat": [
    "string"
  ],
  "source": {
    "pchain": "string",
    "ext": {
      "schain": {
        "ver": "string",
        "complete": 0,
        "nodes": [
          {
            "asi": "string",
            "sid": "string",
            "hp": 0,
            "rid": "string",
            "name": "string",
            "domain": "string"
          }
        ]
      }
    }
  }
}

Bid Response

{
  "cur": "cur",
  "id": "id",
  "seatbid": [
    {
      "seat": "seat",
      "bid": [
        {
          "adid": "adid",
          "crid": "crid",
          "adomain": [
            "adomain",
            "adomain"
          ],
          "price": 0.8008281904610115,
          "id": "id",
          "adm": "adm",
          "impid": "impid",
          "cid": "cid"
        },
        {
          "adid": "adid",
          "crid": "crid",
          "adomain": [
            "adomain",
            "adomain"
          ],
          "price": 0.8008281904610115,
          "id": "id",
          "adm": "adm",
          "impid": "impid",
          "cid": "cid"
        }
      ]
    },
    {
      "seat": "seat",
      "bid": [
        {
          "adid": "adid",
          "crid": "crid",
          "adomain": [
            "adomain",
            "adomain"
          ],
          "price": 0.8008281904610115,
          "id": "id",
          "adm": "adm",
          "impid": "impid",
          "cid": "cid"
        },
        {
          "adid": "adid",
          "crid": "crid",
          "adomain": [
            "adomain",
            "adomain"
          ],
          "price": 0.8008281904610115,
          "id": "id",
          "adm": "adm",
          "impid": "impid",
          "cid": "cid"
        }
      ]
    }
  ]
}
http shell