Publisher

Status: Running
Planned Service Interruptions: None

Resource Overview

Resource Description Methods
publishers publishers commands are used to view, add, update and delete Publishers GET, POST, PUT, DELETE
placements placements commands are used view, add, and update Placements GET, POST, PUT
reports reports commands are used to view statistics for a Placement or group of Placements GET



publishers

publishers commands are used to view (GET), add (POST), update (PUT) and DELETE Publishers.

Fields Data type/Format Description POST PUT
id number A system generated ID
name string Name of the Publisher Required Modifiable
create_date 2014-11-17T12:30:30Z A system generated create time-stamp
modify_date 2014-11-17T14:56:10Z A system generated modify time-stamp
status_id number 1 = active, 2 = inactive Required Modifiable
category_id number Category of the business. See Lookup Table. Optional Modifiable
key string A field for a custom value Optional Modifiable

Example POST request: https://oiapi.com/v1/publishers/

{ 
    "name": "Some Name",  
    "status_id": 1,
    "category_id": 1010
}
	

Example GET response: https://oiapi.com/v1/publishers/

{ 
    "id": 59,  
    "name": "Some Name",
    "create_date": "2014-11-17T12:30:30Z", 
    "modify_date": "2014-11-17T14:56:10Z",  
    "status_id": 1, 
    "category_id": 1010,
    "key": ""
}
	

Example PUT request: https://oiapi.com/v1/publishers/59

{ 
    "status_id": 2 
}
	

The examples above create an Publisher named "Some Name" in the Retail & E-commerce category. In the final PUT request we modify the status_id to "2", thus making the Publisher inactive.




placements

placements commands are used to view (GET), add (POST), and update (PUT) Placements.

Fields Data type/Format Description POST PUT
publisher_id number ID of the parent Publisher Required Modifiable
id number A system generated ID
name string Name of the Placement Required Modifiable
create_date 2014-11-17T12:30:30Z A system generated create time-stamp
modify_date 2014-11-17T14:56:10Z A system generated modify time-stamp
status_id number 9 = add to Approval Queue, 2 = off, 1 (system only) = live Required Modifiable
category_id number Category of the business. See Lookup Table. Optional Modifiable
layout_id number ID that corresponds to a specific HTML layout as either provided to or created by Opt-Intelligence. 1 is recommended, though other options are available. Contact the OI Product Team for other options. Required Modifiable
offer_format_id number ID that corresponds to a specific HTML Offer layout as either provided to or created by Opt-Intelligence. 2607 is recommended, though other options are available. Contact the OI Product Team for other options. Required Modifiable
max_offers number The maximum number of Offers to show a User per impression. Required Modifiable
max_impressions number The maximum number of times to display Offers to a User in their lifetime. Optional Modifiable
max_impressions_time number The maximum number of times to display Offers to a User in a given time period. Optional Modifiable
time_period number Number of days for max_impressions_time. Required when max_impressions is in use Modifiable
max_impressions_offer number The maximum number of times to display unique Offers to a User in their lifetime. Optional Modifiable
max_impressions_time_offer number The maximum number of times to display unique Offers to a User in a given time period. Optional Modifiable
time_period_offer number Number of days for max_impressions_time_offer. Required when max_impressions_offer is in use Modifiable
parameter_share boolean true = enabled, which is recommended. When enabled, data-points (Email, First Name etc.) collected in one Offer will be shared with other Offers on the page. Required Modifiable
comment string Comment for Placement approval Optional Modifiable

Example POST request: https://oiapi.com/v1/placements/

{ 
    "publisher_id": 59, 
    "name": "My Website Placement 1",
    "status_id": 9,
    "category_id": 1010,
    "layout_id": 1,
    "offer_format_id": 2607,
    "max_offers": 4,
    "parameter_share": true
}
	

This command would create a Placement called My Website Placement 1. Users would only be shown Offers 2 times within a 7 day period. Once created, a success response is returned:

{
    "status": "Save Successful",
    "message": "Placement successfully saved",
    "id": 98987676
}
	

Example GET response: https://oiapi.com/v1/placements/98987676/

{ 
    "publisher_id": 59, 
    "id": "98987676",
    "name": "My Website Placement 1",
    "status_id": 9,
    "category_id": 1010,
    "create_date": "2014-11-17T12:30:30Z", 
    "modify_date": "2014-11-17T14:56:10Z",  
    "layout_id": 1,
    "offer_format_id": 2607,
    "max_offers": 4,
    "parameter_share": true
}
	

reports

reports/publishers commands are used to view (GET) statistics for a Placement or group of Placements.

Stat Stat type Description
PUB Identifier Publisher Name
PUB_ID Identifier Publisher ID
PLACEMENT Identifier Placement Name
PLACEMENT_ID Identifier Placement ID
REVENUE Sum Revenue generated
IMRPESSIONS Sum Total number of times Offers were shown
RPM Ratio Revenue per 1,000 Impressions

Summary mode

Calling reports/publishers/ straight-away will return stats in Summary mode. The stats above will be nested as a list sub-field under today, yesterday and mtd (month to date).

Example GET response: https://oiapi.com/v1/reports/publishers/

{
    "status": "ok",
    "data": {
        "today": [
            {
                "IMPRESSIONS": 300,
                "RPM": 33.33,
                "REVENUE": 10
            }
        ],
        "yesterday": [
            {
                "IMPRESSIONS": 400,
                "RPM": 50,
                "REVENUE": 20
            }
        ],
        "mtd": [
            {
                "IMPRESSIONS": 1500,
                "RPM": 60,
                "REVENUE": 90
            }
        ]
    }
}
	

Custom mode

Calling reports with an added parameter start will return stats in Custom mode. The max range for a Custom mode return is 2000 rows.

Example GET response: https://oiapi.com/v1/reports/publishers/?start=2014-11-01

{
{
    "status": "ok",
    "data": {
        "custom": [
            {
                "IMPRESSIONS": 4056,
                "RPM": 3.2,
                "REVENUE": 13.01
            }
        ]
    }
}
	

An additional parameter, end will allow for a snapshot for specific period. Both start and end dates are inclusive. Remember there is still a 2000 row limit for data returned.


Additional features

The following features can be utilized both in Summary and Custom modes.

Filtering

The id-type parameter enables stats filtering by Placement or by Publisher. An additional field, id, must also be present, representing the Placement(s) or Publishers(s) to filter by.

https://oiapi.com/v1/reports/publishers/?start=2014-11-01&end=2014-11-05&id-type=publisher&id=123

{
    "status": "ok", 
    "data": {
        "custom": [
            {
                "IMPRESSIONS": 3000,
                "RPM": 5.00,
                "REVENUE": 15.00
            }
        ]
    }
}
	

https://oiapi.com/v1/reports/advertisers/?start=2014-11-01&end=2014-11-05&id-type=placement&id=98987676

{
    "status": "ok", 
    "data": {
        "custom": [
            {
                "IMPRESSIONS": 2000,
                "RPM": 6.00,
                "REVENUE": 12.00
            }
        ]
    }
}
	

Limiting Fields

The fields parameter will limit the stats returned to only those fields listed.

The example below will show the RPM for all Placements rolled into one data set.

https://oiapi.com/v1/reports/publishers/?start=2014-11-01&end=2014-11-05&groupby=publisher&fields=rpm

{
    "status": "ok",
    "data": {
        "custom": [
            {
                "PUB_ID": 98765,
                "RPM": 7,
                "PUB": "Some Publisher Name"
            }
        ]
    }
}
	

Grouping

The groupby parameter enables a stats roll-up by Placement or by Publisher.

Changing the groupby parameter will display a data set for each Offer.

https://oiapi.com/v1/reports/publishers/?start=2014-11-01&end=2014-11-05&groupby=placement&fields=rpm

{
    "status": "ok",
    "data": {
        "custom": [
            {
                "PUB_ID": 98765,
                "PLACEMENT_ID": 87654321,
                "RPM": 10,
                "PUB": "Some Publisher Name",
                "PLACEMENT": "Some Placement Name [1]"
            },
            {
                "PUB_ID": 98765,
                "PLACEMENT_ID": 12345678,
                "RPM": 5,
                "PUB": "Some Publisher Name",
                "PLACEMENT": "Some Placement Name [2]"
            }
        ]
    }
}