Developers
Quickstart: your first API call
Create a key, read your locations and reviews, and get a signed webhook when a new review arrives. Every step has code in curl, JavaScript, Python and PHP.
1. Create a secret key
- Sign in to the dashboard and open Reviews MCP & API (in the side menu, under Grades.com AI).
- Create a key: give it a name, pick the businesses it may see and the scopes it needs. For this guide:
companies:read,reviews:readand, for the webhook step,reviews:write. - Copy the key (
gk_live_...). It is shown once and stored only as a hash, so keep it in a secret store or an environment variable, never in a web page or a public repository.
The key acts as you: it reaches only the businesses you are a member of and picked for it, with the scopes you gave it. Scopes, OAuth and publishable keys: Authentication.
2. Make your first call
Every request goes to https://app.grades.com/api/v1 with the key in the Authorization header. GET /v1/me answers with your user, so it is the quickest check that the key works.
export GRADES_API_KEY="gk_live_YOUR_KEY" curl https://app.grades.com/api/v1/me \ -H "Authorization: Bearer $GRADES_API_KEY"
// Node.js 18 or later (built-in fetch). Run with GRADES_API_KEY set.
const API = 'https://app.grades.com/api/v1';
const headers = { Authorization: `Bearer ${process.env.GRADES_API_KEY}` };
const res = await fetch(`${API}/me`, { headers });
const body = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${body.detail}`);
console.log(body.data);# pip install requests; run with GRADES_API_KEY set
import os
import requests
API = "https://app.grades.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['GRADES_API_KEY']}"}
r = requests.get(f"{API}/me", headers=headers, timeout=30)
r.raise_for_status()
print(r.json()["data"])<?php
// composer require guzzlehttp/guzzle; run with GRADES_API_KEY set
require 'vendor/autoload.php';
$grades = new GuzzleHttp\Client([
'base_uri' => 'https://app.grades.com/api/v1/',
'headers' => ['Authorization' => 'Bearer ' . getenv('GRADES_API_KEY'), 'Accept' => 'application/json'],
]);
$me = json_decode((string) $grades->get('me')->getBody(), true);
print_r($me['data']);A wrong or revoked key answers 401 with a problem details body; see Errors. The next samples reuse API and headers (or $grades) from this one.
3. List your locations and their reviews
GET /v1/companies lists the businesses (locations) the key can see. Each has a uuid: the id every company endpoint takes.
curl https://app.grades.com/api/v1/companies \ -H "Authorization: Bearer $GRADES_API_KEY"
const res = await fetch(`${API}/companies`, { headers });
const { data: companies } = await res.json();
for (const c of companies) console.log(c.uuid, c.name);r = requests.get(f"{API}/companies", headers=headers, timeout=30)
r.raise_for_status()
for c in r.json()["data"]:
print(c["uuid"], c["name"])$companies = json_decode((string) $grades->get('companies')->getBody(), true)['data'];
foreach ($companies as $c) {
echo $c['uuid'], ' ', $c['name'], PHP_EOL;
}Then read the reviews of one location. Filters such as min_rating, max_rating, has_company_response, start_date and source_drivers combine; this one asks for reviews of 1 or 2 stars that have no reply yet.
curl -G https://app.grades.com/api/v1/companies/COMPANY_UUID/reviews \ -H "Authorization: Bearer $GRADES_API_KEY" \ --data-urlencode "max_rating=2" \ --data-urlencode "has_company_response=false" \ --data-urlencode "limit=10"
const company = 'COMPANY_UUID'; // a uuid from /v1/companies
const query = new URLSearchParams({ max_rating: '2', has_company_response: 'false', limit: '10' });
const res = await fetch(`${API}/companies/${company}/reviews?${query}`, { headers });
const { data: reviews, meta } = await res.json();
for (const r of reviews) console.log(r.rating, r.site, r.published_at, r.text);
console.log('more?', meta.has_more, meta.next_cursor);company = "COMPANY_UUID" # a uuid from /v1/companies
params = {"max_rating": 2, "has_company_response": "false", "limit": 10}
r = requests.get(f"{API}/companies/{company}/reviews", headers=headers, params=params, timeout=30)
r.raise_for_status()
page = r.json()
for review in page["data"]:
print(review["rating"], review["site"], review["published_at"], review["text"])
print("more?", page["meta"]["has_more"], page["meta"]["next_cursor"])$company = 'COMPANY_UUID'; // a uuid from /v1/companies
$res = $grades->get("companies/$company/reviews", [
'query' => ['max_rating' => 2, 'has_company_response' => 'false', 'limit' => 10],
]);
$page = json_decode((string) $res->getBody(), true);
foreach ($page['data'] as $r) {
echo $r['rating'], ' ', $r['site'], ' ', $r['published_at'], ' ', $r['text'], PHP_EOL;
}Lists come in pages: meta.has_more says whether there is another page and meta.next_cursor fetches it (Pagination). A review from Yelp comes without its text unless you send yelp_consent=true and the business has recorded its consent; OAuth apps never get it. The fields are then null, with text_policy and a text_notice that says why.
4. Get a webhook when a review arrives
Instead of polling, register an HTTPS endpoint with POST /v1/webhooks (scope reviews:write; webhooks come with the Pro and Premium plans, and a Starter business answers 402). The answer carries the signing secret (whsec_...), shown only this once.
curl https://app.grades.com/api/v1/webhooks \
-H "Authorization: Bearer $GRADES_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/grades/webhook",
"events": ["review.created", "review.replied"],
"company": "COMPANY_UUID"
}'const res = await fetch(`${API}/webhooks`, {
method: 'POST',
headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({
url: 'https://example.com/grades/webhook',
events: ['review.created', 'review.replied'],
company: 'COMPANY_UUID',
}),
});
const { data: endpoint } = await res.json();
// Store endpoint.secret now (whsec_...): it is shown only in this answer.
console.log(res.status, endpoint.secret);r = requests.post(f"{API}/webhooks", headers=headers, timeout=30, json={
"url": "https://example.com/grades/webhook",
"events": ["review.created", "review.replied"],
"company": "COMPANY_UUID",
})
r.raise_for_status()
endpoint = r.json()["data"]
# Store endpoint["secret"] now (whsec_...): it is shown only in this answer.
print(r.status_code, endpoint["secret"])$res = $grades->post('webhooks', ['json' => [
'url' => 'https://example.com/grades/webhook',
'events' => ['review.created', 'review.replied'],
'company' => 'COMPANY_UUID',
]]);
$endpoint = json_decode((string) $res->getBody(), true)['data'];
// Store $endpoint['secret'] now (whsec_...): it is shown only in this answer.
echo $res->getStatusCode(), ' ', $endpoint['secret'], PHP_EOL;Each delivery is a JSON POST signed with that secret in X-Grades-Signature. Check it against the raw body before you trust the payload, and answer with any 2xx within 5 seconds:
import crypto from 'node:crypto';
// rawBody: the request body exactly as received (a string, before JSON.parse)
// header: the X-Grades-Signature header, "t=<unix seconds>,v1=<hex>"
export function isFromGrades(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(String(header).split(',').map((pair) => pair.split('=', 2)));
if (!parts.t || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false;
const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
return expected.length === parts.v1.length
&& crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}import hashlib
import hmac
import time
def is_from_grades(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
"""raw_body: the request body exactly as received; header: X-Grades-Signature."""
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
if "t" not in parts or "v1" not in parts:
return False
if abs(time.time() - int(parts["t"])) > tolerance:
return False
signed = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])<?php
// $rawBody = file_get_contents('php://input');
// $header = $_SERVER['HTTP_X_GRADES_SIGNATURE'] ?? '';
function is_from_grades(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
$parts = [];
foreach (explode(',', $header) as $pair) {
[$key, $value] = array_pad(explode('=', $pair, 2), 2, null);
$parts[$key] = $value;
}
if (empty($parts['t']) || empty($parts['v1']) || abs(time() - (int) $parts['t']) > $tolerance) {
return false;
}
$expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
return hash_equals($expected, $parts['v1']);
}Not ready for a server yet? GET /v1/webhooks/samples?event=review.created&company=COMPANY_UUID returns sample bodies in the exact delivery shape. Events, retries and headers: Webhooks.
Try it in Postman, Insomnia or Bruno
Every operation is in the OpenAPI description at https://www.grades.com/openapi.json. In Postman choose Import, then Link, and paste that address; Insomnia and Bruno import the same file (Import > From URL or as a file). Set the collection's auth to Bearer token with your key.
Or try requests in the browser: the API reference has a Test request button on every operation.