{
  "openapi": "3.1.0",
  "info": {
    "title": "ReviewWheel API",
    "version": "1.0.0",
    "summary": "Send finished jobs to ReviewWheel so each customer gets a review request.",
    "description": "Human-readable reference: https://reviewwheel.com/api. Guide for AI agents: https://reviewwheel.com/auth.md. Without an active plan or trial, an API key can call the free routes (ping, locations, plan, profile audit, reviews); every other route refuses with `no-plan` or `product-required`. A canceled account refuses every route with `no-plan`.",
    "contact": {
      "name": "ReviewWheel support",
      "email": "support@reviewwheel.com",
      "url": "https://reviewwheel.com/api"
    },
    "termsOfService": "https://reviewwheel.com/terms"
  },
  "externalDocs": {
    "description": "API reference",
    "url": "https://reviewwheel.com/api"
  },
  "servers": [
    { "url": "https://api.reviewwheel.com" }
  ],
  "security": [
    { "apiKey": [] }
  ],
  "paths": {
    "/api/v1/ping": {
      "get": {
        "operationId": "ping",
        "x-mcp-tool": "get_account",
        "summary": "Check the connection",
        "description": "Returns the connection's name, its kind and the account name. `keyName` is the API key's name, or the AI app's name for an AI app sign-in. `kind` is `location` for a location key, which also sets `locationName`, and `company` for an account key or an AI app sign-in.",
        "responses": {
          "200": {
            "description": "The key works.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Ping" },
                "example": { "ok": true, "keyName": "Office key", "kind": "company", "companyName": "Example Plumbing", "locationName": null }
              }
            }
          },
          "401": { "$ref": "#/components/responses/InvalidKey" },
          "403": { "$ref": "#/components/responses/NoPlan" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/locations": {
      "get": {
        "operationId": "listLocations",
        "x-mcp-tool": "list_locations",
        "summary": "List the locations this connection reaches",
        "description": "Sorted by name. An account key lists the account's locations. An AI app sign-in lists the locations its person can open in ReviewWheel. A location key lists its one location. Other calls take an `id` as `locationId`.",
        "responses": {
          "200": {
            "description": "The locations.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Location" }
                },
                "example": [
                  { "id": "<location id>", "name": "Example Plumbing", "city": "Atlanta", "state": "GA", "status": "live" }
                ]
              }
            }
          },
          "401": { "$ref": "#/components/responses/InvalidKey" },
          "403": { "$ref": "#/components/responses/NoPlan" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/plan": {
      "get": {
        "operationId": "getPlan",
        "x-mcp-tool": "get_plan",
        "summary": "List which products each location has",
        "description": "Free: works without a plan. Per location, each product is `none`, `trial` or `full`. A product the location does not have carries `checkoutUrl`, the one page where the owner can buy it, or null when it has no such page or the location is paused. The answer has no prices.",
        "responses": {
          "200": {
            "description": "The products per location.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Plan" },
                "example": { "ok": true, "locations": [{ "id": "<location id>", "name": "Example Plumbing", "products": {
                  "reputation": { "state": "full", "checkoutUrl": null },
                  "rank": { "state": "none", "checkoutUrl": "https://app.reviewwheel.com/agent/checkout/rank?location=<location id>" },
                  "website": { "state": "none", "checkoutUrl": null },
                  "ads": { "state": "none", "checkoutUrl": null } } }] }
              }
            }
          },
          "401": { "$ref": "#/components/responses/InvalidKey" },
          "403": { "$ref": "#/components/responses/NoPlan" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/profile-audit": {
      "get": {
        "operationId": "getProfileAudit",
        "x-mcp-tool": "get_profile_audit",
        "summary": "Read a location's free profile audit",
        "description": "Free: works without a plan. Facts from the business's own Google Business Profile, from the newest free audit: photos, completeness and category scores (0 to 100), AI Search signals, and the profile's rating and review count. No competitor data. `audit` is null, with a `reason`, when no audit has run. This call never starts an audit.",
        "parameters": [
          { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required, except with a location key, which reads its own location." }
        ],
        "responses": {
          "200": {
            "description": "The newest audit's own-profile facts, or null when no audit has run.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProfileAudit" },
                "example": { "ok": true, "locationId": "<location id>", "audit": { "ranAt": "2026-10-14T15:02:11.000Z", "trade": "plumber", "photos": 60, "completeness": 67, "categorySpecificity": 100, "aiVisibility": { "score": 50, "signals": [{ "label": "Website linked", "ok": true }, { "label": "Hours listed", "ok": false }] }, "self": { "rating": 4.8, "reviewCount": 112 } } }
              }
            }
          },
          "401": { "$ref": "#/components/responses/InvalidKey" },
          "403": { "$ref": "#/components/responses/NoPlan" },
          "404": { "description": "That location is not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } },
          "422": { "description": "An account key sent no `locationId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error422LocationRequired" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/rank/score": {
      "get": {
        "operationId": "getRankScore",
        "x-mcp-tool": "get_rank_score",
        "summary": "Read a location's Rank score",
        "description": "The newest weekly SEO and AI Search score, the same number the Rank screen shows. Needs Rank on the location. `score` is null, with a `reason`, before the first scored week.",
        "parameters": [
          { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required, except with a location key, which reads its own location." }
        ],
        "responses": {
          "200": {
            "description": "The score, or null before the first scored week.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RankScore" },
                "example": { "ok": true, "locationId": "<location id>", "score": { "score": 48, "band": "red", "weekStart": "2026-10-19T00:00:00.000Z", "mapPart": 0.5, "aiPart": 0.25, "from": { "score": 21, "weekStart": "2026-08-17T00:00:00.000Z" }, "change": "Up 129%" } }
              }
            }
          },
          "401": { "$ref": "#/components/responses/InvalidKey" },
          "403": { "$ref": "#/components/responses/ProductRequired" },
          "404": { "description": "That location is not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } },
          "422": { "description": "An account key sent no `locationId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error422LocationRequired" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/reputation/stats": {
      "get": {
        "operationId": "getReputationStats",
        "x-mcp-tool": "get_reputation_stats",
        "summary": "Read review requests and reviews by month",
        "description": "For one calendar month, per location: review requests sent and new Google reviews, the same counts as the monthly report. Needs Reputation on the location. Without `locationId`, the answer has one row per location the connection reaches. A location with no activity reads 0. A row without Reputation has `stats` null and a checkout link. `IsLowerBound` true means the count is at least that number.",
        "parameters": [
          { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Leave out to read every location the connection reaches. A location key reads its own location." },
          { "name": "month", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Calendar month as `YYYY-MM`, in each location's timezone. Leave out for the current month. A month that has not started is refused." }
        ],
        "responses": {
          "200": {
            "description": "One row per location asked for.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ReputationStats" },
                "example": { "ok": true, "month": "2026-10", "locations": [{ "locationId": "<location id>", "name": "Main St", "stats": { "requestsSent": 42, "requestsSentIsLowerBound": false, "reviewsGained": 9, "reviewsGainedIsLowerBound": false }, "checkoutUrl": null }] }
              }
            }
          },
          "401": { "$ref": "#/components/responses/InvalidKey" },
          "403": { "$ref": "#/components/responses/ProductRequired" },
          "404": { "description": "That location is not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } },
          "422": { "description": "`month` is not `YYYY-MM`, or has not started at a location read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error422" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/reviews": {
      "get": {
        "operationId": "listReviews",
        "x-mcp-tool": "list_reviews",
        "summary": "List Google reviews",
        "description": "The newest Google reviews on the Reviews page, newest first, at most 100. Each review has its rating, its text and the reviewer's name as Google shows them, and the reply when it is public on Google. Without `locationId`, it reads every location the connection reaches. `contentCleared` true means ReviewWheel no longer keeps the text, name and reply. `removedAt` is set when the review left Google. Free: no product is needed.",
        "parameters": [
          { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Leave out to read every location the connection reaches. A location key reads its own location." }
        ],
        "responses": {
          "200": {
            "description": "The newest reviews, newest first.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Reviews" },
                "example": { "ok": true, "reviews": [{ "id": "<review id>", "locationId": "<location id>", "locationName": "Main St", "rating": 5, "text": "Fast and clean work.", "authorName": "Pat L.", "createdAt": "2026-10-28T15:04:00.000Z", "reply": "Thanks, Pat!", "contentCleared": false, "removedAt": null, "reviewUrl": null }] }
              }
            }
          },
          "401": { "$ref": "#/components/responses/InvalidKey" },
          "404": { "description": "That location is not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/google-performance": {
      "get": {
        "operationId": "getGooglePerformance",
        "x-mcp-tool": "get_google_performance",
        "summary": "Read calls and clicks from Google",
        "description": "For one location and a date range: calls, website clicks and impressions (Search and Maps) from its Google Business Profile, the numbers on the Dashboard. Also the same totals for the period just before, and one row per day Google reported. Needs Reputation or Rank on the location. `totals` is null with `reason` `no-data-yet` until Google reports data for the range.",
        "parameters": [
          { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required, except with a location key, which reads its own location." },
          { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "First day, `YYYY-MM-DD`, in the location's timezone. Leave out for 30 days ending on `to`." },
          { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Last day, `YYYY-MM-DD`. Leave out for today, or 30 days from `from`. At most 366 days in one call." }
        ],
        "responses": {
          "200": {
            "description": "Totals for the range and the period before it, and one row per reported day.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GooglePerformance" },
                "example": { "ok": true, "locationId": "<location id>", "from": "2026-10-01", "to": "2026-10-30", "totals": { "calls": 31, "websiteClicks": 54, "impressions": 2210 }, "days": [{ "date": "2026-10-01", "calls": 1, "websiteClicks": 2, "impressions": 74 }], "previous": { "from": "2026-09-01", "to": "2026-09-30", "totals": { "calls": 24, "websiteClicks": 40, "impressions": 1980 } }, "lastSyncedAt": "2026-10-31T09:00:00.000Z" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/InvalidKey" },
          "403": { "$ref": "#/components/responses/ProductRequired" },
          "404": { "description": "That location is not on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } },
          "422": { "description": "An account key sent no `locationId`, a date is not `YYYY-MM-DD`, `from` is after `to`, or the range is over 366 days.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error422" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/job-completed": {
      "post": {
        "operationId": "reportJobCompleted",
        "summary": "Report a finished job",
        "description": "Saves the customer as a contact and starts the location's review request, which can text or email a real customer. Send only finished jobs, and only for customers who agreed to hear from the business. With `dryRun: true`, every check runs and nothing is saved or sent: the answer shows the contact, the location and when each first message is due, with a `previewId`. To send only what the preview showed, repeat the call with the same fields and the `previewId`. The `requestId` in the answer stops the request. Only an API key or a Zapier connection can call this route. An AI app connection gets `invalid-key`.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "A stable value for each job, for example your job ID. A retry with the same value creates nothing new and returns `deduped: true`. 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.",
            "schema": { "type": "string" },
            "example": "job-10482"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/JobCompleted" },
              "example": {
                "locationId": "<location id>",
                "firstName": "Jane",
                "lastName": "Doe",
                "phone": "+14045550123",
                "email": "jane@example.com",
                "jobType": "Water heater install",
                "completedAt": "2026-10-28T15:00:00Z"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The job was accepted. `deduped`, `stale` and `held` tell you what happened to it.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/JobCompletedResult" },
                "example": { "ok": true, "contactId": "<contact id>", "enrolled": true, "held": null }
              }
            }
          },
          "400": {
            "description": "The body is not a JSON object.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } }
          },
          "401": { "$ref": "#/components/responses/InvalidKey" },
          "403": {
            "description": "No plan, or the location cannot take this job.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403JobCompleted" } } }
          },
          "404": {
            "description": "`locationId` is not on this account.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } }
          },
          "409": {
            "description": "Another job source is connected for that location.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error409" } } }
          },
          "422": {
            "description": "A field is wrong or missing. `error` names it.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error422" } } }
          },
          "428": { "description": "A call with a `previewId` that does not match a dry run of the same fields by the same key in the last 10 minutes. Run the dry run again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error428" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": {
            "description": "Try again later.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } }
          }
        }
      }
    },
    "/api/v1/requests/{requestId}/stop": {
      "post": {
        "operationId": "stopReviewRequest",
        "summary": "Stop one review request",
        "description": "Stops one review request: its queued texts and emails are cancelled. The contact, its other requests and the send log stay. A message already sent stays sent. Needs Reputation on the location. `result` is `stopped`, or `already-finished` when nothing was left to send.",
        "parameters": [
          { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The `requestId` that POST /api/v1/job-completed returned." }
        ],
        "responses": {
          "200": {
            "description": "The request is stopped, or had already finished.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/StopRequestResult" },
                "example": { "ok": true, "requestId": "<request id>", "result": "stopped" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/InvalidKey" },
          "403": { "$ref": "#/components/responses/ProductRequired" },
          "404": { "description": "`request-unknown`: that request is not on this account. `not-found`: the path after the request id is not `/stop`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Request" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/profile-changes": {
      "post": {
        "operationId": "changeProfileFields",
        "x-mcp-tool": "update_profile_fields",
        "summary": "Change profile fields",
        "description": "Sets the same Google Business Profile fields on one location or many, through ReviewWheel's profile engine. A change takes two calls. The first has `dryRun: true`: Google checks each location and nothing changes. The answer has a `changeId` and `phase: \"checking\"` until every location is checked; read it with GET /api/v1/profile-changes/{changeId} (`get_profile_change`). It then shows each location's `before` and `after` for a person to approve. The second call has the same `locationIds` and `fields` and the dry run's `previewId`, within 10 minutes, and applies the change. Each location then reads `pending`, `applied`, or `refused` with a `code`. A location without Rank or the More Jobs Bundle is refused `product-required` with a `checkoutUrl`. One undo restores every location. Needs an owner or admin: an account key one of them made, or an AI app one of them signed in to. A location key is refused. One change runs at a time per account.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileChangeRequest" } } } },
        "responses": {
          "200": {
            "description": "The dry run started, or the confirmed change started. Each location has its own status.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileChange" } } }
          },
          "400": { "description": "The body is not a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } },
          "401": { "$ref": "#/components/responses/InvalidKey" },
          "403": {
            "description": "`approver-required`: the key is a location key, or its maker is no longer an owner or admin. `no-plan`: the account is shut down.",
            "content": {
              "application/json": { "schema": { "oneOf": [{ "$ref": "#/components/schemas/Error403Approver" }, { "$ref": "#/components/schemas/Error403" }] } }
            }
          },
          "404": {
            "description": "A `locationIds` value is not a location id.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } }
          },
          "409": {
            "description": "`company-busy`: another profile change on this account is still running. Retry after `Retry-After` seconds.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error409Change" } } }
          },
          "422": {
            "description": "A field is the wrong type, or the change is outside the allowed fields or 1 to 100 locations.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error422Change" } } }
          },
          "428": {
            "description": "`confirm-required`: no `previewId`, or it does not match a dry run of this body by this key in the last 10 minutes.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error428" } } }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/profile-changes/{changeId}": {
      "get": {
        "operationId": "getProfileChange",
        "x-mcp-tool": "get_profile_change",
        "summary": "Read one profile change",
        "description": "Reads a profile change. While `phase` is `checking` or `previewed`, each location shows the dry run: `before`, `after` and Google's check. After the apply, each location shows its outcome and its `undo`. Google work runs in the background: a location reads `checking` or `pending` until its step is done.",
        "parameters": [
          {
            "name": "changeId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "The `changeId` that POST /api/v1/profile-changes (`update_profile_fields`) returned."
          }
        ],
        "responses": {
          "200": { "description": "The change now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileChange" } } } },
          "401": { "$ref": "#/components/responses/InvalidKey" },
          "403": {
            "description": "`approver-required`: the key is a location key, or its maker is no longer an owner or admin. `no-plan`: the account is shut down.",
            "content": {
              "application/json": { "schema": { "oneOf": [{ "$ref": "#/components/schemas/Error403Approver" }, { "$ref": "#/components/schemas/Error403" }] } }
            }
          },
          "404": {
            "description": "`change-not-found`: that change is not on this account. `not-found`: no route matches the path.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Change" } } }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/profile-changes/{changeId}/undo": {
      "post": {
        "operationId": "undoProfileChange",
        "x-mcp-tool": "undo_profile_change",
        "summary": "Undo one profile change",
        "description": "Puts back every location a profile change touched. A write not yet sent is cancelled (`unchanged`). An applied one is restored through the profile engine: `pending`, then `applied`. A location is refused with a `code` when it cannot be restored: `changed-since` means the profile changed after ours, so it stays as it is. Calling it again reports progress and retries what failed.",
        "parameters": [
          {
            "name": "changeId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "The `changeId` that POST /api/v1/profile-changes (`update_profile_fields`) returned."
          }
        ],
        "responses": {
          "200": {
            "description": "The undo started. Each location has its own `undo`.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileChange" } } }
          },
          "401": { "$ref": "#/components/responses/InvalidKey" },
          "403": {
            "description": "`approver-required`: the key is a location key, or its maker is no longer an owner or admin. `no-plan`: the account is shut down.",
            "content": {
              "application/json": { "schema": { "oneOf": [{ "$ref": "#/components/schemas/Error403Approver" }, { "$ref": "#/components/schemas/Error403" }] } }
            }
          },
          "404": {
            "description": "`change-not-found`: that change is not on this account. `not-found`: no route matches the path.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404Change" } } }
          },
          "409": {
            "description": "`not-applied`: the change was never applied. `company-busy`: another profile change is still running; retry after `Retry-After` seconds.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error409Change" } } }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A ReviewWheel API key, `rwk_live_` followed by 32 hex characters. An owner or an admin creates it on the Webhook connection page: https://app.reviewwheel.com/app/connections/webhook"
      }
    },
    "responses": {
      "InvalidKey": {
        "description": "The key is wrong, revoked or missing.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } }
      },
      "NoPlan": {
        "description": "The account has no active plan.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } }
      },
      "ProductRequired": {
        "description": "The location needs a product it does not have (`product-required`). `checkoutUrl` is the one page where the owner can buy it; null when the location is paused. Give the owner the link. Never state a price. A Zapier connection on an account with no plan gets `no-plan` instead.",
        "content": { "application/json": { "schema": { "oneOf": [{ "$ref": "#/components/schemas/Error403ProductRequired" }, { "$ref": "#/components/schemas/Error403" }] } } }
      },
      "RateLimited": {
        "description": "Too many requests. Wait the number of seconds in `Retry-After`, then retry.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before the next request.",
            "schema": { "type": "integer", "minimum": 1 }
          }
        },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } }
      }
    },
    "schemas": {
      "Ping": {
        "type": "object",
        "required": ["ok", "keyName", "kind", "companyName", "locationName"],
        "properties": {
          "ok": { "const": true },
          "keyName": { "type": "string" },
          "kind": { "type": "string", "enum": ["company", "location"], "description": "`company` for an account key, `location` for a location key." },
          "companyName": { "type": "string" },
          "locationName": { "type": ["string", "null"], "description": "Set only for a location key." }
        }
      },
      "Location": {
        "type": "object",
        "required": ["id", "name", "city", "state", "status"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "city": { "type": ["string", "null"] },
          "state": { "type": ["string", "null"] },
          "status": { "type": "string", "enum": ["setup", "live", "paused", "discovered"] }
        }
      },
      "StopRequestResult": {
        "type": "object",
        "required": ["ok", "requestId", "result"],
        "properties": {
          "ok": { "const": true },
          "requestId": { "type": "string" },
          "result": { "enum": ["stopped", "already-finished"], "description": "`already-finished`: the request had nothing left to send. Nothing changed." }
        }
      },
      "ProfileChangeRequest": {
        "type": "object",
        "required": ["locationIds", "fields"],
        "properties": {
          "locationIds": { "type": "array", "items": { "type": "string" }, "description": "The locations to change: 1 to 100 `id` values from GET /api/v1/locations (`list_locations`)." },
          "fields": {
            "type": "object",
            "description": "The fields to set, in Google Business Profile's Location format. Allowed: `categories`, `serviceItems`, `profile`, `regularHours`, `specialHours`, `moreHours`, `serviceArea`, `websiteUri`, `phoneNumbers`."
          },
          "dryRun": { "type": "boolean", "description": "`true` checks the change with Google and changes nothing." },
          "previewId": { "type": "string", "description": "The `previewId` of a dry run of the same body, to confirm it. Without `dryRun`, the call needs it." }
        }
      },
      "ProfileChange": {
        "type": "object",
        "required": ["ok", "changeId", "previewId", "phase", "expiresAt", "locations"],
        "properties": {
          "ok": { "const": true },
          "changeId": { "type": "string" },
          "previewId": { "type": ["string", "null"], "description": "Send it with the same body to confirm the dry run. Null once the change is applied." },
          "phase": {
            "enum": ["checking", "previewed", "applied"],
            "description": "`checking`: Google is still checking some locations. `previewed`: the dry run is done. `applied`: the change was confirmed."
          },
          "expiresAt": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "The confirm must arrive before this time. Null while checking and after the apply."
          },
          "locations": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileChangeLocation" } }
        }
      },
      "ProfileChangeLocation": {
        "type": "object",
        "required": ["locationId", "name", "after", "status"],
        "properties": {
          "locationId": { "type": "string" },
          "name": { "type": ["string", "null"], "description": "Null for an id that is not on this account." },
          "after": { "type": "object", "description": "The fields the change sets." },
          "before": { "type": ["object", "null"], "description": "Dry run only: what Google holds now." },
          "googleCheck": { "enum": ["passed", "failed", null], "description": "Dry run only: Google's `validateOnly` result." },
          "status": {
            "enum": ["checking", "ready", "refused", "pending", "applied"],
            "description": "Dry run: `checking`, `ready` or `refused`. After the apply: `pending`, `applied` or `refused`."
          },
          "code": {
            "type": "string",
            "description": "Why the location is refused, for example `product-required`, `location-not-found`, `profile-not-connected` or `change-in-progress`."
          },
          "checkoutUrl": {
            "type": ["string", "null"],
            "description": "With `product-required`: the one page where the owner can add Rank. Null when the location is paused. Never state a price."
          },
          "undo": {
            "oneOf": [
              {
                "type": "object",
                "required": ["status"],
                "properties": {
                  "status": { "enum": ["pending", "applied", "unchanged", "refused"] },
                  "code": { "type": "string", "description": "Why the location is refused, for example `changed-since`, `not-settled` or `undo-expired`." }
                }
              },
              { "type": "null" }
            ],
            "description": "After the apply: the undo's outcome, or null before any undo."
          }
        }
      },
      "PlanProduct": {
        "type": "object",
        "required": ["state", "checkoutUrl"],
        "properties": {
          "state": { "type": "string", "enum": ["none", "trial", "full"] },
          "checkoutUrl": { "type": ["string", "null"], "description": "Set only when `state` is `none`, the product has a checkout page and the location is not paused." }
        }
      },
      "Plan": {
        "type": "object",
        "required": ["ok", "locations"],
        "properties": {
          "ok": { "const": true },
          "locations": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "name", "products"],
              "properties": {
                "id": { "type": "string" },
                "name": { "type": "string" },
                "products": {
                  "type": "object",
                  "required": ["reputation", "rank", "website", "ads"],
                  "properties": {
                    "reputation": { "$ref": "#/components/schemas/PlanProduct" },
                    "rank": { "$ref": "#/components/schemas/PlanProduct" },
                    "website": { "$ref": "#/components/schemas/PlanProduct" },
                    "ads": { "$ref": "#/components/schemas/PlanProduct" }
                  }
                }
              }
            }
          }
        }
      },
      "ProfileAudit": {
        "type": "object",
        "required": ["ok", "locationId", "audit"],
        "properties": {
          "ok": { "const": true },
          "locationId": { "type": "string" },
          "audit": {
            "type": ["object", "null"],
            "description": "Only facts from the business's own profile. Competitor data, map rank and the overall audit score are never returned.",
            "required": ["ranAt", "trade", "photos", "completeness", "categorySpecificity", "aiVisibility", "self"],
            "additionalProperties": false,
            "properties": {
              "ranAt": { "type": "string", "format": "date-time", "description": "When the audit ran." },
              "trade": { "type": ["string", "null"], "description": "The trade keyword the audit used." },
              "photos": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Photo score." },
              "completeness": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Share of hours, website and phone that the profile lists." },
              "categorySpecificity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "100 when a category names the trade." },
              "aiVisibility": {
                "type": ["object", "null"],
                "properties": {
                  "score": { "type": "integer", "minimum": 0, "maximum": 100 },
                  "signals": { "type": "array", "items": { "type": "object", "required": ["label", "ok"], "properties": { "label": { "type": "string" }, "ok": { "type": "boolean" } } } }
                }
              },
              "self": {
                "type": ["object", "null"],
                "description": "The profile's own Google rating and review count.",
                "properties": { "rating": { "type": ["number", "null"] }, "reviewCount": { "type": "integer" } }
              }
            }
          },
          "reason": { "type": "string", "enum": ["no-audit-yet"], "description": "Set only when `audit` is null." }
        }
      },
      "ReputationStats": {
        "type": "object",
        "required": ["ok", "month", "locations"],
        "properties": {
          "ok": { "const": true },
          "month": { "type": "string", "description": "The month read, `YYYY-MM`. Each location's month runs in its own timezone." },
          "locations": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["locationId", "name", "stats", "checkoutUrl"],
              "properties": {
                "locationId": { "type": "string" },
                "name": { "type": "string" },
                "stats": {
                  "type": ["object", "null"],
                  "description": "Null when the location does not have Reputation.",
                  "required": ["requestsSent", "requestsSentIsLowerBound", "reviewsGained", "reviewsGainedIsLowerBound"],
                  "properties": {
                    "requestsSent": { "type": "integer", "minimum": 0, "description": "Review requests that started this month." },
                    "requestsSentIsLowerBound": { "type": "boolean" },
                    "reviewsGained": { "type": "integer", "minimum": 0, "description": "New Google reviews this month, counted from when the location joined ReviewWheel. A month that began before that is a lower bound." },
                    "reviewsGainedIsLowerBound": { "type": "boolean" }
                  }
                },
                "checkoutUrl": { "type": ["string", "null"], "description": "The agent checkout link when `stats` is null; null when the location is paused or has Reputation." }
              }
            }
          }
        }
      },
      "Reviews": {
        "type": "object",
        "required": ["ok", "reviews"],
        "properties": {
          "ok": { "const": true },
          "reviews": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "required": ["id", "locationId", "locationName", "rating", "text", "authorName", "createdAt", "reply", "contentCleared", "removedAt", "reviewUrl"],
              "properties": {
                "id": { "type": "string" },
                "locationId": { "type": "string" },
                "locationName": { "type": "string" },
                "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
                "text": { "type": ["string", "null"], "description": "As Google gave it. Null when the review has no text or `contentCleared` is true." },
                "authorName": { "type": ["string", "null"], "description": "As Google gave it. Null when `contentCleared` is true." },
                "createdAt": { "type": "string", "format": "date-time" },
                "reply": { "type": ["string", "null"], "description": "The reply that is public on Google. Never a draft." },
                "contentCleared": { "type": "boolean", "description": "True when ReviewWheel no longer keeps the text, name and reply." },
                "removedAt": { "type": ["string", "null"], "format": "date-time", "description": "When the review left Google, or null." },
                "reviewUrl": { "type": ["string", "null"], "description": "The review on Google, when ReviewWheel has the link." }
              }
            }
          }
        }
      },
      "GooglePerformanceTotals": {
        "type": "object",
        "required": ["calls", "websiteClicks", "impressions"],
        "properties": {
          "calls": { "type": "integer", "minimum": 0, "description": "Taps on the call button." },
          "websiteClicks": { "type": "integer", "minimum": 0 },
          "impressions": { "type": "integer", "minimum": 0, "description": "Search and Maps views together." }
        }
      },
      "GooglePerformance": {
        "type": "object",
        "required": ["ok", "locationId", "from", "to", "totals", "days", "previous", "lastSyncedAt"],
        "properties": {
          "ok": { "const": true },
          "locationId": { "type": "string" },
          "from": { "type": "string", "format": "date" },
          "to": { "type": "string", "format": "date" },
          "totals": { "oneOf": [{ "$ref": "#/components/schemas/GooglePerformanceTotals" }, { "type": "null" }], "description": "Null until Google reports data for the range." },
          "days": {
            "type": "array",
            "description": "One row per day Google reported, oldest first.",
            "items": { "allOf": [{ "$ref": "#/components/schemas/GooglePerformanceTotals" }, { "type": "object", "required": ["date"], "properties": { "date": { "type": "string", "format": "date" } } }] }
          },
          "previous": {
            "type": "object",
            "required": ["from", "to", "totals"],
            "description": "The same number of days, ending the day before `from`.",
            "properties": {
              "from": { "type": "string", "format": "date" },
              "to": { "type": "string", "format": "date" },
              "totals": { "oneOf": [{ "$ref": "#/components/schemas/GooglePerformanceTotals" }, { "type": "null" }] }
            }
          },
          "lastSyncedAt": { "type": ["string", "null"], "format": "date-time", "description": "When ReviewWheel last got numbers from Google for this range. Null with no data." },
          "reason": { "type": "string", "enum": ["no-data-yet"], "description": "Set only when `totals` is null." }
        }
      },
      "RankScore": {
        "type": "object",
        "required": ["ok", "locationId", "score"],
        "properties": {
          "ok": { "const": true },
          "locationId": { "type": "string" },
          "score": {
            "type": ["object", "null"],
            "required": ["score", "band", "weekStart", "mapPart", "aiPart", "from", "change"],
            "properties": {
              "score": { "type": "integer", "minimum": 0, "maximum": 100 },
              "band": { "type": "string", "enum": ["red", "yellow", "green", "navy"] },
              "weekStart": { "type": "string", "format": "date-time", "description": "The Monday the scored week starts." },
              "mapPart": { "type": "number", "description": "Share of map points in the top 3, 0 to 1." },
              "aiPart": { "type": "number", "description": "Share of AI answers that name the business, 0 to 1." },
              "from": {
                "type": ["object", "null"],
                "description": "The first scored week, compared against.",
                "properties": { "score": { "type": "integer" }, "weekStart": { "type": "string", "format": "date-time" } }
              },
              "change": { "type": ["string", "null"] }
            }
          },
          "reason": { "type": "string", "enum": ["no-score-yet"], "description": "Set only when `score` is null." }
        }
      },
      "JobCompleted": {
        "type": "object",
        "description": "Send `phone`, `email` or both; at least one must be usable. A string field sent as null or an empty string counts as not sent.",
        "properties": {
          "locationId": { "type": "string", "description": "Required with an account key. Ignored with a location key." },
          "phone": { "type": "string", "description": "The customer's mobile number." },
          "email": { "type": "string", "description": "The customer's email address." },
          "firstName": { "type": "string", "description": "The customer's first name." },
          "lastName": { "type": "string", "description": "The customer's last name." },
          "address": { "type": "string", "description": "The job's street address." },
          "jobType": { "type": "string", "description": "What the job was, for example `Water heater install`." },
          "completedAt": {
            "description": "When the job was done: an ISO 8601 string, or an epoch number in seconds or milliseconds.",
            "oneOf": [
              { "type": "string" },
              { "type": "number", "exclusiveMinimum": 0 }
            ]
          },
          "dryRun": { "type": "boolean", "description": "`true`: run every check and answer the preview, with nothing saved or sent." },
          "previewId": { "type": "string", "description": "The `previewId` of a dry run with the same fields, from the last 10 minutes. With it, the call is refused if anything changed since that preview." }
        }
      },
      "JobCompletedResult": {
        "type": "object",
        "required": ["ok"],
        "properties": {
          "ok": { "const": true },
          "contactId": { "type": "string" },
          "requestId": { "type": ["string", "null"], "description": "The review request this job started, or null when it started none. POST /api/v1/requests/{requestId}/stop stops it." },
          "enrolled": { "type": "boolean", "description": "`false` with `stale: true`: the job is too old for a review request." },
          "held": { "enum": ["paused", "trial", null], "description": "`paused`: the account paused requests. The job saves and waits. `trial` (dry run only): the request waits in the trial queue." },
          "dryRun": { "const": true, "description": "The answer is a preview. Nothing was saved or sent." },
          "previewId": { "type": ["string", "null"], "description": "Dry run only. Send it with the same fields within 10 minutes to make the real call." },
          "contact": {
            "type": "object",
            "description": "Dry run only. The contact as it would be saved. `existing` is true when the job matches a saved contact.",
            "properties": {
              "existing": { "type": "boolean" },
              "firstName": { "type": ["string", "null"] },
              "lastName": { "type": ["string", "null"] },
              "phone": { "type": ["string", "null"] },
              "email": { "type": ["string", "null"] }
            }
          },
          "location": {
            "type": "object",
            "description": "Dry run only. The location the job lands on.",
            "properties": { "locationId": { "type": "string" }, "name": { "type": "string" } }
          },
          "startsRequest": { "type": "boolean", "description": "Dry run only. `false` when the job saves the contact but starts no request; `reason` says why." },
          "reason": {
            "enum": ["already-in-request", "cooldown", "do-not-contact", "source-blocked", "no-channel", "demo-account", "no-template", null],
            "description": "Dry run only. Why no request starts: the customer is already in one, was asked recently, is marked do not contact, or cannot be reached."
          },
          "sends": {
            "type": "array",
            "description": "Dry run only. Each channel's first message and the earliest time it can go, inside 8am to 8pm at the location. Checks run again before each send, so it can go later. `at` is null while the request is held.",
            "items": {
              "type": "object",
              "properties": { "channel": { "enum": ["sms", "email"] }, "at": { "type": ["string", "null"], "format": "date-time" } }
            }
          },
          "deduped": { "const": true, "description": "This `Idempotency-Key` was already used. Nothing new happened." },
          "stale": { "const": true, "description": "The job is too old for a review request." },
          "warnings": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Present when ReviewWheel dropped a phone or email it could not use. The contact still saves with the other channel."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["ok", "code", "error"],
        "properties": {
          "ok": { "const": false },
          "code": { "type": "string", "description": "Machine name for the error. Reference: https://reviewwheel.com/api#errors" },
          "error": { "type": "string", "description": "One sentence for a person to read." }
        }
      },
      "Error400": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["invalid-body"] } } }] },
      "Error401": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["invalid-key"] } } }] },
      "Error403": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["no-plan"] } } }] },
      "Error403JobCompleted": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["no-plan", "service-ineligible", "consent-required", "source-blocked"] } } }] },
      "Error403ProductRequired": {
        "allOf": [
          { "$ref": "#/components/schemas/Error" },
          {
            "required": ["product", "checkoutUrl"],
            "properties": {
              "code": { "enum": ["product-required"] },
              "product": { "type": "string", "enum": ["reputation", "rank", "website", "ads"] },
              "checkoutUrl": { "type": ["string", "null"], "description": "The one page where the owner can buy the product. Null when the location is paused: the owner resumes in the app." }
            }
          }
        ]
      },
      "Error404": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["location-unknown"] } } }] },
      "Error404Request": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["request-unknown", "not-found"] } } }] },
      "Error409": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["source-conflict"] } } }] },
      "Error422": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["invalid-field", "location-required", "no-contact"] } } }] },
      "Error403Approver": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["approver-required"] } } }] },
      "Error404Change": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["change-not-found", "not-found"] } } }] },
      "Error409Change": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["company-busy", "not-applied"] } } }] },
      "Error422Change": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["invalid-field", "invalid-change"] } } }] },
      "Error428": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["confirm-required"] } } }] },
      "Error422LocationRequired": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["location-required"] } } }] },
      "Error429": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["rate-limited"] } } }] },
      "Error503": { "allOf": [{ "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "enum": ["provider-state-changed", "no-template"] } } }] }
    }
  }
}
