| Revision Date | Description |
| May 6, 2021 | Added BidSheet reporting API |
The use of the reporting API is intended for Advertisers running BidSheet ad groups on AdColony Video Ad Network to retrieve ad performance reporting data via an API. The API uses HTTP GET to make reporting requests and retrieve results from the server.
1. API Access URL
https://clients-api.adcolony.com/api/v2/bidsheet_summary?user_credentials=<api_key>&ad_group_id=<ad_group_id>&date=<mmddyyyy>
Note: Please refer to the Read-Only API Key in your account settings in the AdColony Portal to access your API_KEY
2. BidSheet Summary Report
The BidSheet summary reporting API provides performance data about a BidSheet ad group that belongs to an advertiser’s account. The reporting API allows for variable date range or specific date reports. Reports can only be generated for a specific ad group. Performance data can be grouped by different date intervals. For more information on all of these options, consult the request parameters below.
Note: A day is defined by the GMT time zone
2.1. Request Parameters
| Parameter | Data Element | Description |
| user_credentials | String
Required |
Please use the API Key found in your account settings in the AdColony Portal to access the reporting API |
| ad_group_id | String
Required |
The Ad Group ID associated with the Ad Group |
| format | String
Optional |
Response format
If not specified, then defaults to JSON, but other response formats such as CSV and XML are supported Supported values: json, xml, csv |
| date | String
Required unless ‘interval’ parameter is specified, in which case ‘date’ parameter will be overridden |
Start date in mmddyyyy format
Note: GMT time zone is assumed |
| end_date | String
Optional |
End date in mmddyyyy
Note: GMT time zone is assumed; should limit to 3 months in date range for daily report |
| interval | String
Optional |
A string specifying the date interval to retrieve data for
Supported values: today, yesterday, last24, this_week, last_week, this_month, last_month, last_30_days, this_year, all_time |
| date_group | String
Optional |
If not specified, defaults to ‘aggregate’
If ‘day’ is specified, report will break down by daily Supported values: hour, day, aggregate |
2.2. Response Variables
| CSV | JSON | XML | Description |
| Campaign ID | campaign_id | CampaignID | AdColony Campaign ID |
| Campaign Name | campaign_name | CampaignName | Name of Campaign in AdColony Portal |
| Ad Group ID | ad_group_id | AdGroupID | AdColony Ad Group ID |
| Ad Group Name | ad_group_name | AdGroupName | Name of Ad Group in AdColony Portal |
| Creative ID | creative_id | CreativeID | AdColony Creative ID |
| Creative Name | creative_name | CreativeName | Name of Creative in AdColony Portal |
| Advertiser Store ID | advertiser_store_id | AdvertiserStoreID | iTunes ID (iOS) / Bundle ID (Android) |
| Start Date | start_date | StartDate | Start date of report (if specified in the YYYY-MM-DD format) |
| End Date | end_date | EndDate | End date of report (if specified in the YYYY-MM-DD format) |
| Date | date | Date | When the date group is by day, in YYYY-MM-DD format. When date group is by hour, in YYYY-MM-DD HH format |
| Impressions | impressions | Impressions | Number of Ad Starts |
| CVVs | cvvs | CVVs | Number of Video Completes |
| Total Clicks | total_clicks | TotalClicks | Number of Clicks |
| CTR | ctr | CTR | Click Through Rate (Clicks / Impressions) |
| Spend ($) | spend | Spend | Total number amount spent |
| Total Campaign Spend Limit | total_campaign_spend_limit | TotalCampaignSpendLimit | Campaign Spend Limit (if set) |
| Total Group Spend Limit | total_group_spend_limit | TotalGroupSpendLimit | Ad Group Spend Limit (if set) |
| eCPI ($) | ecpi | eCPI | Effective Cost per Install (Spend / Install) |
| Installs | installs | Installs | Total Number of Installs |
| Country | country | Country | 2-Letter Country Abbreviation (ISO Alpha 2) |
| Platform | platform | Platform | iOS, Android |
| Pricing | pricing | Pricing | Pricing model |
| Bid | bid | Bid | Bid amount |
| BidSheet Row Hash | bidsheet_row_hash | BidSheetRowHash | Hash of targeting row from BidSheet |
| Publisher Store ID | publisher_store_id | PublisherStoreID | If iOS, the store ID. If Android, the app package name |
| App Name | app_name | AppName | Name of the application as it appears in the app store / google play, but if no name, portal name |
| App ID | app_id | AppID | UUID of the app as from the AdColony portal |
| Zone ID | zone_id | ZoneID | UUID of the zone from AdColony portal |
| Zone Name | zone_name | ZoneName | Name of the zone as shown in the AdColony UI |
| Device Language | device_language | DeviceLanguage | Language as defined in device settings |
| Zone Type | zone_type | ZoneType | Full Screen / Banner |
| Zone Skip | zone_skip | ZoneSkip | Skip / Non-skip zones |
| Session View Position | session_view_position | SessionViewPosition | The order in which the ad was shown on the inventory. For example, session view position of 3 means the ad was shown 3rd and two other adcolony ads were shown before yours. Considers only the order of ads trafficked via the AdColony SDK |
| Device Type | device_type | DeviceType | Phone, Tablet |
| Device Model | device_model | DeviceModel | The model of the device |
| OS Version | os_version | OSVersion | The version of the device operating system |
| Segment ID | segment_id | SegmentID | Segment ID |
| Segment Name | segment_name | SegmentName | The name of the segment |
| First Quartile Video Complete | first_quartiles | FirstQuartileVideoComplete | Impressions where 25% of video playback is complete (video only) |
| Midpoint Video Complete | midpoints | MidpointVideoComplete | Impressions where 50% of video playback is complete (video only) |
| Third Quartile Video Complete | third_quartiles | ThirdQuartileVideoComplete | Impressions where 75% of video playback is complete (video only) |
| SKAN Campaign ID | skan_campaign_id | SKANCampaignID | SKAN campaign ID |
2.3. Well-formatted Responses
Sample JSON and XML responses are shown below.
2.3.1. JSON
https://clients-api.adcolony.com/api/v2/bidsheet_summary?user_credentials=abcdefghijklmnopqrst&ad_group_id=1234&date=05062021&format=json
{ "status": "success", "results": [ { "campaign_id": 1234, "campaign_name": "Campaign", "ad_group_id": 1234, "ad_group_name": "Group", "creative_id": "", "creative_name": "", "advertiser_store_id": "123456789", "start_date": "2021-05-06", "end_date": "2021-05-06", "impressions": 0, "cvvs": 0, "total_clicks": 0, "ctr": 0.00, "spend": 0.0000000, "total_campaign_spend_limit": 500, "total_group_spend_limit": 500, "ecpi": 0, "installs": 0, "country": "US", "platform": "ios", "pricing": "cpi", "bid": 1, "bidsheet_row_hash": "48e1599cdb87c4d6c9f1292f7e54f58cabc3f8e725638a969b3ddfb6a3f92546", "publisher_store_id": "", "app_name": "", "app_id": "", "zone_id": "", "zone_name": "", "device_language": "", "zone_type": "", "zone_skip": "", "session_view_position": "", "device_type": "", "device_model": "", "os_version": "", "segment_id": "", "segment_name": "", "first_quartiles": 0, "midpoints": 0, "third_quartiles": 0, "skan_campaign_id": 1 } ]}
2.3.2. XML
https://clients-api.adcolony.com/api/v2/bidsheet_summary?user_credentials=abcdefghijklmnopqrst&ad_group_id=1234&date=05062021&format=xml
<Response xmlns="http://www.adcolony.com"> <Status>success</Status> <Reports> <Report> <CampaignID>1234</CampaignID> <CampaignName>Campaign</CampaignName> <AdGroupID>1234</AdGroupID> <AdGroupName>Group</AdGroupName> <CreativeID/> <CreativeName/> <AdvertiserStoreID>123456789</AdvertiserStoreID> <StartDate>2021-05-06</StartDate> <EndDate>2021-05-06</EndDate> <Impressions>0</Impressions> <CVVs>0</CVVs> <TotalClicks>0</TotalClicks> <CTR>0.00</CTR> <Spend>0.0000000</Spend> <TotalCampaignSpendLimit>500</TotalCampaignSpendLimit> <TotalGroupSpendLimit>500</TotalGroupSpendLimit> <eCPI>0</eCPI> <Installs>0</Installs> <Country>US</Country> <Platform>ios</Platform> <Pricing>cpi</Pricing> <Bid>1</Bid> <BidSheetRowHash>48e1599cdb87c4d6c9f1292f7e54f58cabc3f8e725638a969b3ddfb6a3f92546</BidSheetRowHash> <PublisherStoreID/> <AppName/> <AppID/> <ZoneID/> <ZoneName/> <DeviceLanguage/> <ZoneType/> <ZoneSkip/> <SessionViewPosition/> <DeviceType/> <DeviceModel/> <OSVersion/> <SegmentID/> <SegmentName/> <FirstQuartileVideoComplete>0</FirstQuartileVideoComplete> <MidpointVideoComplete>0</MidpointVideoComplete> <ThirdQuartileVideoComplete>0</ThirdQuartileVideoComplete> <SKANCampaignID>1</SKANCampaignID> </Report> </Reports></Response>
2.4. Errors
The Reporting API will return an error in the following situations:
| Status Code | Message |
| 401 | user_credentials is incorrect |
| 400 | Invalid id(s): ad_group_id |
| 400 | No Bidsheet group was found for specified ad_group_id |
| 400 | No Bidsheet was found for specified Bidsheet group |
| 400 | Invalid date format. The correct format is mmddyyyy |
| 400 | date is greater than end_date |
| 400 | The report requested exceeds the allowed capacity limit. Please try to reduce the report size by decreasing the date range |
| 429* | Your organization’s API queue has filled up — please wait a while, or contact [email protected] |
* API Queue Limit
To best support incoming requests for all users, a queue was implemented per API Key. As designed, up to five reports can be actively processed at the same time. Additional reporting requests made while five reports are actively running are added to a queue to become active once an existing report completes. The supported queue length is 25 reports. When five reports are actively running, and the queue count has hit 25 reports, any additional request will return a 429 error.
The recommended method of pulling concurrent reports is to run in batches between 15-20 reports up front, and then make additional requests as reports from the initial batch complete.
2.4.1. Sample JSON Error
{ "status": "error", "status_code": 401, "result": "user_credentials is incorrect"}
2.4.2. Sample XML Error
<Response xmlns="http://www.adcolony.com"><Status>error</Status><StatusCode>401</StatusCode><Result>user_credentials is incorrect</Result></Response>
3. Support Inquiries
If you need support with your API integration please contact [email protected].