Advertiser

Status: Running
Planned Service Interruptions: None

Resource Overview

Resource Description Methods
advertisers advertisers commands are used to view, add, update, and delete Advertisers GET, POST, PUT, DELETE
  cards An advertisers sub-resource. cards commands are used to to view, add, and update Advertiser credit cards GET, POST, PUT
  charges An advertisers sub-resource. charges commands are used to add charges to an Advertiser's credit card POST
  subscriptions An advertisers sub-resource. subscriptions commands are used to to view, add, and update the method by which an Advertiser is charged via recurring payments POST
  balance An advertisers sub-resource. balance commands are used to view an Advertiser's remaining balance GET
offers offers commands are used to view, add, and update Offers GET, POST, PUT
datatransfers datatransfers commands are used to view, add, update and delete Data Transfers GET, POST, PUT, DELETE
autoresponders autoresponders commands are used to view, add, and update Autoresponders GET, POST, PUT
reports reports commands are used to view statistics for an Offer or group of Offers GET
track track commands are used to add tracking records POST


advertisers

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

Fields Data type/Format Description POST PUT
id number A system generated ID
name string Name of the Advertiser 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/advertisers/

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

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

{ 
    "id": 49,  
    "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/advertisers/49

{ 
    "status_id": 2 
}

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

cards

An advertisers sub-resource. cards commands are used to view (GET), add (POST), and update (PUT) Advertiser credit cards.

Fields Data type/Format Description POST PUT
number number The card number of the Client User's credit card Required
exp_month number The expiration month of the Client User's credit card Required Modifiable
exp_year number The expiration year of the Client User's credit card Required Modifiable
cvc number The CVC number of the Client User's credit card Required Modifiable
name string The Client User's name as written on the Credit Card Required Modifiable
address_line1 string The Client User's Address associated with the Credit Card Required Modifiable
address_line2 string The Client User's Address associated with the Credit Card Optional Modifiable
address_zip number The Client User's Postal Code as associated with the Credit Card address Optional Modifiable
address_state string The Client User's State as associated with the Credit Card address Optional Modifiable
address_country string The Client User's Country as associated with the Credit Card address Optional Modifiable
default boolean Designates the card that will be charged when charge criteria is met for subscriptions. Optional Modifiable

Example POST request: https://oiapi.com/v1/advertisers/45678/cards/

{
  "number":"0000111122223333",
  "exp_month":12,
  "exp_year":"16",
  "cvc":"111",
  "name":"John Tester",
  "address_line1":"123 Elm Street",
  "address_line2":"Apt 2",
  "address_city":"Rochester",
  "address_zip":"14605",
  "address_state":"NY",
  "address_country":"US",
  "default":true
}

Example response:

{
  "status":"Success",
  "message":"Card Created",
  "card_id":"123934354353432"
}

Example GET request: https://oiapi.com/v1/advertisers/45678/cards/

[
  {
    "card_id":"0000111122223333",
    "name":"John Tester",
    "last4":"1234",
    "brand":"Visa",
    "exp_month":12,
    "exp_year":16,
    "address_line1":"123 Elm Street",
    "address_line2":"Apt 2",
    "address_city":"Rochester",
    "address_state":"NY",
    "address_country":"US",
    "default":true
  },
  {
    "card_id":"34046394524423",
    "name":"John Tester",
    "last4":"1234",
    "brand":"Amex",
    "exp_month":12,
    "exp_year":16,
    "address_line1":"123 Elm Street",
    "address_line2":"Apt 2",
    "address_city":"Rochester",
    "address_state":"NY",
    "address_country":"US",
    "default":false
  }
]

Example response:

{
  "status":"Success",
  "message":"Card Created",
  "card_id":"123934354353432"
}

charges

An advertisers sub-resource. charges commands are used make a one-time charge to an Advertiser credit card. POST is the only available method.

Fields Data type/Format Description POST PUT
card_id number the card ID that is generated for a card when using the cards resource. Required
amount number The amount of US Dollars to charge the Advertiser's credit card. Required

Example POST request: https://oiapi.com/v1/advertisers/45678/charges/

{
  "card_id":"123934354353432",
  "amount":100
}

Example Success response:

{
  "status":"Charge Success",
  "message":"Credit Card Charged",
  "charge_id":"1234"
}

Example Failed response:

{
  "status":"Charge Failed",
  "message":"The card has expired.",
  "charge_id":"1234"
}

subscriptions

An advertisers sub-resource. subscriptions commands are used to view (GET) and update (POST) the method by which an Advertiser is charged via recurring payments.

Fields Data type/Format Description POST PUT
subscription_id number 427 = Automatic Pre-pay, 428 = Automatic Post-pay. Automatic Pre-pay subscription will charge a users default card for the specified payment_amount when the balance is <= 0. Automatic Post-pay will charge a users default card periodically for Leads their Offer(s) generate. Required Modifiable
payment_amount number The amount of US Dollars to charge the Advertiser's credit card. Required for subscription_id = 427 Modifiable

Example POST request: https://oiapi.com/v1/advertisers/45678/subscriptions/

{
  "subscription_id":428,
  "payment_amount":100.0
}

This command would set up an automatic recurring payment for $100.


Example GET request: https://oiapi.com/v1/advertisers/45678/subscriptions/

{
  "subscription_id":427,
  "payment_amount":100.0
}

balance

An advertisers sub-resource. balance commands are used to view (GET) an Advertiser's remaining balance.

Example GET request: https://oiapi.com/v1/advertisers/45678/balance/

{
  "balance":12211.45
}


offers

offers commands are used to view (GET), add (POST) and update (PUT) Offers.

Fields Data type/Format Description POST PUT
advertiser_id number ID of the parent Advertiser Required Modifiable
id number A system generated ID
name string Name of the Offer 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 (standard) = add to Approval Queue, 2 = off, 1 (system only) = live Required Modifiable
category_id number Category of the business. See Lookup Table. Optional Modifiable
headline string Part of the Offer Creative. Main call to action for the good/service. Required Modifiable
body string Part of the Offer Creative. Secondary call to action for the good/service. Required Modifiable
image1 url 120x60px .png, .jpeg, or .gif image. Example: https://www.mydomain/images/offer_images/cats120.png

After initial POST, images will be transferred to our CDN. The URL will then look something like this: https://d1e25ii2es31lb.cloudfront.net/1421897851163-91bd185d9774a8eae292f9e19de25823.gif 		Required Modifiable
image2 url 88x31px .png, .jpeg, or .gif image. Example: https://www.mydomain/images/offer_images/cats88.png

After initial POST, images will be transferred to our CDN. The URL will then look something like this: https://d1e25ii2es31lb.cloudfront.net/1421897851163-91bd185d9774a8eae292f9e19de25832.gif 		Optional Modifiable
cpl_price number Cost Per Lead for the Offer Required Modifiable
cap_status_id number System generated. 1101 = Not Capped, 1102 = Capped
global_cap number Total Lead allotment for an Offer Required Modifiable
monthly_cap number Monthly Lead allotment for an Offer Optional Modifiable
daily_cap number Daily Lead allotment for an Offer Optional Modifiable
data_points list List of consumer Data Points being collected for an Offer. Email (EM) is a required Data Point. See Lookup Table. Required Modifiable
targeting parent field Optional Modifiable
comment string Comment for Offer approval Optional Modifiable

targeting

Fields Data type/Format Description POST PUT
gender string sub-field of targeting m = male, f = female Optional Modifiable
min_age number sub-field of targeting Minimum age for a Lead Optional Modifiable
max_age number sub-field of targeting Maximum age for a Lead Optional Modifiable
zip sub-field of targeting
Fields Data type/Format Description POST PUT
zip_codes list sub-field of zip Postal Codes (US or Canada) Optional Modifiable
include boolean sub-field of zip true = show Offer to zip_codes list
false = do not show Offer to zip_codes list		 Required Modifiable
Optional Modifiable
state sub-field of targeting
Fields Data type/Format Description POST PUT
states list sub-field of state State (2-letter ANSI format) or Province (2-letter format) codes. Optional Modifiable
include boolean sub-field of state true = show Offer to states list
false = do not show Offer to states list		 Required Modifiable
Optional Modifiable
country sub-field of targeting
Fields Data type/Format Description POST PUT
countries list sub-field of country Country codes. 3-letter ISO format. Optional Modifiable
include boolean sub-field of country true = show Offer to countries list
false = do not show Offer to countries list		 Required Modifiable
Optional Modifiable
zip_radius number sub-field of targeting For use with zip_codes. When in use, Offer will appear to all Users within defined mile radius for all zip codes listed. Optional Modifiable
third_party list sub-field of targeting OI provided parameter names and values. This is a very custom field. Optional Modifiable

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

{ 
    "advertiser_id": 123, 
    "name": "Special Product 1",
    "category_id": 1010,
    "status_id": 9,
    "headline": "Buy our product today",
    "body": "Try for FREE for a limited time only. This is your one-and-only chance!",
    "cpl_price": 1.0,
    "global_cap": 1000, 
    "monthly_cap": 300, 
    "daily_cap": 10, 
    "image1": "http://www.opt-intelligence.com/images/cats120.png", 
    "image2": "http://www.opt-intelligence.com/images/cats88.png",
    "data_points": [
        "EM", "FN"
    ], 
    "targeting": {
        "min_age": 18, 
        "max_age": 45, 
        "zip": {
            "include": true, 
            "zip_codes": ["14226","10009","10023","11211"]
        }, 
        "gender": "m", 
        "country": {
            "include": true, 
            "countries": ["USA"]
        },
        "third_party": { }
    },
    "comment":"Hello there"
}

Example GET response: https://oiapi.com/v1/offers/45678/

{ 
    "advertiser_id": 123, 
    "id": "45678",
    "name": "Special Product 1",
    "status_id": "9",
    "category_id": 1010,
    "create_date": "2014-11-17T12:30:30Z", 
    "modify_date": "2014-11-17T14:56:10Z",  
    "headline": "Buy our product today",
    "body": "Try for FREE for a limited time only. This is your one-and-only chance!",
    "cpl_price": 1.0,
    "cap_status_id": 1101,
    "global_cap": 1000, 
    "monthly_cap": 300, 
    "daily_cap": 10, 
    "image1": "https://d1e25ii2es31lb.cloudfront.net/1421897851163-91bd185d9774a8eae292f9e19de25823.gif", 
    "image2": "https://d1e25ii2es31lb.cloudfront.net/1421897851163-91bd185d9774a8eae292f9e19de25832.gif", 
    "data_points": [
        "EM", "FN"
    ], 
    "targeting": {
        "min_age": 18, 
        "max_age": 45, 
        "zip": {
            "include": true, 
            "zip_codes": ["14226","10009","10023","11211"]
        }, 
        "gender": "m", 
        "country": {
            "include": true, 
            "countries": ["USA"]
        },
        "third_party": { }
    },
    "comment":"Hello there"
}

Example PUT request: https://oiapi.com/v1/offers/45678/

{ 
    "headline": "Last chance to buy our product",
    "cpl_price": 2.0
}

The examples above create an Offer named "Special Product 1". The Cost Per Lead for the Offer is $1.00 and it is targeted to a list of 4 zip codes. Later on, in the PUT request, we modify the headline field to "Last chance to buy our product", and increase the cpl_price to $2.00, thus modifying the Offer Creative and increasing the Cost Per Lead.



datatransfers

datatransfers commands are used to view (GET), add (POST), update (PUT) and DELETE Data Transfers. All Data Transfers have a one-to-one relationship with an Offer. Therefore all datatransfers commands include an Offer ID (https://oiapi.com/v1/offers/45678/datatransfers/).

Fields Data type/Format Description POST PUT
id number A system generated ID
name string Name of the Data Transfer Required Modifiable
type string http = standard method for transfer of Leads. Requires dt_info field. Required Modifiable
status_id number 1 (default) = on, 2 = off Optional 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
dt_info parent field
Fields Data type/Format Description POST PUT
base_url string Base URL for a standard HTTP or HTTPS form POST Required Modifiable
method string Required Modifiable
Required for type = html Modifiable
data_fields list List of field names and field values to pass in Lead POST. Field names can be created by you. Field values can be static or dynamic and unique to each Lead. A list of dynamic field values tags can be found here. Required Modifiable

Example POST request: https://oiapi.com/v1/offers/45678/datatransfers/

{
    "name": "DT for Special Product 1",
    "status_id": 1,
    "type": "http",
    "offer_id": 45678,
    "dt_info": {
        "base_url": "http://www.someclientbaseurl.com",
        "method": "POST"
    },
    "data_fields": [
        {
            "email": "#{EM}"
        },
        {
            "first_name": "#{FN}"
        },
        {
            "last_name": "#{LN}"
        },
        {
            "zip": "#{PO}"
        },
        {
            "gender": "#{G}"
        }
    ]
}


autoresponders

autoresponders commands are used to view (GET), add (POST) and update (PUT) Autoresponders. All Autoresponders have a one-to-one relationship with an Offer. Therefore all autoresponders commands include an Offer ID (https://oiapi.com/v1/offers/45678/autoresponders/).

Fields Data type/Format Description POST PUT
id number A system generated ID
status_id number 1 = on, 2 = off Required Modifiable
subject string The subject line of an Autoresponder email Required Modifiable
from_name string The from name of an Autoresponder email Required Modifiable
body_html string HTML email body Required Modifiable
body_text string Text email body Optional Modifiable

Example POST request: https://oiapi.com/v1/offers/45678/autoresponders/

{ 
    "status_id": 1,
    "subject": "Here's a good subject line",
    "from_name": "Our Company",
    "body_html": "some html here",
    "body_text": "some text here"
}

Example GET response: https://oiapi.com/v1/offers/45678/autoresponders/

{ 
    "id": 163,  
    "status_id": 1,
    "subject": "Here's a good subject line",  
    "from_name": "Our Company",
    "body_html": "some html here",
    "body_text": "some text here"
}

Example PUT request: https://oiapi.com/v1/offers/45678/autoresponders/163

{ 
    "from_name": "Confirmation"
}

The examples above create an Autoresponder for Offer ID 45678 with the Subject Line "Here's a good subject line". Later on, in the PUT request, we modify the from_name field to "Confirmation".



reports

reports/advertisers/ commands are used to view (GET) statistics for an Offer or group of Offers.

Stat Stat type Description
ADV Identifier Advertiser Name
ADV_ID Identifier Advertiser ID
OFFER Identifier Offer Name
OFFER_ID Identifier Offer ID
TOTAL_COST Sum Total cost of Leads
OPT_INS Sum Total number of Leads before Validation
VALID_OPT_INS Sum Total number of Leads after Validation
AVG_CPL Ratio TOTAL_COST/VALID_OPT_INS
EMAIL_SENT Sum Total Autoresponder emails sent
DELIVERED Sum Total Autoresponder emails delivered
OPENS Sum Total Autoresponder emails opened
CLICKS Sum Total Autoresponder email clicks
OPN_DLVRD Ratio OPENS/DELIVERED
CLK_OPN Ratio CLICKS/OPENS

Summary mode

Calling reports/advertisers/ 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/advertisers/

{
    "status": "ok", 
    "data": {
        "today": [
            {
                "TOTAL_COST": 200,
                "OPT_INS": 440, 
                "VALID_OPT_INS": 400, 
                "AVG_CPL": 0.5,
                "EMAIL_SENT": 440, 
                "DELIVERED": 410, 
                "OPENS": 220, 
                "CLICKS": 85, 
                "OPN_DLVRD": 0.54, 
                "CLK_DLVRD": 0.21
            }
        ], 
        "yesterday": [
            {
                "TOTAL_COST": 250,
                "OPT_INS": 600, 
                "VALID_OPT_INS": 500, 
                "AVG_CPL": 0.5,
                "EMAIL_SENT": 600, 
                "DELIVERED": 520, 
                "OPENS": 250, 
                "CLICKS": 105, 
                "OPN_DLVRD": 0.48, 
                "CLK_DLVRD": 0.20
            }
        ], 
        "mtd": [
            {
                "TOTAL_COST": 900,
                "OPT_INS": 2000, 
                "VALID_OPT_INS": 1800, 
                "AVG_CPL": 0.5,
                "EMAIL_SENT": 2000, 
                "DELIVERED": 1900, 
                "OPENS": 1021, 
                "CLICKS": 430, 
                "OPN_DLVRD": 0.54, 
                "CLK_DLVRD": 0.23
            }
        ]
    }
}

Custom mode

Calling reports/advertisers/ 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/advertisers/?start=2014-11-01

{
    "status": "ok", 
    "data": {
        "custom": [
            {
                "TOTAL_COST": 900,
                "OPT_INS": 2000, 
                "VALID_OPT_INS": 1800, 
                "AVG_CPL": 0.5,
                "EMAIL_SENT": 2000, 
                "DELIVERED": 1900, 
                "OPENS": 1021, 
                "CLICKS": 430, 
                "OPN_DLVRD": 0.54, 
                "CLK_DLVRD": 0.23
            }
        ]
    }
}

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 Offer or by Advertiser. An additional field, ids, must also be present, representing the Offer(s) or Advertiser(s) to filter by.

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

{
    "status": "ok", 
    "data": {
        "custom": [
            {
                "TOTAL_COST": 450,
                "OPT_INS": 1000, 
                "VALID_OPT_INS": 900, 
                "AVG_CPL": 0.5,
                "EMAIL_SENT": 900, 
                "DELIVERED": 800, 
                "OPENS": 400, 
                "CLICKS": 200, 
                "OPN_DLVRD": 0.50, 
                "CLK_DLVRD": 0.25
            }
        ]
    }
}

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

{
    "status": "ok", 
    "data": {
        "custom": [
            {
                "TOTAL_COST": 400,
                "OPT_INS": 900, 
                "VALID_OPT_INS": 800, 
                "AVG_CPL": 0.5,
                "EMAIL_SENT": 900, 
                "DELIVERED": 450, 
                "OPENS": 300, 
                "CLICKS": 150, 
                "OPN_DLVRD": 0.6666, 
                "CLK_DLVRD": 0.3333
            }
        ]
    }
}

Limiting Fields

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

https://oiapi.com/v1/reports/advertisers/?start=2014-11-01&end=2014-11-05&fields=OPENS,CLICKS

{
    "status": "ok", 
    "data": {
        "custom": [
            {
                "OPENS": 1021, 
                "CLICKS": 430
            }
        ]
    }
}

Grouping

The groupby parameter enables a stats roll-up by Offer or by Advertiser.

https://oiapi.com/v1/reports/advertisers/?start=2014-11-01&end=2014-11-05&id-type=advertiser&ids=123&fields=OPENS,CLICKS&groupby=offer

{
    "status": "ok", 
    "data": {
        "custom": [
            {
                "ADV": "Some Name", 
                "ADV_ID": 123, 
                "OFFER": "Special Offer 1",
                "OFFER_ID": "45678",
                "OPENS": 300, 
                "CLICKS": 150
            },
            {
                "ADV": "Some Name", 
                "ADV_ID": 123, 
                "OFFER": "Special Offer 2",
                "OFFER_ID": "91011",
                "OPENS": 100, 
                "CLICKS": 50
            }
        ]
    }
}


track

track commands are used to add (POST) one or more tracking records.

Fields Data type/Format Description POST
profile_id number User profile ID Required if offer_id is not present
offer_id number ID of offer Required if profile_id is not present
opt_in_date 2017-01-01T01:10 Opt-in timestamp Required if profile_id and email are not present
email string User email Required if profile_id and opt_in_date are not present
type character i = impression, o = open, c = click, u = unknown, l = landing, 1, 2, 3, 4, 5 (1-5 are client defined)
page_id number ID of the page serving the offer
label string Custom label for the track record
url string URL generating the track record

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

{ 
	"offer_id": 2224,
	"opt_in_date": '2017-01-01T01:10'
	"type": "3",
	"page_id": 49560042,
	"email":"test@opt-intelligence.com"
	"profile_id": "2250150960",
	"label": "SUBMIT_OPTIN",
	"url": "www.testurl.com",
}

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

{ 
	"profile_id": "2250150960",
	"type": "3",
}

Example POST request with multiple enteries: https://oiapi.com/v1/track/

[{ 
	"offer_id": 2224,
	"opt_in_date": '2017-01-01T01:10'
	"type": "3",
	"page_id": 49560042,
	"email":"test@opt-intelligence.com"
	"profile_id": "2250150960",
	"label": "SUBMIT_OPTIN",
	"url": "www.testurl.com",
},
{ 
	"offer_id": 2225,
	"opt_in_date": '2017-01-01T01:10'
	"type": "4",
	"page_id": 49560042,
	"email":"test2@opt-intelligence.com"
	"profile_id": "2250150961",
	"label": "SUBMIT_OPTIN",
	"url": "www.testurl.com",
}]