Introduction
As a publisher you can use the Shiny Ads API to further automate your advertising operations.
The web-based API allows our systems to interact with your data and can be integrated into your processes and databases. Examples include:
- Integration into your accounting system
- Integration into your CRM (Customer Relationship Manager) system such as Salesforce or SugarCRM
- Creation of your own interface to manage Shiny Ads orders and or promotional codes
To start, first enable the API in the
Settings menu option, under API. This will generate a unique "token" for you to use to access the API server. Never give out your token to anyone as that will allow them to access your account through the API.
For Advanced Users
Check out the
Event Callbacks for notifications back to your server.
Orders
List Orders
https://shinyads.com/api/orders_list/
URL Variables:
token Your API token
sort One of these sorting options; advertiser, zone, amount, date_date (optional)
show One of these filtering options; rejected, approved, all, requests, unapproved (optional)
date_start The start date
date_end The end date
Output:
A list of Order objects.
Get Order
https://shinyads.com/api/orders_get/
URL Variables:
token Your API token
id The ID of the order to return
Output:
An Order object.
Approve (Unapproved) Order
https://shinyads.com/api/orders_approve/
URL Variables:
token Your API token
id The ID of the order to approve
override (optional) 1 or 0
Output:
None
Reject (Unapproved) Order
https://shinyads.com/api/orders_reject/
URL Variables:
token Your API token
id The ID of the order to approve
comment Comment on the reason why the order was rejected
Output:
None
Cancel (Approved) Order
https://shinyads.com/api/orders_cancel/
URL Variables:
token Your API token
id The ID of the order to approve
Output:
None
Event Callbacks (aka Webhooks)
Event callbacks allow Shiny Ads to contact your server for various events. Check out this presentation on Webhooks to understand our event callbacks.
To enable event callbacks, go to the Settings menu option and click on API. Enter in a URI/URL into the callback input field.
This URL is on your server and will receive calls from Shiny Ads when specific events occur. Each call will include two URL variables, sig and event. The sig variable is the SHA1 hash of your API token found in
Settings and the data being sent (Order or PublisherPayment). This variable makes sure that no one is sending you bogus information and that the data has not been tampered with. The event variable is one of the following:
- publisher_payment
- redeemed_promotion
- reversed_order
- change_request
- rejected_order
- canceled_order
- completed_order
- approved_order
- new_order
The contents of the HTTP call will either be an Order object or a PublisherPayment depending on the event. The format of the contents will be either XML or JSON, depending on your settings.
For Advanced Users
An Order object in JSON looks like the following:
{
"id":"5021",
"advertiser_user_id":"9999",
"zone_id":"9999",
"publisher_user_id":"99999",
"adserver_banner_id":"999999999",
"adserver_campaign_id":"999999",
"impressions":"0",
"actual_impressions":"0",
"revenue_amount":"39",
"cpm":"0",
"paypal_fee":"1.43",
"shiny_fee":"0",
"refund_amount":"0",
"pub_revenue_amount":"0",
"shiny_revenue_amount":"0",
"date_created":"2010-09-11 19:03:16",
"date_start":"2010-09-11",
"date_end":"2010-10-11",
"date_approved":"2010-09-11 19:11:15",
"date_paid_publisher":null,
"date_rejected":null,
"date_emailed":null,
"date_refunded":null,
"date_ad_added":"2010-09-11",
"date_paid":"2010-09-11 19:07:55",
"date_reversed":null,
"paypal_txn_id":"XXXXXXXXXXXXX",
"paypal_refund_txn_id":"",
"paypal_reversal_txn_id":"",
"target_country":"",
"target_language":"",
"target_city":"",
"target_state":"",
"target_variables":"exid=7178",
"target_site_id":"0",
"target_zone_id":"0",
"target_category_id":"101702",
"currency":"USD", // multi-currency support
"currency_native":"USD",
"foreign_amount":"0",
"promotion_amount":"0", // used when an advertiser uses a promotional code
"promotion_id":"0",
"promotion_foreign_amount":"0",
"new_image":"", // used for change requests
"new_image_type":"", // "
"new_dest_url":"", // "
"weight":"8", // campaign's priority
"dest_url":"http://www.website.com",
"image":null,
"image_type":"png",
"exclusive":"1",
"rejected_comment":"",
"inside_sales":"0",
"order_description":"",
"ipaddress":""
}
Because the object sent to your server is NOT sent as a URL or FORM variable, you must be able to read in the RAW post string. In PHP, you can use;
$raw_post = file_get_contents('php://input');
Zones
List Zones
https://shinyads.com/api/zones_list/
URL Variables:
token Your API token
width The width of the zone (optional)
height The height of the zone (optional)
category The category of the zone (optional)
website The website that the zone belongs to (optional)
country The two-digit country code that this zones is either assigned to or accepts for geo-targeting (optional)
Output:
A list of Zone objects.
Get Zone
https://shinyads.com/api/zones_get/
URL Variables:
token Your API token
id Zone ID
Output:
A Zone object.
For Advanced Users
A Zone object in JSON looks like the following:
{
"id":"61",
"user_id":"1",
"description":"this is the name of the zone",
"text":"full description of the zone",
"example_image_url":"http://foobar.com/images/page.gif",
"app_url":"http://foobar.com/",
"size_width":"300",
"size_height":"250",
"logo_image_url":"http://foobar.com/images/logo.gif",
"info_email":"support@foobar.com",
"mediakit_url":"http://foobar.com/pfd/mediakit.pdf",
"active":"1",
"allow_swf_ads":"0",
"allow_animated_gifs":"1",
"min_revenue":"100.00",
"target_country":"1",
"target_language":"0",
"target_city":"0",
"target_state":"1",
"target_variable":"pos=top&category=news",
"campaign_style":"L",
"google_analytics_id":"",
"max_spend":"5000",
"private":"0",
"info_phone","555-123-4567",
"css_url":"http://foobar.com/css/shinyads.css",
"ad_format":"I",
"freq_num":"0",
"freq_type":"",
"allow_monitoring":"1",
"parent_url":"http://foobar.com/advertisehere.html",
"favicon_url":"http://foobar.com/images/favicon.ico"
}
Reports
Active Orders Report
https://shinyads.com/api/reports_active/
URL Variables:
token Your API token
currency The currency that you are requesting a report for (default is USD)
Output:
A list of Order objects
Outstanding Balance Report
https://shinyads.com/api/reports_outanding/
URL Variables:
token Your API token
currency The currency that you are requesting a report for (default is USD)
Output:
A list of Order objects that are completed and ready to be paid to the publisher (you)
Promotional Codes
List Promotional Codes
https://shinyads.com/api/promotions_list/
URL Variables:
token Your API token
redeemed 1 or 0 that denotes what list to return (optional)
sort One of these sorting options; date_created, date_redeemed, date_expiry, order_id, zone_id, amount (optional)
Output:
A list of Promotional Code objects
Create a Promotional Code
https://shinyads.com/promotions_create/
URL Variables:
token Your API token
amount The absolute discount amount (optional)
percent The percent of the discount (optional; either use amount or percent)
zone_id The ID of your ad zone that this promotional code is attached to (optional)
expiry_date The date that this promotional code expires (optional)
code The pre-set code (optional)
min The minimum purchase required for this promotional code to be redeemed (optional)
num_available The number of times that this code can be used (optional)
Output:
The Promotional Code object
Remove Promotional Code
https://shinyads.com/api/promotions_remove
URL Variables:
token Your API token
id The ID of the promotional code
Output:
None
Proprietary Ad Server Webhooks
If you run a proprietary ad server that you have built in-house, you can still have Shiny Ads directory integrate with it by building support for the following web services webhooks:
In order to use these web services webhooks, you must set your ad server to "Proprietary / Built-In" in the Settings > Ad Server page, then provide a URL and shared-secret key. The shared secret key will be used to produce a SHA1 hash over the provided combined shared-secret key and the entire parameter list. This hash value will be sent in the HTTP DIGEST authentication header as "shinyads:$hash".
The provided URL will be called by Shiny Ads as a HTTP POST with a Content-Type as application/json and a body of the json encoded parameters. These parameters will always include a 'method' root parameter. All input and output data is in JSON format.
Add Order Method
Parameters:
method: 'add_order'
order: the order object
override: a boolean that determines if the order needs to be overbooked regardless of available inventory
Output:
banner_id: The ID of the banner/creative/line-item on your ad server (optional)
campaign_id: The ID of the campaign on your ad server
advertiser_id: The ID of the advertiser on your ad server (optional)
error: If the call failed, provide an English error message
Stop Order Method
Parameters:
method: 'stop_order'
order:
banner_id: The ID of the banner on your ad server
campaign_id: The ID of the campaign on your ad server
Output:
-none-
Modify Order Method
Parameters:
method: 'modify_order'
order:
banner_id: The ID of the banner on your ad server
campaign_id: The ID of the campaign on your ad server
html: The new HTML of a HTML/text ad (optional)
text_ad: A boolean that states that this is an text ad
dest_url: The new destination URL (optional)
image: The image data (optional)
image_type: The image type (optional)
weight: The weight/priority of the campaign (optional)
Output:
-none-
Get Order Statistics Method
Parameters:
method: 'stats_order'
order:
campaign_id: The ID of the campaign on your ad server
Output:
impressions: The total impressions of this campaign
clicks: The total clicks of this campaign
Get Order Daily Statistics Method
Parameters:
method: 'get_daily_stats'
order:
campaign_id: The ID of the campaign on your ad server
start_date: The first date that the report should return data for
Output:
an ordered array of:
day: The date in a YYYY-MM-DD format
impressions: An integer representing the number of impressions for this date
clicks: An integer representing the number of clicks for this date
Order Object
id: The Shiny Ads ID for this order
campaign_id: The campaign/order ID
banner_id: The banner/creative/line-item ID
image: Raw image data
image_type: JPG, GIF, PNG
target_country: A comma delimited list of 2 digit country codes
target_state: A comma delimited list of states
target_city: A 2 digit country code following by a '|' and then a comma delimited list of city names
target_metro: A comma delimited list of DMA codes
target_language: A comma delimited list of 2-digit language codes
exclusive: If this order is exclusive for the dates and targeting
dest_url: The destination URL
amount: The total amount of the order
date_start: The start date
date_end: The end date (optional)
inside_sales: A boolean denoting that this order was created by an inside sales person
description: The order description
target_variables: Key-value pairs
currency: The 3 character currency code
weight: The weight/priority of the campaign
salesrep: The name of the sales representative (optional)
pilot_mode: A boolean that states that this order was created in pilot mode (test mode)
campaign_type: CPM, CPC, CPD, Flat-fee
impressions: The number of impressions requested in a CPM campaign
clicks: The number of clicks requested in a CPC campaign
