Note: This feature is only available to users with an Agency plan. We are not able to provide support for API development or implementation beyond this documentation.

Further Note:  Version 1 of the API is no longer being updated. Please consider migrating your application to Version 2 (beta).


 

Overview

Our API provides read-only access to review data for thousands of businesses and is used to power review widgets and reputation management dashboards for many different applications. We also have a growing number of endpoints used for automating common tasks such as sending email campaigns and onboarding new client accounts. To use our API, you will need a subscription plan that includes API access.

Note that this API is not intended for use in loading data on-the-fly into a page on every page load, and therefore we don’t support cross-origin Javascript requests typical of such applications. Our expectation is that your API integration will make use of your own local storage and/or caching of the data so as not to overburden our resources, similar to the implementation our WordPress, Joomla and Drupal plugins/modules.

Authentication

API Token. Read-only GET requests and certain non-destructive actions use simple authentication with an API token. Your API token should then be passed with each GET or POST request as an “Authorization: Token” HTTP header.

Signed Request. More sensitive actions such as account management will require your requests to be signed with a hash of the request data using your API secret, a security technique popularized by Amazon.

Both your API token and API secret should be treated as passwords and should be kept secret at all times. API tokens are readily retrievable via the “My Account” tab when you login. API secrets are shown once and never again–if you lose your API secret, you will need to generate a new one. Generating a new API token or secret will invalidate any previous ones.

Example Code

A simple PHP example class for making API calls:

<?php

class GradeUsApi {

  const URL = 'https://www.grade.us/api/v1';

  function __construct($profile_id, $token, $secret = NULL) {
    $this->profile_id = $profile_id;
    $this->token = $token;
    $this->secret = $secret;
  }
  
  function doRequest($endpoint, $data, $method, $signRequest = false) {
    
    // Use this profile ID:
    $data['profile_id'] = $this->profile_id;
    
    // Init CURL:
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    
    // Add auth token:
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Accept: application/json', 'Authorization: Token token='.$this->token));
    
    // Sign request if necessary:
    if ($signRequest) {
      /* -------------------------------------------------------
        Sign a request by including a hash of the request data
        serialized, encoded and in key order
      ------------------------------------------------------- */
      ksort($data);
      $request_data = array();
      foreach ($data as $key => $value) {
        $key = str_replace("%7E", "~", rawurlencode($key));
        $value = str_replace("%7E", "~", rawurlencode($value));
        $request_data[] = $key . '=' . $value;
      }
      $signed_str = implode('&', $request_data);
      $signature = base64_encode(hash_hmac('sha256', $signed_str, $this->secret, true));
      $data['hash'] = $signature;
    }
    
    // Build the query:
    $query = '';
    switch($method) {
      case 'GET':
        $query = '/' . $endpoint . '/' . $this->profile_id . '?' . http_build_query($data);
        break;
      case 'POST':
        $query = '/' . $endpoint;
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        break;
    }
    // Strip double slashes and setup URL:
    while (strpos($query, '//') > -1) {
      $query = str_replace('//', '/', $query);
    }
    curl_setopt($ch, CURLOPT_URL, self::URL.$query);

    // Execute CURL and close:
    $response = curl_exec($ch);
    curl_close($ch);

    // Decode JSON and return:
    return json_decode($response, true);

  }
    
}

?>

And an example showing how to use it:

<?php

$profile_id = 'some path or profile ID';
$token = 'your token';
$secret = 'your secret';
$api = new GradeUsApi($profile_id, $token, $secret);

$response = $api->doRequest('customers/create', array(
  'email_address' => 'johndoe@example.com',
  'first_name' => 'John',
  'last_name' => 'Doe'
), 'POST', true);
print_r($response);

?>

You can also download some functional examples here.

API Endpoints


GET /v1/reviews

GET /v1/reviews or GET /v1/reviews/{path} (Authentication: API token)

This endpoint retrieves all reviews collected for the Grade.us business or individual profile at {path} or {profile_id}.

Parameter Default Description
path or profile_id NULL Required.
stream true By default, the result includes ONLY reviews flagged for publication in the review stream for that profile. If set to false, the result will include all reviews for the profile.
exclude NULL Channels to exclude from the results.
include NULL Channels to include in the results, excluding all others.
count Number of reviews to be returned. (Max: 50)
offset 0 Number of reviews to skip.

How do I find a profile ID? While either the path (e.g. “yourname” in https://www.grade.us/yourname) or profile ID will work for identifying a profile in your API calls, a profile ID may be preferred since it does not change. To find the profile ID for a given profile, navigate to almost any page of our Dashboard and find it under the “breadcrumbs” at top right:

breadcrumbs

Example response

{
  "name": "The Business Name",
  "reviews_count": 95,
  "ratings_count": 93,
  "ratings_average": 4.6,
  "ratings_max": 5,
  "reviews_shown": 40,
  "reviews": [
    {
      "uuid": "5e16176d-d213-4b39-b19a-27bc0284d844",
      "date": "2015-09-29",
      "rating": 5,
      "attribution": "Janek Walenga",
      "snippet": "Absolutely amazing food! First generation Polish American living in Pompton Lakes and the hot lunches/dinners taste just like moms home made meals!",
      "category": "facebook",
      "url": "https://www.facebook.com/10153187193846732",
      "email_address": null,
      "ip_address": null,
      "response_status": null,
      "image_url": "https://uploads.reviewsoftware.com/sites/651b068c-c21e-11e2-9528-86a67ea064d5/c733ca80-9679-409f-8e30-f9782ce62342/reviews/5e16176d-d213-4b39-b19a-27bc0284d844/review.png?v=2017-01-11"
    },
    {
      "uuid": "e5f4f405-9ee0-43be-bfd8-c61e70aa50a6",
      "date": "2015-03-14",
      "rating": 5,
      "attribution": "Olga Petrusenko",
      "snippet": "Волшебный магазин! Очень вкусные торты! Обязательно к посещению!",
      "category": "facebook",
      "url": "https://www.facebook.com/10204982797902847",
      "email_address": null,
      "ip_address": null,
      "response_status": null,
      "image_url": "https://uploads.reviewsoftware.com/sites/651b068c-c21e-11e2-9528-86a67ea064d5/c733ca80-9679-409f-8e30-f9782ce62342/reviews/e5f4f405-9ee0-43be-bfd8-c61e70aa50a6/review.png?v=2017-01-11"
    },
    {
      "uuid": "702a2907-936f-438d-8f5a-833c1b124059",
      "date": "2015-03-01",
      "rating": 5,
      "attribution": "Robert Butka",
      "snippet": "We have been shopping here since the opened and varieties of Kielbasa from fresh to smoked to Pierogis and Golumpkis are the best. We love getting the small...",
      "category": "facebook",
      "url": "https://www.facebook.com/10200212759718520",
      "email_address": null,
      "ip_address": null,
      "response_status": null,
      "image_url": "https://uploads.reviewsoftware.com/sites/651b068c-c21e-11e2-9528-86a67ea064d5/c733ca80-9679-409f-8e30-f9782ce62342/reviews/702a2907-936f-438d-8f5a-833c1b124059/review.png?v=2017-01-11"
    }
    ...
  ]
}

GET /v1/ratings

GET /v1/ratings or GET /v1/ratings/{path} (Authentication: API token)

This endpoint retrieves aggregated ratings and ratings distributions for the Grade.us business or individual profile at {path} or {profile_id}.

Parameter Default Description
path or profile_id NULL Required.

Example response

{
  "name": "The Business Name",
  "ratings": {
    "sites": [
      {
        "category": "avvo",
        "reviews_count": 4,
        "aggregate_rating": 4,
        "ratings": [1, 5, 5, 5],
        "most_recent_activity_date": "2015-10-04",
        "likes_count": 0,
        "checkins_count": 0,
        "is_listed": true,
        "is_claimed": null,
        "is_verified": null,
        "is_closed": null,
        "is_monitored": true,
        "url": "https://www.avvo.com/attorneys/PAGE_ID.html"
      },
      {
        "category": "facebook",
        "reviews_count": 41,
        "aggregate_rating": 4.853658536585366,
        "ratings": [4, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 4, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 4, 5, 5, 5, 5, 5, 2, 5, 5],
        "most_recent_activity_date": "2016-06-15",
        "likes_count": 0,
        "checkins_count": 0,
        "is_listed": true,
        "is_claimed": null,
        "is_verified": null,
        "is_closed": null,
        "is_monitored": true,
        "url": "https://www.facebook.com/pages/PAGE_ID"
      },
      ...
    ],
    "distributions": {
      "sentiment": {
        "positive": 86,
        "neutral": 1,
        "negative": 6
      },
      "stars": {
        "one": 4,
        "two": 2,
        "three": 1,
        "four": 16,
        "five": 70
      }
    }
  }
}

POST /v1/profiles/:profile_id/recipients

POST /v1/profiles/:profile_id/recipients [deprecated: POST /v1/customers/create] (Authentication: API token)

POST an array of recipient attributes to trigger an email or SMS invite campaign to recipients

Parameter Type Description
recipients Array At least one recipient as JSON (Max: 50)

Recipient attributes

Parameter Default Description
first_name NULL Required. First name of the recipient.
last_name NULL Last name of the recipient.
email_address NULL Or phone_number required. Email address of the recipient.
phone_number NULL Or email_address required. Mobile phone number of the recipient.

Example request

{
  "recipients": [
    {
      "email_address": "john@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    {
      "email_address": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe"
    }
  ]
}

Example response

{
  "status": 200,
  "result": [
    {
      "email_address": "john@example.com",
      "phone_number": null,
      "first_name": "John",
      "last_name": "Doe",
      "sent_count": 0,
      "started_at": "2016-12-09T10:32:15.160-05:00",
      "last_sent_at": null,
      "is_pending": false,
      "is_active": true,
      "is_archived": false,
      "rejected": false,
      "blocked": false,
      "bounced": false,
      "clicked": false,
      "flagged": false,
      "opened": false,
      "unsubscribed": false,
      "uuid": "cc932f7c-d680-11e6-b9c8-6c4008bcf9f4",
      "notices": "john@example.com has been added/updated."
    }
  ],
}

GET /v1/profiles/:profile_id/recipients

GET /v1/profiles/:profile_id/recipients/search [deprecated: GET /v1/customers/search] (Authentication: API token)

GET statuses on customer records and email/SMS invite campaigns for the business at {path} or {profile_id).

Parameter Default Description
path or profile_id NULL Required.
term NULL Term to search: must be an email or UUID.
limit 50 Number of records to be returned. (Max: 50)
offset 0 Number of records to skip.
archived false By default, the result does not include archived customers.

Example response

{
  "customers_total": 37,
  "customers": [
    {
      "email_address": "john@example.com",
      "phone_number": null,
      "first_name": "John",
      "last_name": "Doe",
      "sent_count": 0,
      "started_at": "2016-12-09T10:32:15.160-05:00",
      "last_sent_at": null,
      "is_pending": false,
      "is_active": true,
      "is_archived": false,
      "rejected": false,
      "blocked": false,
      "bounced": false,
      "clicked": false,
      "flagged": false,
      "opened": false,
      "unsubscribed": false,
      "uuid": "cc932f7c-d680-11e6-b9c8-6c4008bcf9f4",
      "notices": "john@example.com has been added/updated."
    },
    {
      "email_address": "jane@example.com",
      "phone_number": null,
      "first_name": "Jane",
      "last_name": "Doe",
      "sent_count": 0,
      "started_at": "2016-12-08T08:45:45.100-05:00",
      "last_sent_at": null,
      "is_pending": false,
      "is_active": true,
      "is_archived": false,
      "rejected": false,
      "blocked": false,
      "bounced": false,
      "clicked": false,
      "flagged": false,
      "opened": false,
      "unsubscribed": false,
      "uuid": "cc932f7c-d680-11e6-b9c8-6c4008bcf9f4",
      "notices": "john@example.com has been added/updated."
    },
    ...
  ],
}

POST /v1/profiles

POST /v1/profiles/create (Authentication: Signed request)


POST parameters such as business name and URL shortname:

Parameter Default Description
name NULL Required. The business name (can be changed later).
shortname NULL The preferred shortname to be used in the profile URL. Depends on availability.
domain grade.us The domain where the profile will live.
domain_type none The domain type: “none”, “own” or “cname”.