Introduction
Welcome to the BrandOps Customer APIs! You can use our API to get information on various scores: brand scores, stage scores, channel scores and metric values in our database.
Authentication
BrandOps uses access tokens to allow access to the API. You can contact support at info@brandops.io to get an access token.
BrandOps expects for the API key to be included in all API requests to the server in a header that looks like the following:
brandops-access-token: your-access-token
Scores Export API
Get All Scores
# With shell, you can just pass the correct header with each request
curl --request GET 'https://api.brandops.io/customer/api/scores-export?customer_name=test-customer&category_name=test-category&month=9&year=2021' \
--header 'brandops-access-token: your-access-token'
The above command returns JSON structured like this:
[{
"brand_scores": [{
"score": 1,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
}],
"channel_scores": [{
"channel_category_id": 16,
"name": "Ads",
"score": 1,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
},
{
"channel_category_id": 4,
"name": "Blogs",
"score": 1,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
},
{
"channel_category_id": 7,
"name": "Email Campaigns",
"score": 1,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
},
{
"channel_category_id": 15,
"name": "Emails",
"score": 1,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
},
{
"channel_category_id": 19,
"name": "Employer Reviews",
"score": 1,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
},
{
"channel_category_id": 5,
"name": "News",
"score": 1,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
},
{
"channel_category_id": 9,
"name": "Podcast",
"score": 1,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
},
{
"channel_category_id": 2,
"name": "Product Reviews",
"score": 1,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
},
{
"channel_category_id": 17,
"name": "Search Engine Results",
"score": 1,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
},
{
"channel_category_id": 1,
"name": "Social",
"score": 1,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
},
{
"channel_category_id": 14,
"name": "Surveys via BrandOps",
"score": 0.0,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
},
{
"channel_category_id": 6,
"name": "Videos",
"score": 1,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
},
{
"channel_category_id": 13,
"name": "Web",
"score": 1,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
},
{
"channel_category_id": 12,
"name": "Web Analytics",
"score": 0.0,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
},
{
"channel_category_id": 10,
"name": "Webinar",
"score": 1,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT"
}
],
"company_id": 1,
"company_name": "Test Company",
"company_url": "https://www.test.io/",
"created_at": "Wed, 08 Sep 2021 19:33:15 GMT",
"description": null,
"google_trend_search_term": null,
"id": 1,
"metric_values": [{
"brand_metric_id": 1,
"channel_name": "Emails",
"is_percent": 0,
"is_private": 0,
"metric_label": "Discovered Email Count",
"metric_name": "email_discovered_email_count",
"score_type": "high_is_good",
"site_name": "Email Collector",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 3,
"channel_name": "News",
"is_percent": 0,
"is_private": 0,
"metric_label": "Aggregated Reach, News",
"metric_name": "news_aggregate_reach_per_million",
"score_type": "high_is_good",
"site_name": "News Crawler",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 4,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Days Since Last Post, Twitter",
"metric_name": "social_time_since_last_post_twitter",
"score_type": "low_is_good",
"site_name": "Twitter",
"stage_name": "Brand Presence",
"value": 2.0
},
{
"brand_metric_id": 5,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Days Since Last Post, LinkedIn",
"metric_name": "social_time_since_last_post_linkedin",
"score_type": "low_is_good",
"site_name": "LinkedIn",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 6,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Posts per Day, Twitter",
"metric_name": "social_post_frequency_twitter",
"score_type": "high_is_good",
"site_name": "Twitter",
"stage_name": "Brand Presence",
"value": 1.8
},
{
"brand_metric_id": 7,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Posts per Day, LinkedIn",
"metric_name": "social_post_frequency_linkedin",
"score_type": "high_is_good",
"site_name": "LinkedIn",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 8,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Posts per Day, All Social",
"metric_name": "social_post_frequency_across_channels",
"score_type": "high_is_good",
"site_name": "All-Social",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 9,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Follower Count, All Social",
"metric_name": "social_presence_across_channels",
"score_type": "high_is_good",
"site_name": "All-Social",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 10,
"channel_name": "Videos",
"is_percent": 0,
"is_private": 0,
"metric_label": "Video Count, YouTube",
"metric_name": "video_youtube_videos_count",
"score_type": "high_is_good",
"site_name": "YouTube",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 11,
"channel_name": "Videos",
"is_percent": 0,
"is_private": 0,
"metric_label": "Hours Since Last Post, YouTube",
"metric_name": "video_youtube_videos_freshness",
"score_type": "low_is_good",
"site_name": "YouTube",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 12,
"channel_name": "Videos",
"is_percent": 0,
"is_private": 0,
"metric_label": "SERP Position, YouTube",
"metric_name": "web_serp_rank_youtube",
"score_type": "low_is_good",
"site_name": "YouTube",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 13,
"channel_name": "Search Engine Results",
"is_percent": 0,
"is_private": 0,
"metric_label": "SERP Position Organic, Google",
"metric_name": "web_serp_rank_organic_google",
"score_type": "low_is_good",
"site_name": "SERP-API",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 14,
"channel_name": "Search Engine Results",
"is_percent": 0,
"is_private": 0,
"metric_label": "SERP Position Organic, Bing",
"metric_name": "web_serp_rank_organic_bing",
"score_type": "low_is_good",
"site_name": "SERP-API",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 15,
"channel_name": "Search Engine Results",
"is_percent": 0,
"is_private": 0,
"metric_label": "SERP Position Paid, Google",
"metric_name": "web_serp_rank_paid_google",
"score_type": "low_is_good",
"site_name": "SERP-API",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 16,
"channel_name": "Search Engine Results",
"is_percent": 0,
"is_private": 0,
"metric_label": "SERP Position Paid, Bing",
"metric_name": "web_serp_rank_paid_bing",
"score_type": "low_is_good",
"site_name": "SERP-API",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 17,
"channel_name": "Search Engine Results",
"is_percent": 0,
"is_private": 0,
"metric_label": "SERP Position Paid & Organic, Google",
"metric_name": "web_serp_rank_paid_and_organic_google",
"score_type": "low_is_good",
"site_name": "SERP-API",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 18,
"channel_name": "Search Engine Results",
"is_percent": 0,
"is_private": 0,
"metric_label": "SERP Position Paid & Organic, Bing",
"metric_name": "web_serp_rank_paid_and_organic_bing",
"score_type": "low_is_good",
"site_name": "SERP-API",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 19,
"channel_name": "Web",
"is_percent": 0,
"is_private": 0,
"metric_label": "Backlink Count, Alexa",
"metric_name": "web_awis_backlink_count",
"score_type": "high_is_good",
"site_name": "External-AWIS",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 20,
"channel_name": "Web",
"is_percent": 0,
"is_private": 0,
"metric_label": "Site Rank, Alexa",
"metric_name": "web_alexa_rank",
"score_type": "low_is_good",
"site_name": "External-AWIS",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 21,
"channel_name": "Web",
"is_percent": 0,
"is_private": 0,
"metric_label": "Page Views per User, Alexa",
"metric_name": "web_page_views_per_user",
"score_type": "high_is_good",
"site_name": "External-AWIS",
"stage_name": "Brand Attention",
"value": 1
},
{
"brand_metric_id": 22,
"channel_name": "Web",
"is_percent": 0,
"is_private": 0,
"metric_label": "Reach per Million, Alexa",
"metric_name": "web_reach_per_million",
"score_type": "high_is_good",
"site_name": "External-AWIS",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 23,
"channel_name": "Web",
"is_percent": 1,
"is_private": 0,
"metric_label": "Web Page Refresh Rate",
"metric_name": "web_page_refresh_rate",
"score_type": "high_is_good",
"site_name": "Site Crawler",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 26,
"channel_name": "Webinar",
"is_percent": 0,
"is_private": 0,
"metric_label": "Webinars Discovered",
"metric_name": "web_webinars_discovered_count",
"score_type": "high_is_good",
"site_name": "Webinar Detector",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 29,
"channel_name": "Product Reviews",
"is_percent": 0,
"is_private": 0,
"metric_label": "Reviews Count, All Sites",
"metric_name": "reviews_count_all",
"score_type": "high_is_good",
"site_name": "All-Reviews",
"stage_name": "Brand Attention",
"value": 1
},
{
"brand_metric_id": 32,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Follower Count, LinkedIn",
"metric_name": "social_follower_count_linkedin",
"score_type": "high_is_good",
"site_name": "LinkedIn",
"stage_name": "Brand Attention",
"value": 1
},
{
"brand_metric_id": 33,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Follower Count, Twitter",
"metric_name": "social_follower_count_twitter",
"score_type": "high_is_good",
"site_name": "Twitter",
"stage_name": "Brand Attention",
"value": 2.0
},
{
"brand_metric_id": 34,
"channel_name": "Videos",
"is_percent": 0,
"is_private": 0,
"metric_label": "Net New Subscribers, YouTube",
"metric_name": "social_subscriber_count_youtube",
"score_type": "high_is_good",
"site_name": "YouTube",
"stage_name": "Brand Attention",
"value": 1.0
},
{
"brand_metric_id": 35,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Mention Count, Twitter",
"metric_name": "social_mention_count_twitter",
"score_type": "high_is_good",
"site_name": "Twitter",
"stage_name": "Brand Attention",
"value": 1.0
},
{
"brand_metric_id": 37,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Engagement, Twitter",
"metric_name": "social_engagement_twitter",
"score_type": "high_is_good",
"site_name": "Twitter",
"stage_name": "Brand Attention",
"value": 1.1
},
{
"brand_metric_id": 38,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Engagement, LinkedIn",
"metric_name": "social_engagement_linkedin",
"score_type": "high_is_good",
"site_name": "LinkedIn",
"stage_name": "Brand Attention",
"value": 1.0
},
{
"brand_metric_id": 55,
"channel_name": "News",
"is_percent": 1,
"is_private": 0,
"metric_label": "Share of News Mentions",
"metric_name": "news_share_of_mention",
"score_type": "high_is_good",
"site_name": "News Crawler",
"stage_name": "Brand Attention",
"value": 1.0
},
{
"brand_metric_id": 57,
"channel_name": "Product Reviews",
"is_percent": 1,
"is_private": 0,
"metric_label": "Percent of 4 & 5 Star Reviews",
"metric_name": "reviews_stars_percent_of_4_5_stars",
"score_type": "high_is_good",
"site_name": "All-Reviews",
"stage_name": "Brand Reputation",
"value": 1.0
},
{
"brand_metric_id": 58,
"channel_name": "Product Reviews",
"is_percent": 1,
"is_private": 0,
"metric_label": "Percent of 1 & 2 Star Reviews",
"metric_name": "reviews_stars_percent_of_1_2_stars",
"score_type": "low_is_good",
"site_name": "All-Reviews",
"stage_name": "Brand Reputation",
"value": 1.0
},
{
"brand_metric_id": 59,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Sentiment: Percent of Promoters, Twitter",
"metric_name": "social_sentiment_percent_of_promoters",
"score_type": "high_is_good",
"site_name": "Twitter",
"stage_name": "Brand Reputation",
"value": 1.0
},
{
"brand_metric_id": 60,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Sentiment: Percent of Detractors, Twitter",
"metric_name": "social_sentiment_percent_of_demoters",
"score_type": "low_is_good",
"site_name": "Twitter",
"stage_name": "Brand Reputation",
"value": 1
},
{
"brand_metric_id": 63,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Sentiment, All Social",
"metric_name": "social_sentiment",
"score_type": "high_is_good",
"site_name": "All-Social",
"stage_name": "Brand Reputation",
"value": null
},
{
"brand_metric_id": 64,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Sentiment, Twitter",
"metric_name": "social_twitter_brand_sentiment",
"score_type": "high_is_good",
"site_name": "Twitter",
"stage_name": "Brand Reputation",
"value": 1.0
},
{
"brand_metric_id": 65,
"channel_name": "Product Reviews",
"is_percent": 0,
"is_private": 0,
"metric_label": "Reviews Stars",
"metric_name": "reviews_stars",
"score_type": "high_is_good",
"site_name": "All-Reviews",
"stage_name": "Brand Reputation",
"value": 1.0
},
{
"brand_metric_id": 67,
"channel_name": "Product Reviews",
"is_percent": 1,
"is_private": 0,
"metric_label": "Share of 4 & 5 Star Reviews",
"metric_name": "reviews_stars_share_of_4_5",
"score_type": "high_is_good",
"site_name": "All-Reviews",
"stage_name": "Brand Reputation",
"value": 1.0
},
{
"brand_metric_id": 68,
"channel_name": "Product Reviews",
"is_percent": 1,
"is_private": 0,
"metric_label": "Share of 1 & 2 Star Reviews",
"metric_name": "reviews_stars_share_of_1_2",
"score_type": "low_is_good",
"site_name": "All-Reviews",
"stage_name": "Brand Reputation",
"value": null
},
{
"brand_metric_id": 71,
"channel_name": "Videos",
"is_percent": 0,
"is_private": 0,
"metric_label": "Video Views, YouTube",
"metric_name": "video_views_youtube",
"score_type": "high_is_good",
"site_name": "YouTube",
"stage_name": "Brand Attention",
"value": 1.0
},
{
"brand_metric_id": 82,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Earned Embedded Links in Posts",
"metric_name": "social_earned_backlinks_in_post",
"score_type": "high_is_good",
"site_name": "Twitter",
"stage_name": "Brand Attention",
"value": 1
},
{
"brand_metric_id": 89,
"channel_name": "Blogs",
"is_percent": 0,
"is_private": 0,
"metric_label": "Blog Post Count",
"metric_name": "web_company_blog_count",
"score_type": "high_is_good",
"site_name": "Blog Crawler",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 90,
"channel_name": "Web",
"is_percent": 0,
"is_private": 0,
"metric_label": "Domain Authority, Moz",
"metric_name": "web_moz_domain_authority",
"score_type": "high_is_good",
"site_name": "Moz",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 91,
"channel_name": "Web",
"is_percent": 0,
"is_private": 0,
"metric_label": "Backlink Count, Moz",
"metric_name": "web_moz_backlink_count",
"score_type": "high_is_good",
"site_name": "Moz",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 92,
"channel_name": "Web",
"is_percent": 0,
"is_private": 0,
"metric_label": "Domain Rank, SEMrush",
"metric_name": "web_semrush_domain_rank",
"score_type": "low_is_good",
"site_name": "Semrush",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 93,
"channel_name": "Web",
"is_percent": 0,
"is_private": 0,
"metric_label": "Organic Traffic, SEMrush",
"metric_name": "web_semrush_organic_traffic",
"score_type": "high_is_good",
"site_name": "Semrush",
"stage_name": "Brand Attention",
"value": 1.0
},
{
"brand_metric_id": 94,
"channel_name": "Web",
"is_percent": 0,
"is_private": 0,
"metric_label": "Organic Cost, SEMrush",
"metric_name": "web_semrush_organic_cost",
"score_type": "high_is_good",
"site_name": "Semrush",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 95,
"channel_name": "Ads",
"is_percent": 0,
"is_private": 0,
"metric_label": "Adwords Traffic, SEMrush",
"metric_name": "web_semrush_adwords_traffic",
"score_type": "high_is_good",
"site_name": "Semrush",
"stage_name": "Brand Attention",
"value": 1.0
},
{
"brand_metric_id": 96,
"channel_name": "Ads",
"is_percent": 0,
"is_private": 0,
"metric_label": "Adwords Cost, SEMrush",
"metric_name": "web_semrush_adwords_cost",
"score_type": "low_is_good",
"site_name": "Semrush",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 97,
"channel_name": "Ads",
"is_percent": 0,
"is_private": 0,
"metric_label": "Search Ads Count",
"metric_name": "web_semrush_search_ads_count",
"score_type": "high_is_good",
"site_name": "Semrush",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 98,
"channel_name": "Ads",
"is_percent": 0,
"is_private": 0,
"metric_label": "Display Ads Count, SEMrush",
"metric_name": "web_semrush_display_ads_count",
"score_type": "high_is_good",
"site_name": "Semrush",
"stage_name": "Brand Presence",
"value": 0.0
},
{
"brand_metric_id": 99,
"channel_name": "Ads",
"is_percent": 0,
"is_private": 0,
"metric_label": "Landing Pages Count",
"metric_name": "web_semrush_landing_pages_count",
"score_type": "high_is_good",
"site_name": "Semrush",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 100,
"channel_name": "Ads",
"is_percent": 0,
"is_private": 0,
"metric_label": "Advertisers Rank, SEMrush",
"metric_name": "web_semrush_advertisers_rank",
"score_type": "low_is_good",
"site_name": "Semrush",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 101,
"channel_name": "Webinar",
"is_percent": 0,
"is_private": 0,
"metric_label": "Webinars, Social Promo & Mention Count",
"metric_name": "web_webinars_promo_mention_count",
"score_type": "high_is_good",
"site_name": "Webinar Detector",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 108,
"channel_name": "Podcast",
"is_percent": 0,
"is_private": 0,
"metric_label": "Podcast Episode Mention Count",
"metric_name": "podcast_listen_mention_count",
"score_type": "high_is_good",
"site_name": "Podcast",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 109,
"channel_name": "Podcast",
"is_percent": 0,
"is_private": 0,
"metric_label": "Owned Podcast Episode Count",
"metric_name": "owned_podcast_episode_count",
"score_type": "high_is_good",
"site_name": "Podcast",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 110,
"channel_name": "News",
"is_percent": 0,
"is_private": 0,
"metric_label": "Press Release Count",
"metric_name": "press_releases_count",
"score_type": "high_is_good",
"site_name": "News Crawler",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 116,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Posts per Day, Facebook",
"metric_name": "social_post_frequency_facebook",
"score_type": "high_is_good",
"site_name": "Facebook",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 117,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Days Since Last Post, Facebook",
"metric_name": "social_time_since_last_post_facebook",
"score_type": "low_is_good",
"site_name": "Facebook",
"stage_name": "Brand Presence",
"value": 3.0
},
{
"brand_metric_id": 118,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Follower Count, Instagram",
"metric_name": "social_follower_count_instagram",
"score_type": "high_is_good",
"site_name": "Instagram",
"stage_name": "Brand Attention",
"value": 1.0
},
{
"brand_metric_id": 119,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Posts per Day, Instagram",
"metric_name": "social_post_frequency_instagram",
"score_type": "high_is_good",
"site_name": "Instagram",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 120,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Days Since Last Post, Instagram",
"metric_name": "social_time_since_last_post_instagram",
"score_type": "low_is_good",
"site_name": "Instagram",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 122,
"channel_name": "Employer Reviews",
"is_percent": 0,
"is_private": 0,
"metric_label": "Employer Reviews Stars",
"metric_name": "employer_reviews_stars",
"score_type": "high_is_good",
"site_name": "Employer-Reviews",
"stage_name": "Brand Reputation",
"value": 1.0
},
{
"brand_metric_id": 123,
"channel_name": "Employer Reviews",
"is_percent": 1,
"is_private": 0,
"metric_label": "Percent of 1 & 2 Star Employer Reviews",
"metric_name": "employer_reviews_stars_percent_of_1_2_stars",
"score_type": "low_is_good",
"site_name": "Employer-Reviews",
"stage_name": "Brand Reputation",
"value": 1.0
},
{
"brand_metric_id": 124,
"channel_name": "Employer Reviews",
"is_percent": 1,
"is_private": 0,
"metric_label": "Percent of 4 & 5 Star Employer Reviews",
"metric_name": "employer_reviews_stars_percent_of_4_5_stars",
"score_type": "high_is_good",
"site_name": "Employer-Reviews",
"stage_name": "Brand Reputation",
"value": 1.0
},
{
"brand_metric_id": 125,
"channel_name": "Employer Reviews",
"is_percent": 1,
"is_private": 0,
"metric_label": "Share of 1 & 2 Star Employer Reviews",
"metric_name": "employer_reviews_stars_share_of_1_2",
"score_type": "low_is_good",
"site_name": "Employer-Reviews",
"stage_name": "Brand Reputation",
"value": 1.0
},
{
"brand_metric_id": 126,
"channel_name": "Employer Reviews",
"is_percent": 1,
"is_private": 0,
"metric_label": "Share of 4 & 5 Star Employer Reviews",
"metric_name": "employer_reviews_stars_share_of_4_5",
"score_type": "high_is_good",
"site_name": "Employer-Reviews",
"stage_name": "Brand Reputation",
"value": 1.0
},
{
"brand_metric_id": 127,
"channel_name": "Employer Reviews",
"is_percent": 0,
"is_private": 0,
"metric_label": "Employer Reviews Count, All Sites",
"metric_name": "employer_reviews_count_all",
"score_type": "high_is_good",
"site_name": "Employer-Reviews",
"stage_name": "Brand Attention",
"value": 1.0
},
{
"brand_metric_id": 129,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Owned Post Count, Linkedin",
"metric_name": "social_owned_post_count_linkedin",
"score_type": "high_is_good",
"site_name": "LinkedIn",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 130,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Owned Post Count, Twitter",
"metric_name": "social_owned_post_count_twitter",
"score_type": "high_is_good",
"site_name": "Twitter",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 131,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Owned Post Count, Facebook",
"metric_name": "social_owned_post_count_facebook",
"score_type": "high_is_good",
"site_name": "Facebook",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 132,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Owned Post Count, Instagram",
"metric_name": "social_owned_post_count_instagram",
"score_type": "high_is_good",
"site_name": "Instagram",
"stage_name": "Brand Presence",
"value": 0.0
},
{
"brand_metric_id": 133,
"channel_name": "News",
"is_percent": 0,
"is_private": 0,
"metric_label": "News Mention Count",
"metric_name": "news_mention_count",
"score_type": "high_is_good",
"site_name": "News Crawler",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 134,
"channel_name": "Webinar",
"is_percent": 0,
"is_private": 0,
"metric_label": "Webinars, Email Promo Count",
"metric_name": "webinars_email_promo_count",
"score_type": "high_is_good",
"site_name": "Webinar Detector",
"stage_name": "Brand Presence",
"value": 0.0
},
{
"brand_metric_id": 135,
"channel_name": "Blogs",
"is_percent": 0,
"is_private": 0,
"metric_label": "Blog Post, Email Promo Count",
"metric_name": "blog_post_email_promo_count",
"score_type": "high_is_good",
"site_name": "Blog Crawler",
"stage_name": "Brand Presence",
"value": 0.0
},
{
"brand_metric_id": 136,
"channel_name": "Blogs",
"is_percent": 0,
"is_private": 0,
"metric_label": "Blog Post, Social Share Count",
"metric_name": "blog_post_social_share_count",
"score_type": "high_is_good",
"site_name": "Blog Crawler",
"stage_name": "Brand Presence",
"value": 1.0
},
{
"brand_metric_id": 137,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Follower Growth Momentum, LinkedIn",
"metric_name": "follower_growth_momentum_linkedin",
"score_type": "high_is_good",
"site_name": "LinkedIn",
"stage_name": "Brand Momentum",
"value": -1.0
},
{
"brand_metric_id": 138,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Follower Growth Momentum, Twitter",
"metric_name": "follower_growth_momentum_twitter",
"score_type": "high_is_good",
"site_name": "Twitter",
"stage_name": "Brand Momentum",
"value": -1.0
},
{
"brand_metric_id": 139,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Mention Momentum, Twitter",
"metric_name": "social_mention_momentum_twitter",
"score_type": "high_is_good",
"site_name": "Twitter",
"stage_name": "Brand Momentum",
"value": 1
},
{
"brand_metric_id": 140,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Engagement Momentum, LinkedIn",
"metric_name": "social_engagement_momentum_linkedin",
"score_type": "high_is_good",
"site_name": "LinkedIn",
"stage_name": "Brand Momentum",
"value": -1
},
{
"brand_metric_id": 141,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Engagement Momentum, Twitter",
"metric_name": "social_engagement_momentum_twitter",
"score_type": "high_is_good",
"site_name": "Twitter",
"stage_name": "Brand Momentum",
"value": -0.1
},
{
"brand_metric_id": 142,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Net New Followers, Twitter",
"metric_name": "net_new_followers_twitter",
"score_type": "high_is_good",
"site_name": "Twitter",
"stage_name": "Brand Attention",
"value": 1.0
},
{
"brand_metric_id": 143,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Net New Followers, Linkedin",
"metric_name": "net_new_followers_linkedin",
"score_type": "high_is_good",
"site_name": "LinkedIn",
"stage_name": "Brand Attention",
"value": 1.0
},
{
"brand_metric_id": 144,
"channel_name": "Web",
"is_percent": 1,
"is_private": 0,
"metric_label": "Web Traffic Momentum, US",
"metric_name": "web_traffic_momentum",
"score_type": "high_is_good",
"site_name": "Semrush",
"stage_name": "Brand Momentum",
"value": 1
},
{
"brand_metric_id": 145,
"channel_name": "News",
"is_percent": 1,
"is_private": 0,
"metric_label": "News Mention Momentum",
"metric_name": "news_mention_momentum",
"score_type": "high_is_good",
"site_name": "News Crawler",
"stage_name": "Brand Momentum",
"value": 1.0
},
{
"brand_metric_id": 146,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Engagement, Facebook",
"metric_name": "social_engagement_facebook",
"score_type": "high_is_good",
"site_name": "Facebook",
"stage_name": "Brand Attention",
"value": 1.0
},
{
"brand_metric_id": 147,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Engagement, Instagram",
"metric_name": "social_engagement_instagram",
"score_type": "high_is_good",
"site_name": "Instagram",
"stage_name": "Brand Attention",
"value": 1
},
{
"brand_metric_id": 148,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Engagement Momentum, Instagram",
"metric_name": "social_engagement_momentum_instagram",
"score_type": "high_is_good",
"site_name": "Instagram",
"stage_name": "Brand Momentum",
"value": 1
},
{
"brand_metric_id": 149,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Engagement Momentum, Facebook",
"metric_name": "social_engagement_momentum_facebook",
"score_type": "high_is_good",
"site_name": "Facebook",
"stage_name": "Brand Momentum",
"value": 1
},
{
"brand_metric_id": 150,
"channel_name": "Videos",
"is_percent": 1,
"is_private": 0,
"metric_label": "Subscriber Growth Momentum, Youtube",
"metric_name": "social_subscriber_growth_momentum_youtube",
"score_type": "high_is_good",
"site_name": "YouTube",
"stage_name": "Brand Momentum",
"value": 1.1
},
{
"brand_metric_id": 151,
"channel_name": "Product Reviews",
"is_percent": 0,
"is_private": 0,
"metric_label": "Review Site Stars",
"metric_name": "rsrp_avg_summary_star_rating",
"score_type": "high_is_good",
"site_name": "All-Reviews",
"stage_name": "Brand Reputation",
"value": 1.1
},
{
"brand_metric_id": 153,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Net New Followers, Instagram",
"metric_name": "net_new_followers_instagram",
"score_type": "high_is_good",
"site_name": "Instagram",
"stage_name": "Brand Attention",
"value": 1.0
},
{
"brand_metric_id": 154,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Follower Growth Momentum, Instagram",
"metric_name": "follower_growth_momentum_instagram",
"score_type": "high_is_good",
"site_name": "Instagram",
"stage_name": "Brand Momentum",
"value": 1.1
},
{
"brand_metric_id": 155,
"channel_name": "Videos",
"is_percent": 1,
"is_private": 0,
"metric_label": "Video Views Momentum, Youtube",
"metric_name": "video_views_momentum",
"score_type": "high_is_good",
"site_name": "YouTube",
"stage_name": "Brand Momentum",
"value": -1.1
},
{
"brand_metric_id": 156,
"channel_name": "Product Reviews",
"is_percent": 1,
"is_private": 0,
"metric_label": "Reviews Count Momentum",
"metric_name": "reviews_count_momentum",
"score_type": "high_is_good",
"site_name": "All-Reviews",
"stage_name": "Brand Momentum",
"value": 100.0
},
{
"brand_metric_id": 157,
"channel_name": "Podcast",
"is_percent": 1,
"is_private": 0,
"metric_label": "Podcast Episode Count Momentum",
"metric_name": "podcast_episode_mention_count_momentum",
"score_type": "high_is_good",
"site_name": "Podcast",
"stage_name": "Brand Momentum",
"value": 1.7
},
{
"brand_metric_id": 158,
"channel_name": "Podcast",
"is_percent": 0,
"is_private": 0,
"metric_label": "Podcast Estimated Subscriber Reach",
"metric_name": "podcast_estimated_subscriber_reach",
"score_type": "high_is_good",
"site_name": "Podcast",
"stage_name": "Brand Attention",
"value": 1.0
},
{
"brand_metric_id": 159,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Sentiment: Percent of Promoters, Facebook",
"metric_name": "social_sentiment_percent_of_promoters_facebook",
"score_type": "high_is_good",
"site_name": "Facebook",
"stage_name": "Brand Reputation",
"value": 1
},
{
"brand_metric_id": 160,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Sentiment: Percent of Detractors, Facebook",
"metric_name": "social_sentiment_percent_of_demoters_facebook",
"score_type": "low_is_good",
"site_name": "Facebook",
"stage_name": "Brand Reputation",
"value": 1
},
{
"brand_metric_id": 161,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Sentiment, Facebook",
"metric_name": "social_facebook_brand_sentiment",
"score_type": "high_is_good",
"site_name": "Facebook",
"stage_name": "Brand Reputation",
"value": 0.0
},
{
"brand_metric_id": 162,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Sentiment: Percent of Promoters, Instagram",
"metric_name": "social_sentiment_percent_of_promoters_instagram",
"score_type": "high_is_good",
"site_name": "Instagram",
"stage_name": "Brand Reputation",
"value": null
},
{
"brand_metric_id": 163,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Sentiment: Percent of Detractors, Instagram",
"metric_name": "social_sentiment_percent_of_demoters_instagram",
"score_type": "low_is_good",
"site_name": "Instagram",
"stage_name": "Brand Reputation",
"value": 1
},
{
"brand_metric_id": 164,
"channel_name": "Social",
"is_percent": 0,
"is_private": 0,
"metric_label": "Sentiment, Instagram",
"metric_name": "social_instagram_brand_sentiment",
"score_type": "high_is_good",
"site_name": "Instagram",
"stage_name": "Brand Reputation",
"value": 0.0
},
{
"brand_metric_id": 166,
"channel_name": "Search Engine Results",
"is_percent": 1,
"is_private": 0,
"metric_label": "Share of Search, Google Trends",
"metric_name": "share_of_search_google_trends",
"score_type": "high_is_good",
"site_name": "SERP-API",
"stage_name": "Brand Attention",
"value": 1.9
},
{
"brand_metric_id": 167,
"channel_name": "Social",
"is_percent": 1,
"is_private": 0,
"metric_label": "Negative Sentiment Multiplier",
"metric_name": "social_sentiment_multiplier",
"score_type": "high_is_good",
"site_name": "All-Social",
"stage_name": "Brand Reputation",
"value": 1
},
{
"brand_metric_id": 168,
"channel_name": "Share Of",
"is_percent": 1,
"is_private": 0,
"metric_label": "Share of Everything",
"metric_name": "share_of_everything",
"score_type": "high_is_good",
"site_name": "Share Of",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 169,
"channel_name": "Share Of",
"is_percent": 1,
"is_private": 0,
"metric_label": "Share Of Owned",
"metric_name": "share_of_owned",
"score_type": "high_is_good",
"site_name": "Share Of",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 170,
"channel_name": "Share Of",
"is_percent": 1,
"is_private": 0,
"metric_label": "Share Of Earned",
"metric_name": "share_of_earned",
"score_type": "high_is_good",
"site_name": "Share Of",
"stage_name": "Brand Presence",
"value": 1
},
{
"brand_metric_id": 171,
"channel_name": "Share Of",
"is_percent": 1,
"is_private": 0,
"metric_label": "Share Of Paid",
"metric_name": "share_of_paid",
"score_type": "high_is_good",
"site_name": "Share Of",
"stage_name": "Brand Presence",
"value": 1
}
],
"name": "Test Company",
"pc_company_id": 1,
"portfolio_id": null,
"private_category_id": 1,
"product_brand_logo": null,
"product_domain": "test.io",
"product_url": "https://www.test.io/",
"sponsor_customer_id": 1,
"stage_scores": [{
"brand_stage_id": 1,
"score": 1.0,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT",
"stage_name": "Brand Presence"
},
{
"brand_stage_id": 3,
"score": 1.0,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT",
"stage_name": "Brand Attention"
},
{
"brand_stage_id": 5,
"score": 1.0,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT",
"stage_name": "Brand Reputation"
},
{
"brand_stage_id": 6,
"score": 1.0,
"score_at": "Sun, 31 Jul 2022 12:00:00 GMT",
"stage_name": "Brand Momentum"
}
],
"updated_at": "Wed, 08 Sep 2021 19:33:15 GMT"
}]
This endpoint retrieves data for a specific category and month. For each brand in a category, the response will include:
- Brand Scores
- Brand Pillar Scores
- Brand Channel Scores
- Brand Metric Values
HTTP Request
GET https://api.brandops.io/customer/api/scores-export
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | the name of customer accessing the API. |
| category_name | the name of the category. |
| month | month, example: pass 1 for January, 2 for February and so on. |
| year | year, example: 2021, 2022 and so on. |
Notes
- When using the current month, the data provided will be partial and up to the previous day. If the request is made on the 1st or 2nd of the current month and the scoring is not yet available, an error will be returned.
- Currently there are no rate limits for this API, but data will not change more frequently than once per day.
Changelog
- 25 July 2022: Added new share of metrics : Share of Everything, Share Of Owned, Share Of Earned, Share Of Paid
Advertisement APIs
Display Ads
Add Display Ads (POST)
Add new display ads by sending HTTP POST requests to the API.
HTTP Request
POST https://api.brandops.io/customer/api/ads/channel/display-ads
NOTE: Please pass brandops-access-token in the request header.
POST body to add a display add
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored Month |
| ad_identifier | Ad Identifier |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | CTR ( Click Through Rate) |
| average_cost_per_click | Average Cost-Per-Click |
| average_cost_per_mile | Average Cost-Per-Mile (CPM) |
| viewable_impressions | Viewable Impressions |
# With shell, you can just pass the correct header with each request
curl --request POST 'https://api.brandops.io/customer/api/ads/channel/display-ads?customer_name=Test-Customer&month=9&year=2022' \
--header 'brandops-access-token: your-access-token -d {POST_BODY}'
POST json body structure:
{
"customer_name": null,
"scored_month": null,
"ad_identifier": null,
"spend": null,
"impressions": null,
"clicks": null,
"click_through_rate": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"viewable_impressions": null
}
Read display Ads (GET)
API to get saved display ads from the database.
HTTP Request
GET https://api.brandops.io/customer/api/ads/channel/display-ads
Query Parameters
Note: Either provide start_date/end_date or month/year to get ads for a time range.
| Parameter | Description |
|---|---|
| customer_name | customer_name |
| start_date | Start date |
| end_date | End date |
| month | Month |
| year | Year |
NOTE: Please pass brandops-access-token in the request header.
# With shell, you can just pass the correct header with each request
curl --request GET 'https://api.brandops.io/customer/api/ads/channel/display-ads?customer_name=Test-Customer&month=9&year=2022' \
--header 'brandops-access-token: your-access-token'
The above command returns JSON structured like this:
[
{
"id": 1,
"company_id": 317,
"scored_month": null,
"ad_identifier": null,
"spend": null,
"impressions": null,
"clicks": null,
"click_through_rate": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"viewable_impressions": null,
"created_at": "Fri, 16 Sep 2022 12:08:44 GMT",
"updated_at": "Fri, 16 Sep 2022 12:08:44 GMT"
}
]
Update Display Ads (UPDATE)
API to update Display Ads properties. When a PUT request is performed, the properties of the request body are read, and if the resource has a property with the same name the property of the resource will be set to the new value.
HTTP Request
PUT https://api.brandops.io/customer/api/ads/channel/display-ads/<id>
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | customer_name |
NOTE: Please pass brandops-access-token in the request header.
Request json body structure:
{
"scored_month": null,
"ad_identifier": null,
"spend": null,
"impressions": null,
"clicks": null,
"click_through_rate": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"viewable_impressions": null
}
Delete Display Ads (DELETE)
Resources are deleted by sending an HTTP DELETE request to the URL that the resource is located at. This is the URL that contains the id of the resource.
HTTP Request
DELETE https://api.brandops.io/customer/api/ads/channel/display-ads/<id>
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | customer_name |
NOTE: Please pass brandops-access-token in the request header.
Notes
- Currently there are no rate limits for this API.
Changelog
- 20 September 2022: Added APIs
Facebook Ads
Add Facebook Ads (POST)
Add new facebook ads by sending HTTP POST requests to the API.
HTTP Request
POST https://api.brandops.io/customer/api/ads/channel/facebook
NOTE: Please pass brandops-access-token in the request header.
POST body to add facebook single image ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored Month |
| ad_identifier | Ad Identifier |
| ad_type | "image_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click Through Rate |
| average_cost_per_click | Average Cost Per Click |
| average_cost_per_mile | Average Cost Per Mile |
| ad_frequency | Ad Frequency |
| likes | Likes |
| comments | Comments |
| total_post_engagement | Total Post Engagement |
POST body to add facebook boosted image ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored Month |
| ad_identifier | Ad Identifier |
| ad_type | "boosted_image" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click Through Rate |
| average_cost_per_click | Average Cost Per Click |
| average_cost_per_mile | Average Cost Per Mile |
| shares | Shares |
| likes | Likes |
| comments | Comments |
| total_post_engagement | Total Post Engagement |
POST body to add facebook video ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored Month |
| ad_identifier | Ad Identifier |
| ad_type | "video_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click Through Rate |
| average_cost_per_click | Average Cost Per Click |
| average_cost_per_mile | Average Cost Per Mile |
| shares | Shares |
| likes | Likes |
| comments | Comments |
| total_post_engagement | Total Post Engagement |
| video_plays | Video Plays |
| video_thru_plays | Video Thru Plays |
| video_cost_per_thru_play | Video Cost Per Thru Play |
| video_average_play_time | Video Average Play Time |
| ad_frequency | Ad Frequency |
Note: Ad types are ('image_ads', 'boosted_image', 'video_ads', 'boosted_live_video', 'carousel_ads', 'instant_experience_ads', 'collection_ads_mobile', 'lead_from_ads', 'facebook_messenger_click_to_chat_ads', 'facebook_messenger_sponsored_message_ads')
# With shell, you can just pass the correct header with each request
curl --request POST 'https://api.brandops.io/customer/api/ads/channel/facebook?customer_name=Test-Customer&month=9&year=2022' \
--header 'brandops-access-token: your-access-token -d {POST_BODY}'
POST json body structure:
{
"ad_frequency": null,
"ad_identifier": null,
"ad_type": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"carousel_card_comments_per_individual": null,
"carousel_card_engagment_per_individual": null,
"carousel_card_likes_per_individual": null,
"carousel_card_shares_per_individual": null,
"click_through_rate": null,
"clicks": null,
"comments": null,
"cost_per_conversation_started": null,
"cost_per_messaging_conversation_started": null,
"facebook_store_visits": null,
"impressions": null,
"instant_experience_outbound_clicks": null,
"instant_experience_view_time": null,
"instant_experience_views": null,
"likes": null,
"messaging_conversation_started": null,
"net_new_messaging_connections": null,
"open_rate": null,
"outbound_clicks": null,
"product_catalog_sales": null,
"shares": null,
"spend": null,
"total_engagements": null,
"total_messaging_connection": null,
"total_post_engagement": null,
"video_average_play_time": null,
"video_cost_per_thru_play": null,
"video_plays": null,
"video_thru_plays": null
}
Read Facebook Ads (GET)
API to get saved facebook ads from the database.
HTTP Request
GET https://api.brandops.io/customer/api/ads/channel/facebook
Query Parameters
Note: Either provide start_date/end_date or month/year to get ads for a time range.
| Parameter | Description |
|---|---|
| customer_name | Customer name |
| start_date | Start date |
| end_date | End date |
| month | Month |
| year | Year |
NOTE: Please pass brandops-access-token in the request header.
# With shell, you can just pass the correct header with each request
curl --request GET 'https://api.brandops.io/customer/api/ads/channel/facebook?customer_name=Test-Customer&month=9&year=2022' \
--header 'brandops-access-token: your-access-token'
The above command returns JSON structured like this:
[
{
"ad_frequency": null,
"ad_identifier": null,
"ad_type": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"carousel_card_comments_per_individual": null,
"carousel_card_engagment_per_individual": null,
"carousel_card_likes_per_individual": null,
"carousel_card_shares_per_individual": null,
"click_through_rate": null,
"clicks": null,
"comments": null,
"cost_per_conversation_started": null,
"cost_per_messaging_conversation_started": null,
"facebook_store_visits": null,
"impressions": null,
"instant_experience_outbound_clicks": null,
"instant_experience_view_time": null,
"instant_experience_views": null,
"likes": null,
"messaging_conversation_started": null,
"net_new_messaging_connections": null,
"open_rate": null,
"outbound_clicks": null,
"product_catalog_sales": null,
"shares": null,
"spend": null,
"total_engagements": null,
"total_messaging_connection": null,
"total_post_engagement": null,
"video_average_play_time": null,
"video_cost_per_thru_play": null,
"video_plays": null,
"video_thru_plays": null
}
]
Update Facebook Ads (UPDATE)
API to update Facebook Ads properties. When a PUT request is performed, the properties of the request body are read, and if the resource has a property with the same name the property of the resource will be set to the new value.
HTTP Request
PUT https://api.brandops.io/customer/api/ads/channel/facebook/<id>
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | customer_name |
NOTE: Please pass brandops-access-token in the request header.
Request json body structure:
{
"ad_frequency": null,
"ad_identifier": null,
"ad_type": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"carousel_card_comments_per_individual": null,
"carousel_card_engagment_per_individual": null,
"carousel_card_likes_per_individual": null,
"carousel_card_shares_per_individual": null,
"click_through_rate": null,
"clicks": null,
"comments": null,
"cost_per_conversation_started": null,
"cost_per_messaging_conversation_started": null,
"facebook_store_visits": null,
"impressions": null,
"instant_experience_outbound_clicks": null,
"instant_experience_view_time": null,
"instant_experience_views": null,
"likes": null,
"messaging_conversation_started": null,
"net_new_messaging_connections": null,
"open_rate": null,
"outbound_clicks": null,
"product_catalog_sales": null,
"shares": null,
"spend": null,
"total_engagements": null,
"total_messaging_connection": null,
"total_post_engagement": null,
"video_average_play_time": null,
"video_cost_per_thru_play": null,
"video_plays": null,
"video_thru_plays": null
}
Delete Facebook Ads (DELETE)
Resources are deleted by sending an HTTP DELETE request to the URL that the resource is located at. This is the URL that contains the id of the resource.
HTTP Request
DELETE https://api.brandops.io/customer/api/ads/channel/facebook/<id>
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | customer_name |
NOTE: Please pass brandops-access-token in the request header.
Notes
- Currently there are no rate limits for this API.
Changelog
- 20 September 2022: Added APIs
Google Ads
Add Google Ads (POST)
Add new google ads by sending HTTP POST requests to the API.
HTTP Request
POST https://api.brandops.io/customer/api/ads/channel/google
NOTE: Please pass brandops-access-token in the request header.
POST body to add a google add
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored Month |
| ad_identifier | Ad Identifier |
| ad_type | AD TYPE: search_ads, display_ads |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | CTR (Click Through Rate) |
| average_cost_per_click | Average Cost-Per-Click |
| average_cost_per_mile | Average Cost-Per-Mile (CPM) |
| search_lost_is_rank | Search Lost IS (rank) |
| impressions_percent_top | Impressions % (Top) |
| impressions_percent_absolute_top | Impressions % (Absolute Top) |
| search_top_is | Search Top IS |
| search_absolute_top_is | Search Absolute Top IS |
| search_lost_top_is_rank | Search Lost Top IS (Rank) |
| search_lost_absolute_top_is_rank | Search Lost Abs. Top IS (Rank) |
# With shell, you can just pass the correct header with each request
curl --request POST 'https://api.brandops.io/customer/api/ads/channel/google?customer_name=Test-Customer&month=9&year=2022' \
--header 'brandops-access-token: your-access-token -d {POST_BODY}'
POST json body structure:
{
"customer_name": null,
"scored_month":null,
"ad_identifier": null,
"ad_type": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"click_through_rate": null,
"clicks": null,
"impressions": null,
"impressions_percent_absolute_top": null,
"impressions_percent_top": null,
"scored_month": "Fri, 30 Sep 2022 00:00:00 GMT",
"search_absolute_top_is": null,
"search_lost_absolute_top_is_rank": null,
"search_lost_is_rank": null,
"search_lost_top_is_rank": null,
"search_top_is": null,
"spend": null
}
Read Google Ads (GET)
API to get saved google ads from the database.
HTTP Request
GET https://api.brandops.io/customer/api/ads/channel/google
Query Parameters
Note: Either provide start_date/end_date or month/year to get ads for a time range.
| Parameter | Description |
|---|---|
| customer_name | customer_name |
| start_date | Start date |
| end_date | End date |
| month | Month |
| year | Year |
| ad_type | search_ads, display_ads |
NOTE: Please pass brandops-access-token in the request header.
# With shell, you can just pass the correct header with each request
curl --request GET 'https://api.brandops.io/customer/api/ads/channel/google?customer_name=Test-Customer&month=9&year=2022' \
--header 'brandops-access-token: your-access-token'
The above command returns JSON structured like this:
[
{
"ad_identifier": null,
"ad_type": null,
"added_by_customer_id": 317,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"click_through_rate": null,
"clicks": null,
"company_id": 317,
"scored_month": "",
"created_at": "Fri, 16 Sep 2022 12:08:44 GMT",
"id": 1,
"impressions": null,
"impressions_percent_absolute_top": null,
"impressions_percent_top": null,
"scored_month": "Fri, 30 Sep 2022 00:00:00 GMT",
"search_absolute_top_is": null,
"search_lost_absolute_top_is_rank": null,
"search_lost_is_rank": null,
"search_lost_top_is_rank": null,
"search_top_is": null,
"spend": null,
"updated_at": "Fri, 16 Sep 2022 12:08:44 GMT"
}
]
Update Google Ads (UPDATE)
API to update Google Ads properties. When a PUT request is performed, the properties of the request body are read, and if the resource has a property with the same name the property of the resource will be set to the new value.
HTTP Request
PUT https://api.brandops.io/customer/api/ads/channel/google/<id>
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | customer_name |
NOTE: Please pass brandops-access-token in the request header.
Request json body structure:
{
"ad_identifier": null,
"ad_type": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"click_through_rate": null,
"clicks": null,
"impressions": null,
"impressions_percent_absolute_top": null,
"impressions_percent_top": null,
"scored_month": "Fri, 30 Sep 2022 00:00:00 GMT",
"search_absolute_top_is": null,
"search_lost_absolute_top_is_rank": null,
"search_lost_is_rank": null,
"search_lost_top_is_rank": null,
"search_top_is": null,
"spend": null
}
Delete Google Ads (DELETE)
Resources are deleted by sending an HTTP DELETE request to the URL that the resource is located at. This is the URL that contains the id of the resource.
HTTP Request
DELETE https://api.brandops.io/customer/api/ads/channel/google/<id>
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | customer_name |
NOTE: Please pass brandops-access-token in the request header.
Notes
- Currently there are no rate limits for this API.
Changelog
- 20 September 2022: Added APIs
Instagram Ads
Add Instagram Ads (POST)
Add new instagram ads by sending HTTP POST requests to the API.
HTTP Request
POST https://api.brandops.io/customer/api/ads/channel/instagram
NOTE: Please pass brandops-access-token in the request header.
POST body to add instagram single image ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | Ad identifier |
| ad_type | "single_image_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click through rate |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| ad_frequency | Ad frequency |
| likes | Likes |
| comments | Comments |
| shares | Shares |
| total_engagements | Total engagements |
| total_post_engagement | Total post engagement |
| net_new_messaging_connections | Net new messaging connections |
| total_messaging_connection | Total messaging connection |
| cost_per_conversation_started | Cost per conversation started |
| open_rate | Open rate |
| outbound_clicks | Outbound clicks |
POST body to add instagram video ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | Ad identifier |
| ad_type | "video_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click through rate |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| ad_frequency | Ad frequency |
| likes | Likes |
| comments | Comments |
| shares | Shares |
| total_engagements | Total engagements |
| total_post_engagement | Total post engagement |
| video_plays | Video plays |
| video_thru_plays | Video thru plays |
| video_cost_per_thru_play | Video cost per thru play |
| video_average_play_time | Video average play time |
POST body to add instagram carousel ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | Ad identifier |
| ad_type | "video_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click through rate |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| ad_frequency | Ad frequency |
| likes | Likes |
| comments | Comments |
| shares | Shares |
| total_engagements | Total engagements |
| total_post_engagement | Total post engagement |
| video_plays | Video plays |
| video_thru_plays | Video thru plays |
| video_cost_per_thru_play | Video cost per thru play |
| video_average_play_time | Video average play time |
| messaging_conversation_started | Messaging conversation started |
| cost_per_messaging_conversation_started | Cost per messaging conversation started |
| carousel_card_likes_per_individual | Carousel card likes per individual |
| carousel_card_comments_per_individual | Carousel card comments per individual |
| carousel_card_shares_per_individual | Carousel card shares per individual |
| carousel_card_engagment_per_individual | Carousel card engagment per individual |
Note: ad_type=('single_image_ads', 'video_ads', 'carousel_ads', 'explore_ads', 'reel_ads', 'story_ads', 'collection_ads')
# With shell, you can just pass the correct header with each request
curl --request POST 'https://api.brandops.io/customer/api/ads/channel/instagram?customer_name=Test-Customer&month=9&year=2022' \
--header 'brandops-access-token: your-access-token -d {POST_BODY}'
POST json body structure:
{
"ad_identifier": null,
"ad_type": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"click_through_rate": null,
"clicks": null,
"comments": null,
"cost_per_conversation_started": null,
"facebook_store_visits": null,
"impressions": null,
"instant_experience_views": null,
"instant_experience_views_time": null,
"net_new_messaging_connections": null,
"open_rate": null,
"outbound_clicks": null,
"product_catalog_sales": null,
"replies": null,
"saves": null,
"scored_month": null,
"shares": null,
"spend": null,
"total_engagements": null,
"total_messaging_connections": null,
"total_sales": null,
"unique_accounts_reached": null,
"unique_views": null,
"video_average_play_time": null,
"video_cost_per_thru_play": null,
"video_plays": null,
"video_thru_plays": null,
"views": null
}
Read Instagram Ads (GET)
API to get saved instagram ads from the database.
HTTP Request
GET https://api.brandops.io/customer/api/ads/channel/instagram
Query Parameters
Note: Either provide start_date/end_date or month/year to get ads for a time range.
| Parameter | Description |
|---|---|
| customer_name | Customer name |
| start_date | Start date |
| end_date | End date |
| month | Month |
| year | Year |
NOTE: Please pass brandops-access-token in the request header.
# With shell, you can just pass the correct header with each request
curl --request GET 'https://api.brandops.io/customer/api/ads/channel/instagram?customer_name=Test-Customer&month=9&year=2022' \
--header 'brandops-access-token: your-access-token'
The above command returns JSON structured like this:
[
{
"ad_identifier": null,
"ad_type": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"click_through_rate": null,
"clicks": null,
"comments": null,
"cost_per_conversation_started": null,
"created_at": "Fri, 16 Sep 2022 17:47:32 GMT",
"facebook_store_visits": null,
"id": 1,
"impressions": null,
"instant_experience_views": null,
"instant_experience_views_time": null,
"net_new_messaging_connections": null,
"open_rate": null,
"outbound_clicks": null,
"product_catalog_sales": null,
"replies": null,
"saves": null,
"scored_month": "Fri, 30 Sep 2022 00:00:00 GMT",
"shares": null,
"spend": null,
"total_engagements": null,
"total_messaging_connections": null,
"total_sales": null,
"unique_accounts_reached": null,
"unique_views": null,
"updated_at": "Fri, 16 Sep 2022 17:47:32 GMT",
"video_average_play_time": null,
"video_cost_per_thru_play": null,
"video_plays": null,
"video_thru_plays": null,
"views": null
}
]
Update Instagram Ads (UPDATE)
API to update Instagram Ads properties. When a PUT request is performed, the properties of the request body are read, and if the resource has a property with the same name the property of the resource will be set to the new value.
HTTP Request
PUT https://api.brandops.io/customer/api/ads/channel/youtube/<id>
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | customer_name |
NOTE: Please pass brandops-access-token in the request header.
Request json body structure:
{
"ad_identifier": null,
"ad_type": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"click_through_rate": null,
"clicks": null,
"comments": null,
"cost_per_conversation_started": null,
"facebook_store_visits": null,
"impressions": null,
"instant_experience_views": null,
"instant_experience_views_time": null,
"net_new_messaging_connections": null,
"open_rate": null,
"outbound_clicks": null,
"product_catalog_sales": null,
"replies": null,
"saves": null,
"shares": null,
"spend": null,
"total_engagements": null,
"total_messaging_connections": null,
"total_sales": null,
"unique_accounts_reached": null,
"unique_views": null,
"video_average_play_time": null,
"video_cost_per_thru_play": null,
"video_plays": null,
"video_thru_plays": null,
"views": null
}
Delete Instagram Ads (DELETE)
Resources are deleted by sending an HTTP DELETE request to the URL that the resource is located at. This is the URL that contains the id of the resource.
HTTP Request
DELETE https://api.brandops.io/customer/api/ads/channel/instagram/<id>
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | customer_name |
NOTE: Please pass brandops-access-token in the request header.
Notes
- Currently there are no rate limits for this API.
Changelog
- 20 September 2022: Added APIs
Linkedin Ads
Add Linkedin Ads (POST)
Add new linkedin ads by sending HTTP POST requests to the API.
HTTP Request
POST https://api.brandops.io/customer/api/ads/channel/linkedin
NOTE: Please pass brandops-access-token in the request header.
POST body to add linkedin sponsored content add
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored Month |
| ad_identifier | Ad Identifier |
| ad_type | "sponsored_content_ads" |
| ad_format | Ad Format |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| click_through_rate | Click through rate |
| likes | Likes |
| engagement | Engagement |
| comments | Comments |
| shares | Shares |
| new_followers_added | New followers added |
| linkedin_page_visits | Linkedin page visits |
| video_views | Video views |
| video_view_through_rate | Video view through rate |
| video_cost_per_view | Video cost per view |
| video_completion_rate | Video completion rate |
| video_total_engagement | Video total engagement |
POST body to add linkedin sponsored messaging add
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | Ad identifier |
| ad_type | "sponsored_messaging_ads" |
| ad_format | Ad format |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| click_through_rate | Click through rate |
| message_sends | Message sends |
| message_opens | Message opens |
| message_open_rate | Message open rate |
| message_cost_per_send | Message cost per send |
| message_cost_per_open | Message cost per open |
POST body to add linkedin single image add
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | ad identifier |
| ad_type | "single_image_ads" |
| ad_format | Ad Format |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| click_through_rate | Click through rate |
POST body to add linkedin video add
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | ad identifier |
| ad_type | "video_ads" |
| ad_format | ad format |
| spend | spend |
| impressions | impressions |
| clicks | clicks |
| average_cost_per_click | average cost per click |
| average_cost_per_mile | average cost per mile |
| click_through_rate | click through rate |
| video_views | video views |
| video_view_through_rate | video view through rate |
| video_cost_per_view | video cost per view |
| video_completion_rate | video completion rate |
| video_total_engagement | video total engagement |
NOTE: ad type=('sponsored_content_ads', 'sponsored_messaging_ads', 'single_image_ads', 'video_ads')
# With shell, you can just pass the correct header with each request
curl --request POST 'https://api.brandops.io/customer/api/ads/channel/linkedin?customer_name=Test-Customer&month=9&year=2022' \
--header 'brandops-access-token: your-access-token -d {POST_BODY}'
POST json body structure:
{
"customer_name": null,
"scored_month": null,
"ad_identifier": null,
"ad_type": null,
"ad_format": null,
"spend": null,
"impressions": null,
"clicks": null,
"click_through_rate": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"viewable_impressions": null,
"video_views": null,
"video_view_through_rate": null,
"video_cost_per_view": null,
"video_completion_rate": null,
"video_total_engagement": null
}
Read Linkedin Ads (GET)
API to get saved linkedin ads from the database.
HTTP Request
GET https://api.brandops.io/customer/api/ads/channel/linkedin
Query Parameters
Note: Either provide start_date/end_date or month/year to get ads for a time range.
| Parameter | Description |
|---|---|
| customer_name | Customer name |
| start_date | Start date |
| end_date | End date |
| month | Month |
| year | Year |
NOTE: Please pass brandops-access-token in the request header.
# With shell, you can just pass the correct header with each request
curl --request GET 'https://api.brandops.io/customer/api/ads/channel/linkedin?customer_name=Test-Customer&month=9&year=2022' \
--header 'brandops-access-token: your-access-token'
The above command returns JSON structured like this:
[
{
"ad_format": null,
"ad_identifier": "",
"ad_type": null,
"added_by_customer_id": 317,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"click_through_rate": null,
"clicks": null,
"comments": null,
"company_id": 317,
"created_at": "Fri, 16 Sep 2022 15:33:19 GMT",
"engagement": null,
"id": 1,
"impressions": null,
"likes": null,
"linkedin_page_visits": null,
"message_cost_per_open": null,
"message_cost_per_send": null,
"message_open_rate": null,
"message_opens": null,
"message_sends": null,
"new_followers_added": null,
"scored_month": "Fri, 30 Sep 2022 00:00:00 GMT",
"shares": null,
"spend": null,
"updated_at": "Fri, 16 Sep 2022 15:33:19 GMT",
"video_completion_rate": null,
"video_cost_per_view": null,
"video_total_engagement": null,
"video_view_through_rate": null,
"video_views": null
}
]
Update Linkedin Ads (UPDATE)
API to update Linkedin Ads properties. When a PUT request is performed, the properties of the request body are read, and if the resource has a property with the same name the property of the resource will be set to the new value.
HTTP Request
PUT https://api.brandops.io/customer/api/ads/channel/linkedin/<id>
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | customer_name |
NOTE: Please pass brandops-access-token in the request header.
Request json body structure:
{
"ad_format": null,
"ad_identifier": "",
"ad_type": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"click_through_rate": null,
"clicks": null,
"comments": null,
"engagement": null,
"impressions": null,
"likes": null,
"linkedin_page_visits": null,
"message_cost_per_open": null,
"message_cost_per_send": null,
"message_open_rate": null,
"message_opens": null,
"message_sends": null,
"new_followers_added": null,
"scored_month": null,
"shares": null,
"spend": null,
"video_completion_rate": null,
"video_cost_per_view": null,
"video_total_engagement": null,
"video_view_through_rate": null,
"video_views": null
}
Delete Linkedin Ads (DELETE)
Resources are deleted by sending an HTTP DELETE request to the URL that the resource is located at. This is the URL that contains the id of the resource.
HTTP Request
DELETE https://api.brandops.io/customer/api/ads/channel/linkedin/<id>
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | customer_name |
NOTE: Please pass brandops-access-token in the request header.
Notes
- Currently there are no rate limits for this API.
Changelog
- 20 September 2022: Added APIs
Twitter Ads
Add Twitter Ads (POST)
Add new twitter ads by sending HTTP POST requests to the API.
HTTP Request
POST https://api.brandops.io/customer/api/ads/channel/twitter
NOTE: Please pass brandops-access-token in the request header.
POST body to add twitter image ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | Ad identifier |
| ad_type | "image_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click through rate |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| likes | Likes |
| comments | Comments |
| new_followers_added | New followers added |
| retweets | Retweets |
POST body to add twitter text ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | Ad identifier |
| ad_type | "text_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click through rate |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| likes | Likes |
| comments | Comments |
| new_followers_added | New followers added |
| retweets | Retweets |
POST body to add twitter video ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | Ad identifier |
| ad_type | "video_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click through rate |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| likes | Likes |
| comments | Comments |
| new_followers_added | New followers added |
| retweets | Retweets |
| video_views | Video views |
| video_view_through_rate | Video view through rate |
| video_average_cost_per_view | Video average cost per view |
POST body to add twitter carousel ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | Ad identifier |
| ad_type | "carousel_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click through rate |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| likes | Likes |
| comments | Comments |
| new_followers_added | New followers added |
| retweets | Retweets |
POST body to add twitter moment ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | Ad identifier |
| ad_type | "moment_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click through rate |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| likes | Likes |
| comments | Comments |
| new_followers_added | New followers added |
| retweets | Retweets |
| single_moment_total_likes | Single moment total likes |
| single_moment_total_comments | Single moment total comments |
| single_moment_total_retweets | Single moment total retweets |
Note: ad_type=('image_ads', 'text_ads', 'video_ads', 'carousel_ads', 'moment_ads')
# With shell, you can just pass the correct header with each request
curl --request POST 'https://api.brandops.io/customer/api/ads/channel/twitter?customer_name=Test-Customer&month=9&year=2022' \
--header 'brandops-access-token: your-access-token -d {POST_BODY}'
POST json body structure:
{
"customer_name": null,
"scored_month": null,
"ad_identifier": null,
"ad_type": null,
"ad_format": null,
"spend": null,
"impressions": null,
"clicks": null,
"click_through_rate": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"likes": null,
"comments": null,
"new_followers_added": null,
"retweets": null
}
Read Twitter Ads (GET)
API to get saved twitter ads from the database.
HTTP Request
GET https://api.brandops.io/customer/api/ads/channel/twitter
Query Parameters
Note: Either provide start_date/end_date or month/year to get ads for a time range.
| Parameter | Description |
|---|---|
| customer_name | Customer name |
| start_date | Start date |
| end_date | End date |
| month | Month |
| year | Year |
NOTE: Please pass brandops-access-token in the request header.
# With shell, you can just pass the correct header with each request
curl --request GET 'https://api.brandops.io/customer/api/ads/channel/twitter?customer_name=Test-Customer&month=9&year=2022' \
--header 'brandops-access-token: your-access-token'
The above command returns JSON structured like this:
[
{
"ad_identifier": "",
"ad_type": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"click_through_rate": null,
"clicks": null,
"comments": null,
"created_at": "Fri, 16 Sep 2022 17:03:00 GMT",
"id": 1,
"impressions": null,
"likes": null,
"new_followers_added": null,
"retweets": null,
"scored_month": "Fri, 30 Sep 2022 00:00:00 GMT",
"single_moment_total_comments": null,
"single_moment_total_likes": null,
"single_moment_total_retweets": null,
"spend": null,
"updated_at": "Fri, 16 Sep 2022 17:03:00 GMT",
"video_average_cost_per_view": null,
"video_view_through_rate": null,
"video_views": null
}
]
Update Twitter Ads (UPDATE)
API to update Twitter Ads properties. When a PUT request is performed, the properties of the request body are read, and if the resource has a property with the same name the property of the resource will be set to the new value.
HTTP Request
PUT https://api.brandops.io/customer/api/ads/channel/twitter/<id>
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | customer_name |
NOTE: Please pass brandops-access-token in the request header.
Request json body structure:
{
"ad_identifier": "",
"ad_type": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"click_through_rate": null,
"clicks": null,
"comments": null,
"impressions": null,
"likes": null,
"new_followers_added": null,
"retweets": null,
"single_moment_total_comments": null,
"single_moment_total_likes": null,
"single_moment_total_retweets": null,
"spend": null,
"video_average_cost_per_view": null,
"video_view_through_rate": null,
"video_views": null
}
Delete Twitter Ads (DELETE)
Resources are deleted by sending an HTTP DELETE request to the URL that the resource is located at. This is the URL that contains the id of the resource.
HTTP Request
DELETE https://api.brandops.io/customer/api/ads/channel/twitter/<id>
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | customer_name |
NOTE: Please pass brandops-access-token in the request header.
Notes
- Currently there are no rate limits for this API.
Changelog
- 20 September 2022: Added APIs
Youtube Ads
Add Youtube Ads (POST)
Add new youtube ads by sending HTTP POST requests to the API.
HTTP Request
POST https://api.brandops.io/customer/api/ads/channel/youtube
NOTE: Please pass brandops-access-token in the request header.
POST body to add youtube skippable in stream ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | scored month |
| ad_identifier | Ad identifier |
| ad_type | "skippable_in_stream_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click through rate |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| views | Views |
| view_through_rate | View through rate |
| video_completion_rate | Video completion rate |
| interactions | Interactions |
| average_cost_per_view | Average cost per view |
| views_from_impressions | Views from impressions |
| average_view_duration | Average view duration |
| watch_time_from_impressions | Watch time from impressions |
POST body to add youtube non skippable in stream ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | Ad identifier |
| ad_type | "non_skippable_in_stream_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click through rate |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| views | Views |
| interactions | Interactions |
POST body to add youtube bumber ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | Ad identifier |
| ad_type | "bumber_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click through rate |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| views | Views |
| interactions | Interactions |
POST body to add in feed video ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | Ad identifier |
| ad_type | "in_feed_video_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click through rate |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| youtube_serp_ranking_paid | Youtube serp ranking paid |
POST body to add masthead ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | Ad identifier |
| ad_type | "masthead_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click through rate |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
POST body to addo verlay ads
| Parameter | Description |
|---|---|
| customer_name | The name of customer accessing the API. |
| scored_month | Scored month |
| ad_identifier | Ad identifier |
| ad_type | "overlay_ads" |
| spend | Spend |
| impressions | Impressions |
| clicks | Clicks |
| click_through_rate | Click through rate |
| average_cost_per_click | Average cost per click |
| average_cost_per_mile | Average cost per mile |
| viewable_impressions | Viewable impressions |
Note: ad_type=('skippable_in_stream_ads', 'non_skippable_in_stream_ads', 'bumber_ads', 'in_feed_video_ads', 'masthead_ads', 'overlay_ads')
# With shell, you can just pass the correct header with each request
curl --request POST 'https://api.brandops.io/customer/api/ads/channel/youtube?customer_name=Test-Customer&month=9&year=2022' \
--header 'brandops-access-token: your-access-token -d {POST_BODY}'
POST json body structure:
{
"ad_identifier": "",
"ad_type": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"click_through_rate": null,
"clicks": null,
"comments": null,
"impressions": null,
"likes": null,
"new_followers_added": null,
"retweets": null,
"single_moment_total_comments": null,
"single_moment_total_likes": null,
"single_moment_total_retweets": null,
"spend": null,
"video_average_cost_per_view": null,
"video_view_through_rate": null,
"video_views": null
}
Read Youtube Ads (GET)
API to get saved youtube ads from the database.
HTTP Request
GET https://api.brandops.io/customer/api/ads/channel/youtube
Query Parameters
Note: Either provide start_date/end_date or month/year to get ads for a time range.
| Parameter | Description |
|---|---|
| customer_name | Customer name |
| start_date | Start date |
| end_date | End date |
| month | Month |
| year | Year |
NOTE: Please pass brandops-access-token in the request header.
# With shell, you can just pass the correct header with each request
curl --request GET 'https://api.brandops.io/customer/api/ads/channel/youtube?customer_name=Test-Customer&month=9&year=2022' \
--header 'brandops-access-token: your-access-token'
The above command returns JSON structured like this:
[
{
"ad_identifier": "",
"ad_type": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"click_through_rate": null,
"clicks": null,
"comments": null,
"created_at": "Fri, 16 Sep 2022 17:03:00 GMT",
"id": 1,
"impressions": null,
"likes": null,
"new_followers_added": null,
"retweets": null,
"scored_month": "Fri, 30 Sep 2022 00:00:00 GMT",
"single_moment_total_comments": null,
"single_moment_total_likes": null,
"single_moment_total_retweets": null,
"spend": null,
"updated_at": "Fri, 16 Sep 2022 17:03:00 GMT",
"video_average_cost_per_view": null,
"video_view_through_rate": null,
"video_views": null
}
]
Update Youtube Ads (UPDATE)
API to update Youtube Ads properties. When a PUT request is performed, the properties of the request body are read, and if the resource has a property with the same name the property of the resource will be set to the new value.
HTTP Request
PUT https://api.brandops.io/customer/api/ads/channel/youtube/<id>
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | customer_name |
NOTE: Please pass brandops-access-token in the request header.
Request json body structure:
{
"ad_identifier": "",
"ad_type": null,
"average_cost_per_click": null,
"average_cost_per_mile": null,
"click_through_rate": null,
"clicks": null,
"comments": null,
"impressions": null,
"likes": null,
"new_followers_added": null,
"retweets": null,
"scored_month": "Fri, 30 Sep 2022 00:00:00 GMT",
"single_moment_total_comments": null,
"single_moment_total_likes": null,
"single_moment_total_retweets": null,
"spend": null,
"video_average_cost_per_view": null,
"video_view_through_rate": null,
"video_views": null
}
Delete Youtube Ads (DELETE)
Resources are deleted by sending an HTTP DELETE request to the URL that the resource is located at. This is the URL that contains the id of the resource.
HTTP Request
DELETE https://api.brandops.io/customer/api/ads/channel/youtube/<id>
Query Parameters
| Parameter | Description |
|---|---|
| customer_name | customer_name |
NOTE: Please pass brandops-access-token in the request header.
Notes
- Currently there are no rate limits for this API.
Changelog
- 20 September 2022: Added APIs
Errors
The BrandOps API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 403 | Forbidden -- The API requested is hidden for administrators only. |
| 404 | Not Found -- The specified API could not be found. |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |