API v2

Base URL: https://suite.assertiveyield.com/api/v2

Login

Used to retrieve a Token for access to your entities.

Path : /login/

Method : POST

Auth required : NO

Headers : Content-Type: application/x-www-form-urlencoded

Post Body

email={userAccountEmail}&password={userAccountPassword}

Example

curl --location --request POST 'https://suite.assertiveyield.com/api/v2/login/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'email=me@mail.com' \
--data-urlencode 'password=mypassword'

Success Response

Code : 200 OK

Content example

{
    "status": "success",
    "data": {
        "authToken": "VR6LdSgalvO9uduQfgAWecULL4QYz0SfiVQfYw2v62v",
        "userId": "p531CkFFhTZH9EbRf"
    }
}

Error Response

Condition : If 'username' and 'password' combination is wrong.

Code : 401 Unauthorized

Content example :

{
    "status": "error",
    "message": "Unauthorized"
}

Authenticated Calls

For all endpoints that require authentication you must set the userId and authToken in the header.

Example

curl -H "X-Auth-Token: VR6LdSgalvO9uduQfgAWecULL4QYz0SfiVQfYw2v62v" -H "X-User-Id: p531CkFFhTZH9EbRf" https://suite.assertiveyield.com/api/v2/report

Endpoints

Report

Retrieve a custom report based on one of the dimensions from the UI.

URL : /report

Method : POST

Headers: Content-Type: application/json

Auth required : YES

Mandatory Params :

Optional Params :

Post Body :

{
    "entities": ["ZmtgyGHidF5QWg2HD"],
    "timezone": "UTC",
    "dimensions": ["host", "client_name"],
    "metrics": ["impressions", "prebid_revenue", "pageViews", "sessions"],
    "timeGranularity": "by_hour",
    "applyRevenueBias": false,
    "dimensionsLimit": 10000,
    "filter": [
        {
            "id": "startDate",
            "value": "2019-12-01T00:00:00.000Z"
        },
        {
            "id": "endDate",
            "value": "2019-12-01T23:59:59.999Z"
        },
        {
            "id": "highest_bidder",
            "value": ["appnexus", "rubicon"]
        },
        {
            "id": "preBidWon",
            "value": [1]
        },
        {
            "id": "country",
            "value": ["United States"],
            "comparator": "not_is_one_of"
        },
        {
            "id": "client_name",
            "value": ["Chrome", "Safari"],
            "comparator": "starts_with"
        }
    ]
}

Calculated Metrics

The API only provides raw metrics. All other metrics are calculated based on these. Below are the details on how they are calculated.

Success Response (Objects)

Condition : If everything is OK and the report could be retrieved.

Code : 200 OK

Content example :

{
    "status": "success",
    "data": [
        {
          // If you ask for only one dimension _group will be a string.
          "_group": ["domain.tld", "Chrome Mobile"],
          "_date": "2019-12-01 00:00:00",
          "impressions": "241",
          "prebid_revenue": "143173528",
          "pageViews": "89",
          "sessions": "20"
        },
        {
          "_group": ["doamin.tld", "Chrome"],
          "_date": "2019-12-01 01:00:00",
          "impressions": "54",
          "prebid_revenue": "121477291",
          "pageViews": "23",
          "sessions": "12"
        },
        ...
    ]
}

Success Response (Compact)

Condition : If everything is OK and the report could be retrieved.

Code : 200 OK

Content example :

{
    "status": "success",
    "data": {
        "meta": [
            {
                "name": "_group",
                "type": "LowCardinality(String)"
            },
            {
                "name": "yield_entity_id",
                "type": "String"
            },
            {
                "name": "_date",
                "type": "DateTime"
            },
            {
                "name": "impressions",
                "type": "UInt64"
            }
        ],
        "data": [
            ["123", "the_entity_id", "2022-05-10 00:00:00", "49"],
            ["123", "the_entity_id", "2022-05-10 00:00:00", "172"]
        ],
        "statistics": {
            "elapsed": 1.23,
            "rows_read": 123
        }
    }
}

Error Response

Condition : If required data is missing.

Code : 400 BAD REQUEST

Content example :

{
    "name": ["Incomplete data supplied."]
}

Publisher

Retrieve a list of publishers and entities you have access to.

URL : /publisher

Method : GET

Headers: Content-Type: application/json

Auth required : YES

Success Response

Condition : If everything is OK and the report could be retrieved.

Code : 200 OK

Content example :

[
    {
        "id": "32duwgAeiPKjFcwhq",
        "name": "eBay",
        "organizationId": "d3sHqM2AsmBLq3w9C",
        "organizationName": "O&O",
        "entities": [
            {
                "id": "ht3nGNbqd7M8vyaaY",
                "name": "ebay.com",
                "currency": "USD"
            },
            {
                "id": "d42hvR5viHfzK2sEEL",
                "name": "ebay.de"
            }
        ]
    },
    {
        "id": "FhZgtupa3qwPgzAwB",
        "name": "eBay Classifieds",
        "organizationId": "d3sHqM2AsmBLq3w9C",
        "organizationName": "O&O",
        "entities": [
            {
                "id": "d3sHqM2AsmBLq3w9C",
                "name": "kleinanzeigen.de",
                "currency": "EUR"
            }
        ]
    }
]

Upload Mappings

Mappings allow you to submit a set of fileds to replace other fields on our reports.

URL : /upload-mappings

Method : POST

Headers: Content-Type: application/json

Auth required : YES

Mandatory Params :

Post Body :

{
    "entity": "32duwgAeiPKjFcwhq",
    "dimension": "utmSource",
    "mappings": [
        {
            "from": "from1",
            "to": "to1"
        },
        {
            "from": "from2",
            "to": "to2"
        }
    ]
}

Success Response

Condition : If everything is OK and the entity was not rate-limited.

Code : 200 OK

Content example :

{
    "message": "Uploaded 2 items",
    "ok": true
}

Error Response

Condition : If entity was rate limited.

Code : 403 FORBIDDEN

Content example :

{
    "ok": false,
    "message": "Rate limit exceeded. Try again in a minute."
}

Error Response

Condition : If data is missing/not formatted correctly.

Code : 500 ERROR

Content example :

{
    "ok": false,
    "message": "To 'undefined' is not string. from='from2'"
}

Session Report

WARNING: This is an early alpha version that should not be used in production. It has not been fully tested nor is the format final.

The session report provides revenue information in real-time about ongoing as well as ended sessions.

URL : /report/session

Method : POST

Headers: Content-Type: application/json

Auth required : YES

Mandatory Params :

You should provide a set of filters on either session_start or session_lastUpdate, or both.

Post Body :

{
    "entities": ["ZmtgyGHidF5QWg2HD"],
    "timezone": "UTC",
    "filter": [
        {
            "id": "session_start_from",
            "value": "2019-12-01T00:00:00.000Z"
        },
        {
            "id": "session_start_to",
            "value": "2019-12-01T23:59:59.999Z"
        }
    ]
}

Success Response

Condition : If everything is OK and the report could be retrieved.

Code : 200 OK

Content example :

{
    "status": "success",
    "data": [
        {
            "entityId": "ZmtgyGHidF5QWg2HD",
            "session_entryPage": "/the-url/",
            "session_utm_source": "",
            "session_utm_campaign": "",
            "video_revenue": "0",
            "session_start": "2021-11-08 15:18:25",
            "session_lastUpdate": "2021-11-08 15:18:25",
            "sessionId": "1239933369444712830",
            "host": "ebay.de",
            "session_impressionCount": "1",
            "session_pageViewCount": "1",
            "prebid_won_revenue": "402",
            "dynamicAllocation_revenue_predicted": "0",
            "direct_revenue": "0",
            "acquisition_clickId": "",
            "acquisition_cost": "0",
        },
        ...
    ]
}

Error Response

Condition : If required data is missing.

Code : 400 BAD REQUEST

Content example :

{
    "status": "error",
    "message": "Bad request! [400]",
    "details": "Timezone 'America/Torontoooo' is not valid."
}

Spent Report

WARNING: This is an early alpha version that should not be used in production. It has not been fully tested nor is the format final.

URL : /report/spent

Method : POST

Headers: Content-Type: application/json

Auth required : YES

Mandatory Params :

Optional Params :

Post Body :

{
    "entities": ["ZmtgyGHidF5QWg2HD"],
    "currency": "EUR",
    "metrics": ["spent", "clicks"],
    "timezone": "Europe/Amsterdam",
    "timeGranularity": "by_hour",
    "dimensions": ["platform", "campaign_name"],
    "filter": [
        {
            "id": "startDate",
            "value": "2021-05-01T09:00:00.000Z"
        },
        {
            "id": "endDate",
            "value": "2021-05-01T09:59:59.999Z"
        }
        {
            "id": "platform",
            "comparator": "is_one_of",
            "value": ["baidu"]
        }
    ],
    "dimensionsLimit": 500,
    "level": "ad"
}

Success Response

Condition : If everything is OK and the report could be retrieved.

Code : 200 OK

Content example :

{
    "status": "success",
    "data": [
        {
            "_date": "2022-10-18",
            "_group": ["baidu", "a-b-c"],
            "clicks": "0",
            "spent": 0
        }
    ]
}

Error Response

Condition : If required data is missing.

Code : 400 BAD REQUEST

Content example :

{
    "status": "error",
    "message": "Bad request! [400]",
    "details": "Timezone 'America/Torontoooo' is not valid."
}

Web Analytics Report

WARNING: This is an early alpha version that should not be used in production. It has not been fully tested nor is the format final.

URL : /report/web

Method : POST

Headers: Content-Type: application/json

Auth required : YES

Mandatory Params :

Optional Params :

Post Body :

{
    "entities": ["ZmtgyGHidF5QWg2HD"],
    "timezone": "UTC",
    "dimensions": ["host", "client_name"],
    "metrics": ["impressions", "prebid_revenue", "pageViews", "sessions"],
    "timeGranularity": "by_hour",
    "applyRevenueBias": false,
    "dimensionsLimit": 10000,
    "filter": [
        {
            "id": "startDate",
            "value": "2019-12-01T00:00:00.000Z"
        },
        {
            "id": "endDate",
            "value": "2019-12-01T23:59:59.999Z"
        },
        {
            "id": "highest_bidder",
            "value": ["appnexus", "rubicon"]
        },
        {
            "id": "preBidWon",
            "value": [1]
        },
        {
            "id": "country",
            "value": ["United States"],
            "comparator": "not_is_one_of"
        },
        {
            "id": "client_name",
            "value": ["Chrome", "Safari"],
            "comparator": "starts_with"
        }
    ]
}

Success Response (Objects)

Condition : If everything is OK and the report could be retrieved.

Code : 200 OK

Content example :

{
    "status": "success",
    "data": [
        {
          // If you ask for only one dimension _group will be a string.
          "_group": ["domain.tld", "Chrome Mobile"],
          "_date": "2019-12-01 00:00:00",
          "impressions": "241",
          "prebid_revenue": "143173528",
          "pageViews": "89",
          "sessions": "20"
        },
        {
          "_group": ["doamin.tld", "Chrome"],
          "_date": "2019-12-01 01:00:00",
          "impressions": "54",
          "prebid_revenue": "121477291",
          "pageViews": "23",
          "sessions": "12"
        },
        ...
    ]
}

Success Response (Compact)

Condition : If everything is OK and the report could be retrieved.

Code : 200 OK

Content example :

{
    "status": "success",
    "data": {
        "meta": [
            {
                "name": "_group",
                "type": "LowCardinality(String)"
            },
            {
                "name": "yield_entity_id",
                "type": "String"
            },
            {
                "name": "_date",
                "type": "DateTime"
            },
            {
                "name": "impressions",
                "type": "UInt64"
            }
        ],
        "data": [
            ["123", "the_entity_id", "2022-05-10 00:00:00", "49"],
            ["123", "the_entity_id", "2022-05-10 00:00:00", "172"]
        ],
        "statistics": {
            "elapsed": 1.23,
            "rows_read": 123
        }
    }
}

Error Response

Condition : If required data is missing.

Code : 400 BAD REQUEST

Content example :

Object {
    "message": "Failed to parse body - Invalid type. [{
    "code": \\"invalid_type\\",
    \\"expected\\": \\"array\\",
    \\"received\\": \\"undefined\\",
    \\"path\\": [
    \\"entities\\"
    ],
    \\"message\\": \\"Required\\"
    },
    ...
}

Rate Limits

In order to ensure high availability and performance for all publishers, rate limits apply to expensive requests.

Should the given rate limits not be enough for your use case, please reach out.

Compression

To enable compression provide the correct "Accept-Encoding" headers in the request, for example gzip.

Gzip and Deflate compression methods are supported.