NAV
shell

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": "Thu, 30 Sep 2021 12:00:00 GMT"
        }],
        "channel_scores": [{
            "channel_category_id": 1,
            "name": "Social",
            "score": 1,
            "score_at": "Thu, 30 Sep 2021 12:00:00 GMT"
        },
            {
                "channel_category_id": 2,
                "name": "Product Reviews",
                "score": 1,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT"
            },
            {
                "channel_category_id": 4,
                "name": "Blogs",
                "score": 1,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT"
            },
            {
                "channel_category_id": 5,
                "name": "News",
                "score": 1,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT"
            },
            {
                "channel_category_id": 6,
                "name": "Videos",
                "score": 1,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT"
            },
            {
                "channel_category_id": 7,
                "name": "Email Campaigns",
                "score": 0.0,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT"
            },
            {
                "channel_category_id": 9,
                "name": "Podcast",
                "score": 1.0,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT"
            },
            {
                "channel_category_id": 10,
                "name": "Webinar",
                "score": 0.0,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT"
            },
            {
                "channel_category_id": 12,
                "name": "Web Analytics",
                "score": 0.0,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT"
            },
            {
                "channel_category_id": 13,
                "name": "Web",
                "score": 1.0,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT"
            },
            {
                "channel_category_id": 14,
                "name": "Surveys via BrandOps",
                "score": 0.0,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT"
            },
            {
                "channel_category_id": 15,
                "name": "Emails",
                "score": 0.0,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT"
            },
            {
                "channel_category_id": 19,
                "name": "Employer Reviews",
                "score": 1.0,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT"
            }
        ],
        "company_id": 1,
        "company_name": "test-company",
        "company_url": "http://www.test.org",
        "created_at": "Mon, 28 Jun 2021 13:48:13 GMT",
        "description": "",
        "id": 1,
        "metric_values": [{
            "brand_metric_id": 1,
            "channel_name": "Emails",
            "is_percent": 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": 0
        },
            {
                "brand_metric_id": 2,
                "channel_name": "News",
                "is_percent": 0,
                "metric_label": "Backlink Mention Count, News",
                "metric_name": "news_backlink_mention_count",
                "score_type": "high_is_good",
                "site_name": "News Crawler",
                "stage_name": "Brand Presence",
                "value": 0
            },
            {
                "brand_metric_id": 3,
                "channel_name": "News",
                "is_percent": 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,
                "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": 1
            },
            {
                "brand_metric_id": 5,
                "channel_name": "Social",
                "is_percent": 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,
                "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": 0.0
            },
            {
                "brand_metric_id": 7,
                "channel_name": "Social",
                "is_percent": 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": 0.0
            },
            {
                "brand_metric_id": 10,
                "channel_name": "Videos",
                "is_percent": 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,
                "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,
                "metric_label": "SERP Rank, YouTube",
                "metric_name": "web_serp_rank_youtube",
                "score_type": "low_is_good",
                "site_name": "YouTube",
                "stage_name": "Brand Presence",
                "value": 1
            },
            {
                "brand_metric_id": 158,
                "channel_name": "Podcast",
                "is_percent": 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
            }
        ],
        "name": "test",
        "portfolio_id": "",
        "private_category_id": 1,
        "product_url": "http://www.test.org",
        "stage_scores": [{
            "brand_stage_id": 1,
            "score": 1,
            "score_at": "Thu, 30 Sep 2021 12:00:00 GMT",
            "stage_name": "Brand Presence"
        },
            {
                "brand_stage_id": 3,
                "score": 1,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT",
                "stage_name": "Brand Attention"
            },
            {
                "brand_stage_id": 5,
                "score": 1,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT",
                "stage_name": "Brand Reputation"
            },
            {
                "brand_stage_id": 6,
                "score": 1,
                "score_at": "Thu, 30 Sep 2021 12:00:00 GMT",
                "stage_name": "Brand Momentum"
            }
        ],
        "updated_at": "Mon, 28 Jun 2021 13:48:13 GMT"
    }]

This endpoint retrieves data for a specific category and month. For each brand in a category, the response will include:

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

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.