---
name: reviewwheel
description: Connect a home service business's job software or CRM to ReviewWheel so each finished job sends that customer a review request. Use when the owner asks to set up ReviewWheel, send review requests when jobs are done, or call the ReviewWheel API.
---

# ReviewWheel

ReviewWheel helps contractors book more jobs from Google. One part of it sends review requests: when a job is done, ReviewWheel texts or emails that customer a request for a Google review. This skill connects the owner's job software or CRM to that, through the ReviewWheel API.

## When to use

- The owner wants their job software or CRM to tell ReviewWheel when a job is done.
- The owner asks you to test or fix a ReviewWheel API connection.

Do not use the API to create an account, add a location, change a plan, take a payment, or reply to reviews. It cannot do those things. It changes a Google Business Profile only through `profile-changes`, after a dry run the owner confirms. The owner does them in the app at https://app.reviewwheel.com.

## Quick reference

- Base URL: `https://api.reviewwheel.com`
- Auth: `Authorization: Bearer $REVIEWWHEEL_API_KEY`. Keys start with `rwk_live_`.
- MCP: an AI app with MCP connectors can connect to `https://api.reviewwheel.com/mcp` instead. The person signs in with OAuth, and no key is needed. See https://reviewwheel.com/auth.md.
- `GET /api/v1/ping`: checks the key.
- `GET /api/v1/locations`: lists the locations the key can send jobs to.
- `POST /api/v1/job-completed`: reports a finished job. This can text or email a real customer. With `"dryRun": true` it saves and sends nothing and answers a preview with a `previewId`. The answer to a real call has the `requestId`.
- `GET /api/v1/plan`: lists which products each location has, with a checkout link for each one it lacks. Works without a plan.
- `GET /api/v1/profile-audit`: reads the facts from a location's newest free profile audit. Works without a plan.
- `GET /api/v1/rank/score`: reads a location's Rank score. Needs Rank.
- `GET /api/v1/reputation/stats`: reads a calendar month's review requests and new Google reviews per location. Needs Reputation.
- `GET /api/v1/reviews`: lists the newest Google reviews, as the Reviews page shows them. Works without a plan.
- `GET /api/v1/google-performance`: reads calls, website clicks and impressions from Google for one location and a date range. Needs Reputation or Rank.
- `POST /api/v1/requests/{requestId}/stop`: stops one review request. Its queued texts and emails are cancelled. Needs Reputation.
- `POST /api/v1/profile-changes`: sets the same Google Business Profile fields on one location or many. Run it with `"dryRun": true` first and show the owner the result. Needs Rank or the More Jobs Bundle, and an owner's or admin's account key.
- `GET /api/v1/profile-changes/{changeId}`: reads a profile change while Google checks or applies it.
- `POST /api/v1/profile-changes/{changeId}/undo`: puts back every location the change touched.
- Full rules, fields and errors: https://reviewwheel.com/auth.md
- OpenAPI 3.1: https://reviewwheel.com/openapi.json
- Human reference: https://reviewwheel.com/api

## Workflow

1. Read https://reviewwheel.com/auth.md and follow it. It is the source of truth for this API.
2. Have the owner create an API key on the Webhook connection page: https://app.reviewwheel.com/app/connections/webhook. The owner puts it in the `REVIEWWHEEL_API_KEY` environment variable or a secret store. Never ask the owner to paste the key into the chat. Never put it in code, logs or commits.
3. Call `GET /api/v1/ping` to test the key.
4. Call `GET /api/v1/locations`. If there is more than one location, ask the owner which to use. An account key needs that `id` as `locationId` on each job.
5. Find where the job software marks a job complete. From there, send `POST /api/v1/job-completed` with the customer's `phone` or `email`, the `locationId`, and an `Idempotency-Key` header set to the job's ID. Send only finished jobs, and only for customers who agreed to hear from the business. To check a job first, send it with `"dryRun": true` and show the owner the preview.
6. Send one test job with the owner's own phone or email. Show the owner the response.
7. Stop. Tell the owner what you set up and where.

## When a call fails

Every error body is `{"ok":false,"code":"<code>","error":"<one sentence>"}`. A 403 `product-required` body also has `product` and `checkoutUrl`: give the owner that link, and never state a price. A null `checkoutUrl` means the location is paused. Look up the code at `https://reviewwheel.com/api#error-<code>`. Two you will meet first:

- 401 `invalid-key`: the key is wrong, revoked or missing. Ask the owner to check it. Do not retry with the same key.
- 429 `rate-limited`: wait the number of seconds in `Retry-After`, then retry.
