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

  1. Sign in to the dashboard and open Reviews MCP & API (in the side menu, under Grades.com AI).
  2. Create a key: give it a name, pick the businesses it may see and the scopes it needs. For this guide: companies:read, reviews:read and, for the webhook step, reviews:write.
  3. 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.

Check your key: who am I
export GRADES_API_KEY="gk_live_YOUR_KEY"

curl https://app.grades.com/api/v1/me \
  -H "Authorization: Bearer $GRADES_API_KEY"

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.

Your locations
curl https://app.grades.com/api/v1/companies \
  -H "Authorization: Bearer $GRADES_API_KEY"

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.

Low-rated reviews without a reply
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"

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.

Register a webhook endpoint
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"
  }'

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:

Check the signature of a delivery
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));
}

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.

Next steps