API reference

The ReviewWheel API lets your job software tell ReviewWheel when a job is done. ReviewWheel then sends that customer a review request.

  • Base URL: https://api.reviewwheel.com
  • Format: JSON request and response bodies.
  • OpenAPI 3.1: reviewwheel.com/openapi.json
  • MCP server: https://api.reviewwheel.com/mcp. Add it to Claude or ChatGPT as a connector, then sign in with your ReviewWheel login. Setup steps

Give this to your agent

  • Claude
  • OpenAI
  • Grok
  • Gemini

Your agent follows our setup skill. You create the API key and keep it out of the chat.

Install and set up https://reviewwheel.com/skill.md

Get an API key

An owner or an admin creates the key in the app, on the Webhook connection page. The key starts with rwk_live_. The app shows it one time, so store it in a secret store or an environment variable.

KindScopelocationId on each job
Account keyEvery location on the accountRequired
Location keyOne locationNot needed

Before the first account key, the owner confirms that they have consent to message their customers. Only the owner can give that confirmation.

Authenticate

Send the key in the Authorization header on every request:

Authorization: Bearer rwk_live_...

The API answers only while the account has an active plan or trial.

Endpoints

GET /api/v1/ping

Checks the key. Zapier uses this call to test a connection.

curl https://api.reviewwheel.com/api/v1/ping \
  -H "Authorization: Bearer $REVIEWWHEEL_API_KEY"
{
  "ok": true,
  "keyName": "Office key",
  "kind": "company",
  "companyName": "Example Plumbing",
  "locationName": null
}

kind is company for an account key and location for a location key. locationName is set only for a location key.

GET /api/v1/locations

Lists the locations the key can send jobs to. An account key lists the account's locations, sorted by name. A location key lists its one location.

curl https://api.reviewwheel.com/api/v1/locations \
  -H "Authorization: Bearer $REVIEWWHEEL_API_KEY"
[
  {
    "id": "<location id>",
    "name": "Example Plumbing",
    "city": "Atlanta",
    "state": "GA",
    "status": "live"
  }
]

Use an id from this list as locationId. city and state are null when the location has none.

POST /api/v1/job-completed

Reports a finished job. ReviewWheel saves the customer as a contact and starts the location's review request sequence.

This call can text or email a real customer. Send only finished jobs, and only for customers who agreed to hear from the business.

# Prints the JSON body. On an error it holds "code" and "error".
curl -sS -X POST https://api.reviewwheel.com/api/v1/job-completed \
  -H "Authorization: Bearer $REVIEWWHEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: job-10482" \
  -d '{
    "locationId": "<location id>",
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "+14045550123",
    "email": "[email protected]",
    "jobType": "Water heater install",
    "completedAt": "2026-10-28T15:00:00Z"
  }'
// Node 18 or later, as an ES module (job.mjs).
const res = await fetch("https://api.reviewwheel.com/api/v1/job-completed", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.REVIEWWHEEL_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "job-10482",
  },
  body: JSON.stringify({
    locationId: "<location id>",
    firstName: "Jane",
    lastName: "Doe",
    phone: "+14045550123",
    email: "[email protected]",
    jobType: "Water heater install",
    completedAt: "2026-10-28T15:00:00Z",
  }),
});
const body = await res.json();
if (res.status !== 200) {
  console.error(`${res.status} ${body.code}: ${body.error}`);
} else {
  console.log(body);
}
# pip install requests
import os
import requests

res = requests.post(
    "https://api.reviewwheel.com/api/v1/job-completed",
    headers={
        "Authorization": f"Bearer {os.environ['REVIEWWHEEL_API_KEY']}",
        "Idempotency-Key": "job-10482",
    },
    json={
        "locationId": "<location id>",
        "firstName": "Jane",
        "lastName": "Doe",
        "phone": "+14045550123",
        "email": "[email protected]",
        "jobType": "Water heater install",
        "completedAt": "2026-10-28T15:00:00Z",
    },
    timeout=30,
)
body = res.json()
if res.status_code != 200:
    print(f"{res.status_code} {body['code']}: {body['error']}")
else:
    print(body)
FieldTypeRule
locationIdstringRequired with an account key. Ignored with a location key.
phonestringSend phone, email or both. At least one must be usable.
emailstringSee phone.
firstName, lastNamestringOptional.
addressstringOptional. The job's street address.
jobTypestringOptional.
completedAtISO 8601 string or epoch numberOptional. When the job was done.

A success returns 200:

{
  "ok": true,
  "contactId": "<contact id>",
  "enrolled": true,
  "held": null
}
  • warnings: present when ReviewWheel dropped a phone or email it could not use. The contact still saves with the other channel.
  • held: "paused": the account paused requests. The job saves and waits.
  • deduped: true: this Idempotency-Key was already used. Nothing new happened.
  • stale: true with enrolled: false: the job is too old for a review request.

Deduplication

Send an Idempotency-Key header with a stable value for each job, for example your job ID. If you retry the same job with the same value, ReviewWheel does not create it again.

An account key checks the value across the whole account. A location key checks it within its one location. A blank header counts as no header.

Errors

Every error body has the same three fields. error is one sentence for a person to read. The errors below are grouped by what you do next.

{
  "ok": false,
  "code": "location-unknown",
  "error": "That location is not on this ReviewWheel account."
}

Fix the key

StatuscodeWhat to do
401 invalid-key The key is wrong, revoked or missing. Check it or create a new one. Do not retry with the same key.

Pick or renew a plan

StatuscodeWhat to do
403 no-plan The account has no active plan. The owner picks a plan in the app.
403 service-ineligible That location has no active plan.
403 product-required That location needs a product it does not have. Give the owner the checkoutUrl from the error body. Never state a price. A null checkoutUrl means the location is paused: the owner resumes it in the app.

Ask the owner

StatuscodeWhat to do
403 approver-required Profile changes need an account key made by an owner or admin. The owner creates one.
409 source-conflict Another job source is connected for that location. The owner disconnects it in the app first.
428 confirm-required Run the call with dryRun: true, show the owner the preview, then send its previewId with the same fields within 10 minutes.

Fix the request

StatuscodeWhat to do
400 invalid-body Send a JSON object.
404 location-unknown locationId is not on this account. Call /api/v1/locations.
422 invalid-field Fix the field that error names.
422 location-required An account key needs locationId on each job.
422 no-contact Send a usable phone or email.
404 request-unknown That requestId is not on this account. Use the requestId that job-completed returned.
404 not-found No route matches the path. Check it against openapi.json.
404 change-not-found That changeId is not on this account. Use the changeId that profile-changes returned.
409 not-applied The change was never applied, so it has nothing to undo.
422 invalid-change Send 1 to 100 locations and only the fields that error lists.
403 source-blocked completedAt is missing, or it is earlier than the location’s last job source change. Send completedAt for jobs finished after that change.

Wait and retry

StatuscodeWhat to do
429 rate-limited Wait the number of seconds in Retry-After, then retry.
409 company-busy Another profile change on this account is still running. Wait the number of seconds in Retry-After, then retry.
503 provider-state-changed Try again later.
503 no-template Try again later.

Zapier

The ReviewWheel Zapier app needs no API key. You connect it by signing in to ReviewWheel. Its Send Review Request action calls POST /api/v1/job-completed. See ReviewWheel on Zapier.

To deduplicate in Zapier, map both Deduplication Source and Deduplication Key, or neither. The action sends them as Idempotency-Key: <source>:<key>, with the source URL-encoded, so jobs from two systems cannot collide.

What the API cannot do

The API cannot create an account, add a location, change a plan, take a payment, read or reply to reviews, or change a Google Business Profile. The owner does these things in the app.

Revoke a key

The owner revokes a key on the same Webhook connection page. A 401 on a key that worked before means the key is revoked. Create a new key and replace the old one.

Help

10 days free · 30-day money-back · Cancel anytime

Book more jobs →