Skip to main content
Help centerGet support
Browse documentation
On this page 71 sections

API Reference

EmbedMyReviews API

Two complementary interfaces, one platform. The REST API covers structured automations: reviews, organisations and their locations, review-request invites, Google Business Profile performance data, agency-only Local Search Grid scans and SMS provider setup, and real-time webhook notifications. The AI Hub (MCP) covers interactive AI work. Assistants can read reviews, metrics, contacts, campaigns and Google Business Profile data, tag reviews, and draft review replies and Google posts that a person approves. For the agency owner they can also read Sales Intelligence leads, run Local Search Grid scans and set up SMS providers. MCP clients such as ChatGPT, Claude, Claude Code and Cursor call these tools over JSON-RPC 2.0. Some REST features, such as sending review-request invites, have no AI Hub tool.

Base URLhttps://app.your-white-label.com/api/v1
AuthBearer Token
Rate Limit60 req/min
FormatJSON

Authentication

All API requests require a valid API token. Create tokens on the API Tokens tab of the API & Webhooks page (the agency owner: Platform → AI & Automation → API & Webhooks; team members and customers: Settings → API & Webhooks). Include the token in the Authorization header of every request.

Authorization Header

Authorization: Bearer your-api-token

Token permissions

PermissionAccess
reviews:readView reviews and review sources
reviews:createCreate reviews
reviews:updateUpdate reviews and publish review replies
reviews:deleteDelete reviews
request:readView campaigns
request:createSend review invites
organizations:readView organisations and locations
organizations:createCreate organisations and locations
organizations:updateUpdate organisations and locations
organizations:deleteDelete organisations and locations

Rate limiting

60 requests per minute per token. Every response includes rate limit headers.

HeaderDescription
X-RateLimit-LimitMaximum requests per window (60)
X-RateLimit-RemainingRemaining requests in current window
Retry-AfterSeconds to wait before retrying (only on 429)

Errors

Standard HTTP status codes. Errors return JSON with a message field.

CodeStatusDescription
200OKRequest succeeded
201CreatedResource successfully created
202AcceptedRequest accepted and queued
401UnauthenticatedMissing or invalid API token
402Upgrade RequiredPlan limit or plan feature required (e.g. location limit, auto-respond)
403ForbiddenToken lacks required permissions for this action. Also returned while a customer's subscription is not active, for the customer's own tokens and for a team member's tokens while their current organization belongs to that customer (never for the agency owner's); while the agency's subscription is paused; and when an AI Hub token is sent to the REST API, which AI Hub tokens cannot call. The message field gives the reason.
404Not FoundResource does not exist
409ConflictResource already in the requested state (e.g. review already replied)
422Validation ErrorRequest body failed validation
429Too Many RequestsRate limit exceeded
500Server ErrorSomething went wrong on our end
502Upstream ErrorThe review platform rejected the request (e.g. reply publish failed)

Pagination

List endpoints return paginated results. Most default to 10 items per page (locations default to 25 and connect links to 20; per-endpoint per_page parameters are documented where supported). Use the page query parameter to navigate.

{
  "data": [...],
  "links": {
    "first": "https://app.your-white-label.com/api/v1/reviews?page=1",
    "last": "https://app.your-white-label.com/api/v1/reviews?page=5",
    "prev": null,
    "next": "https://app.your-white-label.com/api/v1/reviews?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 10,
    "to": 10,
    "total": 48
  }
}

Validation error (422) response

{
  "message": "The email field is required when phone is not present.",
  "errors": {
    "email": [
      "The email field is required when phone is not present."
    ]
  }
}
GET/api/v1/reviews

List reviews

Retrieve a paginated list of reviews across all connected sources. Filter by rating, organisation, location, or review source.

Requires reviews:read

Query parameters

ParameterTypeDescription
ratingintegerFilter by rating (1-5)
organization_idintegerFilter by organisation
location_idintegerFilter by location
source_names[]arrayFilter by source names (e.g. Google, Facebook)
source_statusstringremoved: only reviews no longer on their review site. live: every other review. restored: reviews back on their review site after a removal (part of live)
pageintegerPage number (default: 1)

Example request

curl https://app.your-white-label.com/api/v1/reviews?rating=5 \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": [
    {
      "id": 142,
      "organization_id": 1,
      "location_id": 3,
      "integration_id": 12,
      "author": "Sarah Johnson",
      "date": "2025-12-15T10:30:00.000000Z",
      "rating": 5,
      "title": null,
      "message": "Outstanding service!",
      "source": "Google",
      "source_logo": "https://example.com/logos/google.svg",
      "avatar": "https://...",
      "reply": "Thank you Sarah!",
      "reply_date": "2025-12-16T09:00:00.000000Z",
      "hidden": false,
      "verified": false,
      "source_status": "live",
      "source_removed_at": null,
      "source_last_seen_at": null,
      "source_restored_at": null
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "from": 1, "last_page": 5, "per_page": 10, "to": 10, "total": 48 }
}

Important

Google locations connected with Grant Access (Google sign-in) are checked for removed reviews once a week, and sooner when the Google review count drops. Every review carries source_status ("live" or "removed"), source_removed_at (when the removal was detected), source_last_seen_at (when a removed review was last known to be on Google, or null) and source_restored_at (when a removed review came back, while it is still there). Sources that are not checked always report "live".

GET/api/v1/reviews/{id}

Get review

Retrieve a single review by its ID.

Requires reviews:read

Example request

curl https://app.your-white-label.com/api/v1/reviews/142 \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": {
    "id": 142,
    "organization_id": 1,
    "location_id": 3,
    "integration_id": 42,
    "author": "Sarah Johnson",
    "date": "2025-12-15T10:30:00.000000Z",
    "rating": 5,
    "title": null,
    "message": "Outstanding service!",
    "source": "Testimonials",
    "source_logo": "https://cdn.revw.me/img/integration-logos/testimonials.svg",
    "avatar": "https://...",
    "reply": null,
    "reply_date": null,
    "hidden": false,
    "verified": false,
    "source_status": "live",
    "source_removed_at": null,
    "source_last_seen_at": null,
    "source_restored_at": null
  }
}
POST/api/v1/reviews

Create review

Create a new review from a custom or testimonial source. Only custom integrations and testimonials are supported, so reviews from synced sources like Google or Facebook cannot be created via the API. Use the Writable Sources endpoint to discover available sources.

Requires reviews:read + reviews:create

Request body

ParameterTypeDescription
authorstringReviewer name (required, max 255 chars)
ratingintegerStar rating 1-5 (required)
published_ondatePublication date in Y-m-d format (required)
organization_idintegerOrganisation ID (required)
location_idintegerLocation ID, must belong to the organisation (required)
sourceintegerIntegration ID from the Writable Sources endpoint (required)
messagestringReview content
titlestringReview title (max 255 chars)
avatarfileReviewer avatar (png, jpg, jpeg, svg, max 250KB)

Example request

curl -X POST https://app.your-white-label.com/api/v1/reviews \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json" \
  -F "author=Jane Smith" \
  -F "rating=5" \
  -F "message=Absolutely fantastic experience!" \
  -F "published_on=2026-01-15" \
  -F "organization_id=1" \
  -F "location_id=3" \
  -F "source=42"

Example response 201 Created

{
  "data": {
    "id": 285,
    "organization_id": 1,
    "location_id": 3,
    "integration_id": 42,
    "author": "Jane Smith",
    "date": "2026-01-15T00:00:00.000000Z",
    "rating": 5,
    "title": null,
    "message": "Absolutely fantastic experience!",
    "source": "Testimonials",
    "source_logo": "https://cdn.revw.me/img/integration-logos/testimonials.svg",
    "avatar": "https://ui-avatars.com/api/?name=Jane Smith&background=333D9B&size=74&color=ffffff&rounded=1",
    "reply": null,
    "reply_date": null,
    "hidden": false,
    "verified": false
  }
}

Important

Only custom and testimonial sources are supported. Use GET /api/v1/reviews/sources to discover available sources and their IDs.

The location must belong to the specified organisation, and your token must have access to both.

PUT/api/v1/reviews/{id}

Update review

Update an existing review. All fields are optional, so only include the fields you want to change. Only reviews from custom or testimonial sources can be updated. Source cannot be changed.

Requires reviews:read + reviews:update

Request body

ParameterTypeDescription
authorstringReviewer name (max 255 chars)
ratingintegerStar rating 1-5
messagestringReview content
titlestringReview title (max 255 chars)
published_ondatePublication date in Y-m-d format
avatarfileReviewer avatar (png, jpg, jpeg, svg, max 250KB)

Example request

curl -X PUT https://app.your-white-label.com/api/v1/reviews/285 \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json" \
  -F "rating=4" \
  -F "message=Updated review content."

Important

Only reviews from custom integrations and testimonial sources can be updated. Synced reviews (Google, Facebook, etc.) return 403. To respond to a synced review, use the Reply to Review endpoint below.

Source cannot be changed. To change source, delete and recreate the review.

POST/api/v1/reviews/{id}/reply

Reply to review

Publish a reply to a Google or Facebook review. The reply goes live on the platform IMMEDIATELY, with no approval step. This is the programmatic equivalent of clicking Reply in the dashboard, intended for systems that manage responses in their own workflow. Requires the auto-respond feature on your plan.

Requires reviews:read + reviews:update

Request body

ParameterTypeDescription
messagestringThe reply text (required, max 4096 chars, Google's hard limit).

Example request

curl -X POST https://app.your-white-label.com/api/v1/reviews/285/reply \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Thank you Sarah! We look forward to seeing you again."}'

Example response 200 OK

{
  "data": {
    "id": 285,
    "replied": true,
    "reply_message": "Thank you Sarah! We look forward to seeing you again.",
    "reply_published_on": "2026-07-13T10:30:00+00:00"
  }
}

Important

Only reviews synced through a Google or Facebook API connection can be replied to. Other sources return 422 with code unsupported_source.

Requires the auto-respond feature on the organisation's plan. Without it the endpoint returns 402 with code upgrade_required.

Replying again to a Google review UPDATES the existing reply (Google replaces it). Replying again to a Facebook review is blocked with 409 already_replied, because it would post a second public comment.

Concurrent publishes to the same review are serialised: a racing request gets 409 with code publish_in_progress and should retry after a few seconds.

If the platform rejects the reply (revoked connection, unsupported content), the endpoint returns 502 with code publish_failed and the review is NOT marked as replied.

A review that is no longer on its review site (source_status "removed", or Google answers that it no longer exists) returns 422 with code review_removed. Nothing is posted.

AI Hub note: the MCP draft_review_response tool is unaffected: MCP drafts are still always held for human approval. This endpoint is the deliberate, token-gated exception for your own backend integrations.

DELETE/api/v1/reviews/{id}

Delete review

Permanently delete a review. This action cannot be undone. Only reviews from custom or testimonial sources can be deleted.

Requires reviews:read + reviews:delete

Example request

curl -X DELETE https://app.your-white-label.com/api/v1/reviews/285 \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "message": "Review deleted successfully."
}

Important

Only reviews from custom integrations and testimonial sources can be deleted. Synced reviews (Google, Facebook, etc.) return 403.

GET/api/v1/reviews/sources

Writable review sources

Returns sources available for creating reviews (custom integrations and testimonials). The id from each source is what you pass as the source parameter when creating a review.

Requires reviews:read

Query parameters

ParameterTypeDescription
organization_idintegerFilter by organisation
location_idintegerFilter by location
pageintegerPage number (default: 1)

Example request

curl https://app.your-white-label.com/api/v1/reviews/sources?location_id=3 \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": [
    {
      "id": 42,
      "name": "Testimonials",
      "logo": "https://cdn.revw.me/img/integration-logos/testimonials.svg",
      "type": "testimonials",
      "organization_id": 1,
      "location_id": 3
    },
    {
      "id": 58,
      "name": "My Custom Source",
      "logo": "https://cdn.revw.me/...",
      "type": "custom",
      "organization_id": 1,
      "location_id": 3
    }
  ],
  "links": { ... },
  "meta": { ... }
}
GET/api/v1/organizations

List organisations

Returns a paginated list of all organisations accessible to the authenticated user, each with its locations.

Requires organizations:read

Example request

curl https://app.your-white-label.com/api/v1/organizations \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": [
    {
      "id": 1,
      "name": "Acme Dental Clinic",
      "default_location_id": 3,
      "locations": [
        { "id": 3, "organization_id": 1, "name": "Downtown", "created_at": "...", "updated_at": "..." }
      ],
      "created_at": "2025-01-15T08:30:00.000000Z",
      "updated_at": "2025-06-20T14:22:00.000000Z"
    }
  ],
  "links": { ... },
  "meta": { ... }
}
POST/api/v1/organizations

Create organisation

Create a new organisation. The name must be unique across your account. A "Default Location" is created automatically and returned in the response, so you can pass its ID straight to connect links or campaigns without a second call.

Requires organizations:create

Request body

ParameterTypeDescription
namestringOrganisation name (required, max 255 chars, unique)
logofileLogo image (png, jpg, jpeg, svg, max 250KB)

Example request

curl -X POST https://app.your-white-label.com/api/v1/organizations \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Downtown Branch"}'

Example response 201 Created

{
  "id": 2,
  "name": "Downtown Branch",
  "default_location_id": 5,
  "locations": [
    { "id": 5, "organization_id": 2, "name": "Default Location", "created_at": "...", "updated_at": "..." }
  ],
  "created_at": "2025-12-15T10:30:00.000000Z",
  "updated_at": "2025-12-15T10:30:00.000000Z"
}
GET/api/v1/organizations/{id}

Get organisation

Retrieve a single organisation by its ID, including its locations.

Requires organizations:read

Example request

curl https://app.your-white-label.com/api/v1/organizations/1 \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "id": 1,
  "name": "Acme Dental Clinic",
  "default_location_id": 3,
  "locations": [
    { "id": 3, "organization_id": 1, "name": "Downtown", "created_at": "...", "updated_at": "..." }
  ],
  "created_at": "2025-01-15T08:30:00.000000Z",
  "updated_at": "2025-06-20T14:22:00.000000Z"
}
PUT/api/v1/organizations/{id}

Update organisation

Update an existing organisation's name or logo.

Requires organizations:update

Request body

ParameterTypeDescription
namestringOrganisation name (max 255 chars, unique)
logofileLogo image (png, jpg, jpeg, svg, max 250KB)

Example request

curl -X PUT https://app.your-white-label.com/api/v1/organizations/1 \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name"}'
DELETE/api/v1/organizations/{id}

Delete organisation

Permanently delete an organisation. This action cannot be undone. You must have at least one remaining organisation.

Requires organizations:delete

Example request

curl -X DELETE https://app.your-white-label.com/api/v1/organizations/1 \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "message": "Organization deleted successfully."
}
GET/api/v1/locations

List locations

Returns a paginated list of the locations the token's user can access, ordered by organisation. Use these IDs anywhere the API expects a location_id: connect links, GBP performance, review filters, campaigns. Every organisation gets a "Default Location" automatically on creation.

Requires organizations:read

Query parameters

ParameterTypeDescription
organization_idintegerLimit to one organisation (optional)
searchstringFree-text search over location and organisation names (optional)
per_pageintegerItems per page, 1 to 100. Defaults to 25.

Example request

curl "https://app.your-white-label.com/api/v1/locations?organization_id=1" \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": [
    {
      "id": 3,
      "organization_id": 1,
      "name": "Downtown",
      "created_at": "2025-01-15T08:30:00.000000Z",
      "updated_at": "2025-06-20T14:22:00.000000Z"
    }
  ],
  "links": { ... },
  "meta": { ... }
}

Important

Scoping matches the dashboard: a tenant owner token sees every location, an organisation owner sees their organisations' locations, and a role-bound team member only sees their assigned locations.

GET/api/v1/locations/{id}

Get location

Retrieve a single location by its ID.

Requires organizations:read

Example request

curl https://app.your-white-label.com/api/v1/locations/3 \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": {
    "id": 3,
    "organization_id": 1,
    "name": "Downtown",
    "created_at": "2025-01-15T08:30:00.000000Z",
    "updated_at": "2025-06-20T14:22:00.000000Z"
  }
}

Important

Returns 404 for IDs outside your organisations, and 403 with code location_access_denied when a role-bound team member's token requests a location outside their assigned scope, the same rules as the GBP endpoints.

POST/api/v1/locations

Create location

Create a new location inside one of your organisations. Plan location limits apply, exactly as in the dashboard.

Requires organizations:create

Request body

ParameterTypeDescription
organization_idintegerThe organisation the location will belong to (required)
namestringLocation name (required, max 255 chars)

Example request

curl -X POST https://app.your-white-label.com/api/v1/locations \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"organization_id": 1, "name": "Riverside Branch"}'

Example response 201 Created

{
  "data": {
    "id": 8,
    "organization_id": 1,
    "name": "Riverside Branch",
    "created_at": "2026-07-13T10:30:00.000000Z",
    "updated_at": "2026-07-13T10:30:00.000000Z"
  }
}

Important

Returns 404 if the organisation does not exist or is not visible to your token.

Returns 403 if your token's user lacks the create-locations permission in the target organisation (organisation owners always pass).

Returns 402 with code upgrade_required when the organisation owner's plan location limit is reached.

PUT/api/v1/locations/{id}

Update location

Rename an existing location.

Requires organizations:update

Request body

ParameterTypeDescription
namestringLocation name (required, max 255 chars)

Example request

curl -X PUT https://app.your-white-label.com/api/v1/locations/8 \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Riverside HQ"}'

Example response 200 OK

{
  "data": {
    "id": 8,
    "organization_id": 1,
    "name": "Riverside HQ",
    "created_at": "2026-07-13T10:30:00.000000Z",
    "updated_at": "2026-07-13T10:45:00.000000Z"
  }
}
DELETE/api/v1/locations/{id}

Delete location

Delete a location. Every organisation must keep at least one location, so the last remaining location cannot be deleted.

Requires organizations:delete

Example request

curl -X DELETE https://app.your-white-label.com/api/v1/locations/8 \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "message": "Location deleted successfully."
}

Important

Deleting the organisation's last location returns 422 with code last_location.

Team members whose dashboard was set to the deleted location are switched to another location automatically.

GET/api/v1/request-reviews/campaigns

List campaigns

Retrieve your review request campaigns. Use campaign UUIDs to send invites via the Send Invite endpoint.

Requires request:read

Query parameters

ParameterTypeDescription
organization_idintegerFilter campaigns by organisation
searchstringSearch campaigns by name

Example request

curl https://app.your-white-label.com/api/v1/request-reviews/campaigns \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Post-Visit Follow Up"
    },
    {
      "id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
      "name": "Monthly Customer Outreach"
    }
  ],
  "links": { ... },
  "meta": { ... }
}
POST/api/v1/request-reviews/campaigns/{campaign}/invite

Send review invite

Add a contact to a review request campaign so they receive an invite by email, SMS, or WhatsApp (coming soon). This is the primary endpoint for automating review requests from your CRM, POS, or booking system. A 202 response means the request was accepted, not that a message has been sent: the invite goes out in the background at the scheduled time.

Requires request:read + request:create

Path + request body

ParameterTypeDescription
campaignuuidCampaign UUID (required path parameter, from List Campaigns)
emailstringContact email. Required when phone is not provided.
phonestringPhone in E.164 format (e.g. +14275238194). Required when email is not provided.
first_namestringContact first name (max 255 chars)
last_namestringContact last name (max 255 chars)
send_after_hoursintegerHours to wait before sending. 0 = send as soon as possible (still within the campaign send window). null = use the campaign default.

Example request

curl -X POST https://app.your-white-label.com/api/v1/request-reviews/campaigns/{campaign_uuid}/invite \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "Sarah",
    "send_after_hours": 0
  }'

Example response 202 Accepted

{
  "id": "c7d8e9f0-1234-5678-abcd-ef9876543210",
  "status": "accepted",
  "reason": null,
  "message": "Invites sent successfully."
}

Response fields

FieldTypeDescription
iduuidUUID of the contact record, not of an individual invite. The same person (matched by email or phone) always returns the same id, including when the request is ignored as a duplicate or scheduled for later.
statusstring"accepted", or "skipped" when the contact will not be invited (see reason). A request ignored as a duplicate is "accepted": Invite Status then reports "ignored".
reasonstring | nullWhy it was skipped: "suppressed", "unsubscribed", "not_subscribed" or "invalid_identifier". null when accepted.
messagestring"Invites sent successfully." when accepted, whether the invite is sent now, scheduled for later, or ignored as a duplicate; otherwise why the contact was not invited.

Important

The returned id identifies the contact, not the invite. Contacts are matched by email or phone within the campaign's contact list: if either matches an existing contact, that contact is updated with the details you send and its existing id is returned. Campaigns that share a contact list return the same id for the same person.

Duplicate protection: if the contact was sent an invite (on any channel, and not failed) within the campaign's duplicate window (default 14 days), the request still returns 202 with the contact's id, but no invite is scheduled and an "ignored" activity is logged. The contact details you sent are still saved.

The duplicate window only counts invites that have already been sent. Submitting a contact again while their invite is still waiting (because of send_after_hours or the send window) is not treated as a duplicate, and the send time is recalculated from the latest request.

Returning customers whose last invite was sent outside the duplicate window are invited again.

Unsubscribed contacts will not receive new invites, even via the API. The request still returns 202. Their opt-out is always respected.

Invites respect the campaign's configured send window (UTC). Requests outside the window are scheduled for the start of the next window.

Delivery channels (email and SMS, with WhatsApp coming soon) depend on your campaign step configuration. Providing both email and phone maximises reach.

Track each invite with GET /api/v1/request-reviews/invites/{id}, using the id this endpoint returns (see Invite status below).

This endpoint does not accept an idempotency key, external reference, or custom metadata. Fields not listed above are ignored and not stored, and the X-Correlation-Id header applies to the MCP endpoint only. If a response is lost, check the contact in your dashboard before submitting again.

Errors: 401 invalid token, 403 token lacks request:create or the token owner cannot edit this campaign's location, 404 campaign UUID not found, 422 validation failed (for example an invalid phone number).

GET/api/v1/request-reviews/invites/{id}

Invite status

Where a review request stands, by the id the Send review invite endpoint returned: its status, every message sent or tried (with the reason when one failed and when it is retried), the next message still to come or why nothing more will be sent, and what the contact did. It is read from the same records and rules as the contact's activity in your dashboard. Inviting the same person again returns the same id, so the answer describes their newest invite.

Requires request:read

Path parameters

ParameterTypeDescription
iduuidThe id the Send review invite endpoint returned (required).

Example request

curl https://app.your-white-label.com/api/v1/request-reviews/invites/c7d8e9f0-1234-4678-abcd-ef9876543210 \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": {
    "id": "c7d8e9f0-1234-4678-abcd-ef9876543210",
    "campaign": { "id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "name": "Post-Visit Follow Up" },
    "contact": { "first_name": "Sarah", "last_name": null, "email": "[email protected]", "phone": "+15551234567" },
    "subscription": "subscribed",
    "status": "opened",
    "status_at": "2026-10-15T14:02:11.000000Z",
    "completed": null,
    "invited_at": "2026-10-15T13:00:04.000000Z",
    "next_message": {
      "step": 2,
      "channels": ["sms"],
      "state": "scheduled",
      "send_at": "2026-10-18T14:00:00.000000Z",
      "due_since": null,
      "waiting_for": ["send_window"],
      "email_paused_until": null
    },
    "next_message_known": true,
    "stopped": null,
    "messages": [
      {
        "step": 1, "channel": "email", "status": "sent",
        "created_at": "2026-10-15T13:15:01.000000Z", "sent_at": "2026-10-15T13:15:02.000000Z",
        "delivered_at": null, "read_at": null, "failed_at": null, "error": null
      }
    ],
    "events": [
      { "type": "added", "at": "2026-10-15T13:00:04.000000Z", "step": null, "channel": null, "rating": null, "source": null, "reason": null },
      { "type": "invited", "at": "2026-10-15T13:15:02.000000Z", "step": 1, "channel": "email", "rating": null, "source": null, "reason": null },
      { "type": "opened", "at": "2026-10-15T14:02:11.000000Z", "step": 1, "channel": "email", "rating": null, "source": null, "reason": null }
    ],
    "earlier_invites": 0
  }
}

Response fields

FieldTypeDescription
statusstringWhere the newest invite stands, by the same rules as the status on your Contacts page: waiting (nothing sent yet), invited (sent), ignored (not sent: a request went out within the duplicate window), opened, clicked, video_played, reviewed (a star rating was picked in the request), completed (went to a review site, left a review on your form, or gave private feedback), bounced (email bounced, or SMS or WhatsApp not delivered), complained (marked as spam), unsubscribed, or not_invited (your blocked list, an invalid email or phone, or the contact had unsubscribed or is not subscribed).
status_atdatetime | nullWhen that status was reached. null for not_invited when your blocked list or an invalid address keeps the contact from being invited.
completedobject | nullWhen the status is completed: type (redirected, testimonial_submitted or private_feedback_given), the star rating picked and the review site (source).
subscriptionstringsubscribed, unconfirmed or unsubscribed.
invited_atdatetimeWhen the newest invite was received.
next_messageobject | nullThe next message still to come. state: scheduled, due (goes with the next send run, every 15 minutes), sending (on the send queue) or paused (the campaign is paused; send_at is then null). waiting_for: send_window, campaign_start, retry_cooldown (24 hours after a failed attempt) or recently_invited (the duplicate window). due_since is set when it is late; email_paused_until when your email provider asked to pause.
next_message_knownbooleanfalse in the rare case the next message could not be worked out just now: next_message and stopped are then null without meaning nothing is coming. Ask again later.
stoppedobject | nullWhy nothing more will be sent: reason (finished, responded, undelivered, unsubscribed, suppressed, invalid_identifier, no_address, retries_exhausted, whatsapp_unreachable, campaign_deleted, cannot_send, or unavailable when your blocked list could not be checked just now) and a message.
messagesarrayEvery message of this invite sent or tried, oldest first. status: sent (accepted by the email, SMS or WhatsApp provider), failed, skipped (not attempted, for example no credits or no provider) or sending (no outcome recorded yet). delivered_at and read_at come from WhatsApp receipts. A failed or skipped message has an error with its code, a message, resolved when it no longer matters, and retry: scheduled (at retry_at), paused or exhausted.
eventsarrayWhat happened, oldest first, as on the contact's activity: type (added, invited, ignored, not_invited, opened, clicked, video_played, reviewed, redirected, testimonial_submitted, private_feedback_given, bounced, complained or unsubscribed; bounced also covers an SMS or WhatsApp message that was not delivered), the message step and channel it concerns, the star rating, the review site (source) and, for not_invited, the reason. Repeated star clicks from email security scanners are shown once, as in the dashboard.
earlier_invitesintegerInvites this contact received before the newest one.

Important

All times are UTC.

An email open can come from the reader's mail app or a security scanner rather than the person.

Errors: 401 invalid token, 403 token lacks request:read, 404 no invite with that id in the organisations and locations the token's owner can see.

GET/api/v1/sources

List review sources

Retrieve all available review sources (Google, Facebook, Yelp, Trustpilot, etc.) with their capabilities and logos.

Requires Any valid token

Example request

curl https://app.your-white-label.com/api/v1/sources \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": [
    {
      "id": 1,
      "name": "Google",
      "url": "https://google.com",
      "logo": "https://...",
      "available": true,
      "can_collect_reviews": true,
      "deep_linking_supported": true
    }
  ]
}
GET/api/v1/countries

List countries

Retrieve the full list of supported countries with ISO 3166-1 alpha-2 codes. Useful for populating country selectors.

Requires Any valid token

Example response 200 OK

[
  { "id": "US", "name": "United States" },
  { "id": "GB", "name": "United Kingdom" },
  { "id": "CA", "name": "Canada" },
  ...
]
GET/api/v1/me

Current user

Retrieve the authenticated user's basic information. Useful for verifying your API token.

Requires Any valid token

Example response 200 OK

{
  "id": 1,
  "name": "John Smith",
  "email": "[email protected]"
}
GET/api/v1/gbp/metrics

Google Business Profile metrics

Aggregated impressions (search, maps, desktop, mobile), call clicks, website clicks, and direction requests for one location over a date range. The response also includes the totals for the equal-length window immediately before the requested period, so you can compute trend deltas without a second call.

Requires reviews:read

Query parameters

ParameterTypeDescription
location_idintegerInternal location ID (required, from /api/v1/locations).
fromdateInclusive start date in Y-m-d format. Defaults to 29 days before the to date (a 30-day window), or to 30 days ago when no to date is given.
todateInclusive end date in Y-m-d format. Defaults to yesterday.
include_dailybooleanInclude the per-day rows in the response. Default false.

Example request

curl "https://app.your-white-label.com/api/v1/gbp/metrics?location_id=123&from=2026-04-01&to=2026-04-30" \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": {
    "location_id": 123,
    "organization_id": 45,
    "period": { "from": "2026-04-01", "to": "2026-04-30" },
    "totals": {
      "impressions_total": 21110,
      "impressions_search": 12345,
      "impressions_maps": 8765,
      "impressions_desktop": 6543,
      "impressions_mobile": 14567,
      "call_clicks": 89,
      "website_clicks": 234,
      "direction_requests": 156
    },
    "previous_period": {
      "from": "2026-03-02",
      "to": "2026-03-31",
      "totals": { "impressions_total": 17800 }
    }
  }
}

Important

Each token only sees the locations its user can open in the dashboard. A team member with restricted role gets 403 location_access_denied for locations outside their scope.

Profile views and Photo views are no longer available from the Google Performance API and are not returned, even when present in older data. Impressions, calls, direction requests, website clicks, and search query terms are still available.

Maximum date range is 540 days. Wider windows return 422 invalid_date_range so you can chunk the request.

GET/api/v1/gbp/search-terms

GBP search query terms

The search query terms shoppers used to find this location, with their impression counts, ordered by impressions descending. Below-threshold rows (Google masks impression counts for very low volume terms) are returned with below_threshold=true and sorted to the bottom of the list.

Requires reviews:read

Query parameters

ParameterTypeDescription
location_idintegerInternal location ID (required).
yearintegerDefaults to the current year.
monthinteger1-12. Omit to return every month in the year.
per_pageintegerDefault 50, max 200.
pageinteger1-based page number.

Example request

curl "https://app.your-white-label.com/api/v1/gbp/search-terms?location_id=123&year=2026&month=4" \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": [
    {
      "keyword": "emergency dentist near me",
      "year": 2026,
      "month": 4,
      "month_label": "Apr 2026",
      "impressions": 234,
      "below_threshold": false,
      "location_id": 123,
      "organization_id": 45
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 87,
    "location_id": 123,
    "organization_id": 45,
    "year": 2026,
    "month": 4
  }
}

Important

Same per-token, per-location access rules as the metrics endpoint. A 403 location_access_denied means the caller cannot see this location.

Below-threshold rows still appear in the list so you can show "Google masked this keyword" instead of leaving a gap in the report.

Agency API

The Agency API lets you manage your customers programmatically. Create accounts, switch plans, adjust limits, manage credits, handle NFC orders, pull Local Search Grid data, and set up the SMS providers your customers' texts go through. These endpoints use the same authentication but require an agency-level API token generated from the agency account. None of the Local Search Grid or SMS provider endpoints below are reachable by your customers, even if they hold their own API token.

Base URL

https://app.your-white-label.com/api/agency/v1

Agency tokens have full access across all customer accounts. There are no scoped permissions here, so the token acts as a super admin.

POST/api/agency/v1/customers

Create customer

Create a new customer account. Optionally email them their login details and a secure one-click link to connect their Google Business Profile and/or Facebook Page without ever logging into the platform.

Request body

ParameterTypeDescription
namestringCustomer name (required)
companystringOrganisation/company name (required)
emailstringLogin email address (required)
passwordstringPassword, min 8 characters (required)
custom_plan_idstringPlan ID to assign (required)
phonestringPhone in E.164 format (optional)
location_limitintegerOverride plan location limit (optional; 0 = unlimited)
member_limitintegerOverride plan member limit. 0 = unlimited (optional)
send_invitebooleanEmail login details to the customer (optional)
send_google_connect_linkbooleanEmail a secure one-click link to connect their Google Business Profile. The customer signs in directly with Google, no platform login needed. The link is bound to their auto-created default location and is valid for 7 days (optional).
send_facebook_connect_linkbooleanSame as send_google_connect_link but for Facebook Pages. Independent of the Google flag: send one, the other, both, or neither (optional).
countrystringISO 3166-1 alpha-2 code. Required if Stripe Tax is enabled.
postal_codestringRequired for US/CA when Stripe Tax is enabled

Example request

curl -X POST https://app.your-white-label.com/api/agency/v1/customers \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "company": "My Clinic",
    "email": "[email protected]",
    "password": "Password123456",
    "custom_plan_id": "2",
    "send_invite": true,
    "send_google_connect_link": true,
    "send_facebook_connect_link": false
  }'

Example response 200 OK

{
  "data": {
    "id": 1,
    "name": "John Smith",
    "email": "[email protected]",
    "phone": null,
    "language": "en",
    "trial_ends_at": null,
    "created_at": "2024-09-26T19:57:52.000000Z",
    "updated_at": "2024-09-26T19:57:52.000000Z",
    "custom_plan": { "id": 2, "name": "Pro" },
    "organizations": [{ "id": 1, "name": "My Clinic" }]
  }
}

Notes

  • send_google_connect_link and send_facebook_connect_link are independent. Set neither, one, or both.
  • Each connect link email goes through your configured transactional email provider (the same provider used for invites and other transactional sends) and appears in your transactional mail log.
  • A delivery failure on either provider is logged but does not block the customer record from being created. The customer is always returned with 200/201.
  • When the customer clicks the link, they sign in directly with Google or Facebook. They never see a platform login screen. The integration is auto-attached to their default location.
  • You can revoke or re-issue a connect link at any time from the customer's integration manager in the UI.
PUT/api/agency/v1/customers/{customer}

Switch customer plan

Change the customer's assigned plan.

Request body

ParameterTypeDescription
custom_plan_idstringThe plan ID to switch to (required)

Example request

curl -X PUT https://app.your-white-label.com/api/agency/v1/customers/{customer} \
  -H "Authorization: Bearer {token}" \
  -d custom_plan_id="2"

Example response 200 OK

{
  "data": {
    "id": 1,
    "name": "John Smith",
    "email": "[email protected]",
    "custom_plan": { "id": 2, "name": "Pro" },
    "organizations": [{ "id": 1, "name": "My Clinic" }]
  }
}
PUT/api/agency/v1/customers/{customer}/location-limit

Update location & member limits

Override the customer's location or member limit independently of their plan defaults. Two separate endpoints.

Request body

ParameterTypeDescription
location_limitintegerPUT .../location-limit: number of locations allowed (0 = unlimited)
member_limitintegerPUT .../member-limit: number of team members allowed (0 = unlimited)

Example request

# Update location limit
curl -X PUT https://app.your-white-label.com/api/agency/v1/customers/{customer}/location-limit \
  -H "Authorization: Bearer {token}" \
  -d location_limit="5"

# Update member limit
curl -X PUT https://app.your-white-label.com/api/agency/v1/customers/{customer}/member-limit \
  -H "Authorization: Bearer {token}" \
  -d member_limit="10"

Example response 200 OK

{ "message": "Location limit updated successfully." }
// or
{ "message": "Member limit updated successfully." }
POST/api/agency/v1/customers/{customer}/add-credits

Add credits

Add email or SMS credits to a customer's account. Credits can optionally expire.

Request body

ParameterTypeDescription
typestringCredit type: "email" or "sms" (required)
creditsintegerNumber of credits to add, min 1 (required)
expires_atdateExpiry date in Y-m-d format (optional)
notesstringNote visible to the customer (optional)

Example request

curl -X POST https://app.your-white-label.com/api/agency/v1/customers/{customer}/add-credits \
  -H "Authorization: Bearer {token}" \
  -d type="email" \
  -d credits="1000"

Example response 200 OK

{
  "message": "Credits added successfully.",
  "balance": 250
}
PUT/api/agency/v1/customers/{customer}/pause

Pause & resume subscription

Pause or resume a customer's subscription. Only available when the plan is not linked to Stripe (for Stripe-managed subscriptions, use Stripe's native pause).

Example request

# Pause subscription
curl -X PUT https://app.your-white-label.com/api/agency/v1/customers/{customer}/pause \
  -H "Authorization: Bearer {token}"

# Resume subscription
curl -X PUT https://app.your-white-label.com/api/agency/v1/customers/{customer}/resume \
  -H "Authorization: Bearer {token}"

Example response 200 OK

{ "message": "Subscription has been paused." }
// or
{ "message": "Subscription has been resumed." }
DELETE/api/agency/v1/customers/{customer}

Delete customer

Permanently delete a customer account.

Example request

curl -X DELETE https://app.your-white-label.com/api/agency/v1/customers/{customer} \
  -H "Authorization: Bearer {token}"

Example response 200 OK

{ "message": "Customer deleted successfully." }
GET/api/agency/v1/customers

List all customers

Retrieve a paginated list of all your customers with their plans and organisations.

Parameters

ParameterTypeDescription
searchstringSearch by name or email (optional)

Example request

curl https://app.your-white-label.com/api/agency/v1/customers \
  -H "Authorization: Bearer {token}"

Example response 200 OK

{
  "data": [
    {
      "id": 1,
      "name": "John Smith",
      "email": "[email protected]",
      "phone": null,
      "language": "en",
      "trial_ends_at": "2023-08-24T16:57:57.000000Z",
      "created_at": "2023-07-25T16:57:57.000000Z",
      "updated_at": "2023-08-04T15:01:11.000000Z",
      "custom_plan": { "id": 2, "name": "Pro" },
      "organizations": [{ "id": 2, "name": "My Clinic" }]
    }
  ],
  "links": { ... },
  "meta": { "current_page": 1, "from": 1, "per_page": 10, "to": 10 }
}
GET/api/agency/v1/custom-plans

List all plans

Retrieve all custom plans you've created. Use the plan ID when creating customers or switching plans.

Example request

curl https://app.your-white-label.com/api/agency/v1/custom-plans \
  -H "Authorization: Bearer {token}"

Example response 200 OK

{
  "data": [
    {
      "id": 1,
      "stripe_monthly_id": "",
      "stripe_yearly_id": "",
      "name": "Basic",
      "is_default": false,
      "is_hidden": false,
      "is_free": true,
      "updated_at": "2024-09-26T10:19:58.000000Z",
      "created_at": "2023-07-25T15:14:02.000000Z"
    }
  ]
}
GET/api/agency/v1/orders

Orders (NFC products)

Manage NFC product orders. List all orders, mark as shipped (with optional tracking URL), complete, or cancel.

Example request

# List orders
curl https://app.your-white-label.com/api/agency/v1/orders \
  -H "Authorization: Bearer {token}"

# Ship order (with optional tracking URL)
curl -X PUT https://app.your-white-label.com/api/agency/v1/orders/{order}/ship \
  -H "Authorization: Bearer {token}" \
  -d tracking_url="https://tracking.example.com/123"

# Complete order
curl -X PUT https://app.your-white-label.com/api/agency/v1/orders/{order}/complete \
  -H "Authorization: Bearer {token}"

# Cancel order
curl -X PUT https://app.your-white-label.com/api/agency/v1/orders/{order}/cancel \
  -H "Authorization: Bearer {token}"

Example response 200 OK

{
  "data": [
    {
      "id": "27d2ba02-...",
      "order_number": "HUFTMX-1733678942",
      "email": "[email protected]",
      "total": 49.99,
      "currency": "usd",
      "status": "completed",
      "shipping": {
        "name": "John Smith",
        "address": "49 Featherstone Street",
        "city": "London",
        "country": "GB",
        "tracking_url": null
      },
      "items": [
        {
          "product_name": "Google Review Card",
          "quantity": 1,
          "unit_price": 29.99,
          "nfc_urls": ["https://your-domain.com/nfc/..."]
        }
      ]
    }
  ]
}
GET/api/agency/v1/scans

List Local Search Grid scans

Paginated metadata for every Local Search Grid scan the agency owns, newest first. Filter by schedule, completion state, recency, or free-text. Restricted to the tenant owner.

Parameters

ParameterTypeDescription
searchstringFree-text over location and keyword.
is_scheduledbooleanOnly recurring scans.
completedbooleantrue: scans whose latest run has ended, whether or not it failed (add failed=false to leave failed runs out). false: every other scan, such as one whose run is in progress. Starting a run clears completed_at, so a scan with earlier snapshots counts as false while that run is in progress.
failedbooleanOnly scans whose last run failed.
since_daysintegerLimit to scans created in the last N days (1-365).
per_pageinteger1-100, default 20.
pageinteger1-based page number.

Example request

curl "https://app.your-white-label.com/api/agency/v1/scans?completed=true&since_days=30" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": [
    {
      "uuid": "4f3a3b6c-...",
      "location": "Acme Dental, Downtown",
      "keyword": "dentist near me",
      "keywords": ["dentist near me", "emergency dentist"],
      "grid_size": 7,
      "is_scheduled": true,
      "is_running": false,
      "last_run_at": "2026-04-15T10:30:00+00:00",
      "next_run_at": "2026-05-01T13:00:00+00:00"
    }
  ],
  "meta": { "current_page": 1, "per_page": 20, "total": 24 }
}

Notes

  • Customers on your platform never see these endpoints, even with their own API token. Authorization is gated on tenant ownership, not just the use_api plan option.
GET/api/agency/v1/scans/{uuid}

Get a Local Search Grid scan

Returns one scan with its per-pin results for the requested snapshot. Defaults to the most recent snapshot; pass snapshot_at to load a historical one. Each pin's top_results list is capped at top_n (0-20, default 5) so the response stays bounded on large grids. For paginated per-pin access, use the data_points endpoint below.

Parameters

ParameterTypeDescription
uuidstringScan UUID (required path parameter).
snapshot_atdatetimeISO-8601 timestamp from available_snapshots. Defaults to the latest snapshot.
top_nintegerSERP entries per pin (0-20). Default 5. Pass 20 for the full SERP list per pin.

Example request

curl "https://app.your-white-label.com/api/agency/v1/scans/4f3a3b6c-...?snapshot_at=2026-04-15T10:30:00Z&top_n=5" \
  -H "Authorization: Bearer {token}"

Example response 200 OK

{
  "data": {
    "uuid": "4f3a3b6c-...",
    "location": "Acme Dental, Downtown",
    "keyword": "dentist near me",
    "keywords": ["dentist near me", "emergency dentist"],
    "grid_size": 7,
    "is_running": false,
    "summary": {
      "average_rank": 5.2,
      "top_3_count": 12,
      "top_4_to_10_count": 23,
      "not_ranking_count": 14
    },
    "report_url": "https://app.your-white-label.com/scans/4f3a3b6c-.../report",
    "available_snapshots": [
      "2026-04-01T10:30:00+00:00",
      "2026-04-15T10:30:00+00:00",
      "2026-05-01T10:30:00+00:00"
    ],
    "results": [
      {
        "lat": 40.71, "lng": -74.00, "rank": 3,
        "keyword": "dentist near me", "status": "complete",
        "top_results": [
          { "place_id": "ChIJ...", "name": "Acme Dental", "rank": 1 }
        ]
      }
    ]
  }
}

Notes

  • For large grids (15×15 with multi-keyword scans), prefer the data_points endpoint below. It is paginated and lean, returning only what most rank-tracker integrations need.
GET/api/agency/v1/scans/{uuid}/data_points

LSG pin data (paginated)

Lean, paginated per-pin data designed for rank-tracker integrations and pin-layer heatmap renderers. Returns one row per pin with the target business's rank and the top-N competitors (place_id, name, rank). Always paginated, so the response size is bounded regardless of grid scale.

Parameters

ParameterTypeDescription
uuidstringScan UUID (required path parameter).
snapshot_atdatetimeISO-8601 timestamp. Defaults to the latest snapshot for the (scan, keyword) combo.
keywordstringRestrict to one keyword on multi-keyword scans.
top_nintegerCompetitors per pin (0-20). Default 5. Pass 0 for just lat/lng/target_rank.
per_pageinteger1-500. Default 100.
pageinteger1-based.

Example request

curl "https://app.your-white-label.com/api/agency/v1/scans/4f3a3b6c-.../data_points?per_page=100&top_n=5" \
  -H "Authorization: Bearer {token}"

Example response 200 OK

{
  "data": [
    {
      "lat": 39.96,
      "lng": -86.28,
      "keyword": "dentist near me",
      "snapshot_at": "2026-04-15T10:30:00+00:00",
      "target_rank": 4,
      "results": [
        { "place_id": "ChIJ...", "name": "Acme Dental", "rank": 1 },
        { "place_id": "ChIJ...", "name": "Best Smiles", "rank": 2 }
      ]
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": {
    "current_page": 1,
    "per_page": 100,
    "total": 1125,
    "scan_uuid": "4f3a3b6c-...",
    "snapshot_at": "2026-04-15T10:30:00+00:00",
    "keyword": "dentist near me",
    "top_n": 5
  }
}

Notes

  • target_rank is null when the target business was not found in the top 20 at that pin (the in-app UI labels this "NR").
  • Scans with no completed snapshots return 200 with data: [] and meta.total: 0 so pollers can branch on meta.total rather than HTTP status.
  • A 13×13 × 6-keyword scan is 1,014 pins per snapshot. With per_page=100 that is 11 pages.
GET/api/agency/v1/scans/{uuid}/snapshots

Snapshot history

Aggregated rank distribution and visibility score for every snapshot the scan has produced. Each row is one snapshot. Use this to plot a long-range trend without paging through every pin.

Parameters

ParameterTypeDescription
uuidstringScan UUID (required path parameter).
keywordstringRestrict the aggregate to one keyword on a multi-keyword scan.

Example request

curl "https://app.your-white-label.com/api/agency/v1/scans/4f3a3b6c-.../snapshots?keyword=dentist+near+me" \
  -H "Authorization: Bearer {token}"

Example response 200 OK

{
  "data": [
    {
      "snapshot_at": "2026-04-01T10:30:00+00:00",
      "label": "1 April 2026 10:30",
      "short_label": "1 Apr",
      "month_year": "April 2026",
      "avg_rank": 12.1,
      "change_from_previous": 0.0,
      "top_3_count": 3,
      "top_10_count": 9,
      "below_top_10_count": 8,
      "not_ranking_count": 5,
      "total_pins": 25,
      "visibility_score": 18.6
    }
  ]
}

Notes

  • change_from_previous is the delta vs the previous snapshot's avg_rank. Negative values mean the average rank improved (lower is better).
GET/api/agency/v1/scans/{uuid}/insights

Deep insights

Everything the in-app report computes: summary stats, long-range trends, snapshot-over-snapshot deltas, geographic quadrant strength, top competitors, and rule-based recommendations. Defaults to the latest snapshot.

Parameters

ParameterTypeDescription
uuidstringScan UUID (required path parameter).
keywordstringRestrict to one keyword on multi-keyword scans.
snapshot_atdatetimeISO-8601 timestamp; default is the latest snapshot.

Example request

curl "https://app.your-white-label.com/api/agency/v1/scans/4f3a3b6c-.../insights" \
  -H "Authorization: Bearer {token}"

Example response 200 OK

{
  "data": {
    "scan_uuid": "4f3a3b6c-...",
    "snapshot_at": "2026-05-01T10:30:00+00:00",
    "keyword": "dentist near me",
    "summary": {
      "avg_rank": 7.3,
      "visibility_score": 24.5,
      "top_3_pins": 4,
      "top_10_pins": 9,
      "not_ranking": 5,
      "total_pins": 25
    },
    "trends_vs_first_snapshot": {
      "first_snapshot_at": "2026-04-01T10:30:00+00:00",
      "start_avg": 12.1,
      "current_avg": 7.3,
      "change": -4.8,
      "improved": true,
      "percent_change": 39.7
    },
    "trends_vs_previous_snapshot": {
      "previous_snapshot_at": "2026-04-15T10:30:00+00:00",
      "avg_rank_change": -1.2,
      "visibility_change": 3.1,
      "top_3_change": 1,
      "top_10_change": 2
    },
    "geographic_strength": [
      { "label": "North", "pins": 7, "avg_rank": 8.0, "visibility": 18.2, "coverage": 86 }
    ],
    "top_competitors": [
      { "name": "Competitor One", "avg_rank": 3.2, "visibility": 45.6, "threat_score": 60.0 }
    ],
    "recommendations": [
      { "type": "warning", "icon": "eye-off", "title": "Low visibility", "description": "..." }
    ]
  }
}

Notes

  • Scans with no completed snapshots still return 200 with summary: null. Branch on field presence rather than HTTP status.
POST/api/agency/v1/scans

Create a scan

Creates a brand-new Local Search Grid scan, generates the hex-ring pin grid server-side, and queues the first snapshot immediately. Returns 202 Accepted with the new scan UUID. Subscribe to scan-completed to be notified when the snapshot finishes.

Request body

ParameterTypeDescription
locationstringHuman-readable name (required). Shows in the dashboard.
addressstringUsed only if lat/lng are not supplied (server geocodes via Google Maps).
keywordsarray<string>1-20 keyword strings (required).
grid_sizeintegerOne of 3, 5, 7, 9, 11, 13, 15 (required).
distancenumberDistance from the center to the outer ring, greater than 0, max 50 (required).
distance_unitstring"km" or "miles" (required).
typestring"business" (default) or "sab" for service-area businesses.
target_place_idstringGoogle Place ID, used to score "self" pins in competitor analysis.
latnumberPin grid center latitude.
lngnumberPin grid center longitude.

Example request

curl -X POST https://app.your-white-label.com/api/agency/v1/scans \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "location": "Acme Dental, Downtown",
    "keywords": ["dentist near me", "emergency dentist"],
    "grid_size": 7,
    "distance": 2.0,
    "distance_unit": "miles",
    "target_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
    "lat": 42.3601,
    "lng": -71.0589
  }'

Example response 202 Accepted

{
  "data": {
    "uuid": "4f3a3b6c-...",
    "started_at": "2026-05-12T11:45:00+00:00",
    "is_running": true
  }
}

Notes

  • Coordinate resolution order: (target_place_id + lat + lng) is used as-is; (lat + lng) only is used as-is; address only is geocoded via your LocalSearchGridProvider's Google Maps key. If geocoding fails the call returns 422 missing_coords.
  • A 422 provider_not_configured response means you have not configured DataForSEO + Google Maps credentials yet. Wire them up in Settings then retry.
  • A 422 invalid_grid_params response means the grid_size and distance combination is unsupported (for example, the center landing at the geographic poles).
POST/api/agency/v1/scans/{uuid}/run

Re-run a scan

Snaps a new snapshot using the saved grid, keywords, and distance. Returns 202 Accepted immediately and fires the scan-completed webhook (or scan-failed if the run errors) once the snapshot finishes.

Example request

curl -X POST https://app.your-white-label.com/api/agency/v1/scans/4f3a3b6c-.../run \
  -H "Authorization: Bearer {token}"

Example response 202 Accepted

{
  "data": {
    "uuid": "4f3a3b6c-...",
    "started_at": "2026-05-12T12:00:00+00:00",
    "is_running": true
  }
}

Notes

  • A 409 response means the scan is already running. Wait for the current snapshot to finish or subscribe to the webhook instead of polling.
  • A 422 response means the scan has no provider configured, no keywords, or no saved pins. Open the scan in the dashboard to confirm.
  • Bulk-create burst protection: scans 6+ in a 60-second window get a per-scan stagger on their first snapshot to keep DataForSEO from throttling. Scheduled re-runs are unaffected.
PUT/api/agency/v1/scans/{uuid}

Update a scan

Updates an existing scan without abandoning its snapshot history. All body fields are optional (PATCH-like on PUT). Metadata changes (location, address, target_place_id, type, keywords) are always allowed. Geometry changes (grid_size, distance, distance_unit, lat, lng) are allowed when the scan has no completed snapshots, or with regenerate_pins=true when it does.

Request body

ParameterTypeDescription
locationstringDisplay name shown in the dashboard.
addressstringDisplay-only.
keywordsarray<string>Full replacement set, 1-20 strings, each ≤ 100 chars.
target_place_idstringGoogle Place ID. Used to score "self" in competitor analysis.
typestring"business" or "sab".
grid_sizeintegerGeometry. One of 3, 5, 7, 9, 11, 13, 15.
distancenumberGeometry. > 0 and ≤ 50.
distance_unitstringGeometry. "km" or "miles".
latnumberGeometry. New pin grid center latitude.
lngnumberGeometry. New pin grid center longitude.
regenerate_pinsbooleanRequired when changing any geometry field on a scan that already has completed snapshots. Acknowledges that future snapshots will use a new pin grid and are not geometrically comparable with the historical trail.

Example request

# Metadata-only update (always allowed)
curl -X PUT https://app.your-white-label.com/api/agency/v1/scans/4f3a3b6c-... \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "location": "Acme Dental, Uptown" }'

# Geometry resize on a scan with snapshots
curl -X PUT https://app.your-white-label.com/api/agency/v1/scans/4f3a3b6c-... \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "grid_size": 9,
    "distance": 3.0,
    "regenerate_pins": true
  }'

Example response 200 OK

{
  "data": {
    "uuid": "4f3a3b6c-...",
    "location": "Acme Dental, Uptown",
    "grid_size": 9,
    "distance": 3.0
    /* … */
  }
}

Notes

  • On geometry changes the server regenerates selected_pins from the new lat/lng + grid_size + distance. Historical scan_results rows stay queryable by snapshot_at.
  • A 422 geometry_change_requires_acknowledgement response means the scan has completed snapshots and regenerate_pins=true was not passed.
  • Archived scans must be restored before update; PUT against an archived UUID returns 404.
POST/api/agency/v1/scans/{uuid}/archive

Archive or restore a scan

Archive (soft-delete) a scan to remove it from the active list and stop scheduled snapshots without losing history. Restore brings it back. Both endpoints are idempotent so retries are safe.

Example request

# Archive
curl -X POST https://app.your-white-label.com/api/agency/v1/scans/4f3a3b6c-.../archive \
  -H "Authorization: Bearer {token}"

# Restore
curl -X POST https://app.your-white-label.com/api/agency/v1/scans/4f3a3b6c-.../restore \
  -H "Authorization: Bearer {token}"

# List only archived scans (for restore workflows)
curl "https://app.your-white-label.com/api/agency/v1/scans?archived_only=true" \
  -H "Authorization: Bearer {token}"

# Include archived alongside active in a normal list
curl "https://app.your-white-label.com/api/agency/v1/scans?include_archived=true" \
  -H "Authorization: Bearer {token}"

Example response 200 OK

{
  "data": {
    "uuid": "4f3a3b6c-...",
    "is_scheduled": true,
    "next_run_at": null
    /* … */
  }
}

Notes

  • Archive clears next_run_at so the cron skips the scan, but preserves frequency, scheduled_from, scheduled_to, scheduled_days, and timezone so a future restore re-arms cleanly.
  • Restore on a scheduled scan recomputes next_run_at from the current clock.
  • Idempotent: archiving an already-archived scan (or restoring an active one) returns 200 with the scan resource and no error.
POST/api/agency/v1/scans/{uuid}/schedule

Schedule recurring scans (set / get / unset)

POST sets or unsets a recurring schedule. GET on the same path returns just the schedule fields for audit workflows that iterate "list scans → check each schedule" without pulling the full scan resource. The cron worker picks up scheduled scans every 15 minutes and triggers a new snapshot whenever next_run_at falls inside the configured day-of-week and time-of-day window.

Request body

ParameterTypeDescription
is_scheduledbooleantrue turns the schedule on, false disables it (required).
frequencystring"weekly", "bi-weekly", or "monthly" (required when enabling).
scheduled_fromstring24-hour HH:MM, e.g. "09:00" (required when enabling).
scheduled_tostring24-hour HH:MM, must be strictly later than scheduled_from.
scheduled_daysarray<integer>Day numbers (Carbon style: 0 = Sunday, 6 = Saturday).
timezonestringPHP DateTimeZone identifier, e.g. "America/New_York".

Example request

# Read the current schedule
curl https://app.your-white-label.com/api/agency/v1/scans/4f3a3b6c-.../schedule \
  -H "Authorization: Bearer {token}"

# Enable a Mon-Fri 9-5 monthly schedule in New York time
curl -X POST https://app.your-white-label.com/api/agency/v1/scans/4f3a3b6c-.../schedule \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "is_scheduled": true,
    "frequency": "monthly",
    "scheduled_from": "09:00",
    "scheduled_to": "17:00",
    "scheduled_days": [1, 2, 3, 4, 5],
    "timezone": "America/New_York"
  }'

# Disable
curl -X POST https://app.your-white-label.com/api/agency/v1/scans/4f3a3b6c-.../schedule \
  -H "Authorization: Bearer {token}" \
  -d '{ "is_scheduled": false }'

Example response 200 OK

{
  "data": {
    "uuid": "4f3a3b6c-...",
    "is_scheduled": true,
    "frequency": "monthly",
    "next_run_at": "2026-06-01T13:00:00+00:00",
    "scheduled_from": "09:00",
    "scheduled_to": "17:00",
    "scheduled_days": [1, 2, 3, 4, 5],
    "timezone": "America/New_York"
  }
}

Notes

  • The first scheduled run lands within ~15 minutes of next_run_at (the cron tick cadence).
  • Disabling clears next_run_at but preserves your schedule fields, so re-enabling does not require re-entering them.
  • A 422 invalid_schedule_window response means scheduled_from was not earlier than scheduled_to. A 422 invalid_timezone means the string is not a recognised DateTimeZone identifier.
GET/api/agency/v1/sms-providers/types

SMS provider types

Every SMS provider type the API can set up, in the dashboard's order, with the fields each one takes under credentials, sender and settings, which of them are secret, how the connection is checked, and what stays in the dashboard. Read it before setting up a provider: the fields differ per type.

Example request

curl https://app.your-white-label.com/api/agency/v1/sms-providers/types \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": [
    {
      "transport": "twilio",
      "label": "Twilio",
      "credentials": [
        { "name": "sid", "label": "Account SID", "secret": false, "required": true, "help": "Starts with AC, 34 characters." },
        { "name": "token", "label": "Auth token", "secret": true, "required": true, "help": "At least 32 characters." }
      ],
      "sender": [
        { "name": "phone", "label": "Twilio number to send from", "required": "to finish setup; leave it out to save the credentials and choose a number later" },
        { "name": "phone_country", "label": "Toll-free country", "required": "for a +1 toll-free number" }
      ],
      "settings": [],
      "sender_capability": "both",
      "supports_mms": true,
      "dashboard_only": ["Buying or releasing numbers", "Regulatory compliance bundles", "Toll-free verification", "Alphanumeric sender IDs"]
    }
  ]
}

Notes

  • The SMS provider endpoints are for the agency owner only. Your customers never reach them, even with their own API token.
  • These endpoints need a REST API token. AI Hub connections cannot call them: the REST API refuses an AI Hub token with 403.
  • API keys and tokens are never returned. A response shows the last four characters of a long secret, or only ********.
  • A field an endpoint does not take is refused by name with a 422, never ignored. Other refusals carry message, code and, where it helps, fix.
GET/api/agency/v1/sms-providers

List SMS providers

The agency's SMS providers, oldest first, with whether each one is the default, whether it is ready to send and, when it is not, what is missing. GET /api/agency/v1/sms-providers/{id} returns one provider in the same shape.

Parameters

ParameterTypeDescription
searchstringMatches the provider's name.
per_pageinteger1-100, default 20.
pageinteger1-based page number.

Example request

curl https://app.your-white-label.com/api/agency/v1/sms-providers \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": [
    {
      "id": 12,
      "name": "Twilio (main)",
      "transport": "twilio",
      "transport_label": "Twilio",
      "default": true,
      "ready_for_use": true,
      "status": "ready",
      "status_message": "Ready to send.",
      "credentials": { "sid": "AC...", "token": "********9f2c" },
      "sender": { "phone": "+14155550123", "phone_country": "US" },
      "sender_capability": "both",
      "supports_mms": true,
      "organizations_count": 4,
      "manageable_via_api": true
    }
  ],
  "meta": { "current_page": 1, "per_page": 20, "total": 2, "last_page": 1 }
}

Notes

  • status is ready, or names what is missing, such as needs_number (Twilio), pending_verification (a toll-free number) or needs_registration (SignalHouse). status_message says it in words.
  • A provider of a type the API does not set up is listed with manageable_via_api false, every stored value masked, and a dashboard_url.
POST/api/agency/v1/sms-providers

Set up an SMS provider

Send the type and the fields its description lists. The connection is checked the way the dashboard checks it before anything is saved: when the provider refuses, nothing is saved and the answer is 422 verification_failed. The agency's first provider becomes its default.

Body

ParameterTypeDescription
transportstringThe provider type, from the types endpoint (required).
namestringDisplay name. The type's name when left out.
credentialsobjectWhat signs in to the provider, by the field names of its type.
senderobjectWho messages come from: a phone, a sender name or another sender field of its type.
settingsobjectOther fields the type takes, such as an Amazon SNS region.

Example request

curl -X POST https://app.your-white-label.com/api/agency/v1/sms-providers \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "twilio",
    "name": "Twilio (main)",
    "credentials": { "sid": "AC...", "token": "..." },
    "sender": { "phone": "+14155550123" }
  }'

Example response 201 Created

{
  "data": { "id": 12, "transport": "twilio", "status": "ready", "...": "..." },
  "warnings": [],
  "next_steps": []
}

Notes

  • Twilio uses a number already on the Twilio account. Leave out sender.phone to save the credentials first; the next step choose_number points to the numbers endpoint. A Messaging Service that already holds the number is reused, so its 10DLC registration is kept. A +1 toll-free number needs sender.phone_country (US or CA) and sends once Twilio approves its toll-free verification.
  • SignalHouse connects with its API token and is ready once its 10DLC registration is approved: the next step is register.
  • warnings say what still matters for delivery, such as a sender name the provider must register or a toll-free verification still pending.
PUT/api/agency/v1/sms-providers/{id}

Change, make default or delete an SMS provider

Send only what changes. Fields you send are merged over the saved ones and the connection is checked again; when the provider refuses, the saved provider is left as it was. A new name alone is saved without a check. The type cannot change: set up a new provider instead.

Body

ParameterTypeDescription
namestringNew display name.
credentialsobjectCredential fields to replace.
senderobjectSender fields to replace. For Twilio, sender.phone finishes a setup that waits for a number.
settingsobjectSetting fields to replace.

Example request

curl -X PUT https://app.your-white-label.com/api/agency/v1/sms-providers/12 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "credentials": { "token": "..." } }'

curl -X POST https://app.your-white-label.com/api/agency/v1/sms-providers/12/default \
  -H "Authorization: Bearer {token}"

curl -X DELETE https://app.your-white-label.com/api/agency/v1/sms-providers/12 \
  -H "Authorization: Bearer {token}"

Example response 200 OK

{
  "message": "SMS provider deleted.",
  "data": { "id": 12, "organizations_unassigned": 4, "was_default": false }
}

Notes

  • Only a provider that is ready to send can be the default.
  • Deleting a provider unassigns its organisations, so their messages use the default provider again. was_default true means the agency has no default until you choose one.
POST/api/agency/v1/sms-providers/{id}/test

Send a test SMS

Sends one real text through a ready provider. The provider charges for it as for any other message.

Body

ParameterTypeDescription
phonestringInternational format, or national with phone_country (required).
phone_countrystringTwo-letter country code.
messagestringUp to 1,600 characters; a short test line by default.

Example request

curl -X POST https://app.your-white-label.com/api/agency/v1/sms-providers/12/test \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+14155550188" }'

Example response 200 OK

{
  "message": "Test message sent.",
  "data": { "to": "+14155550188", "from": "+14155550123", "message": "This is a test message from Acme Agency." }
}

Notes

  • At most five tests a minute across the agency (429 rate_limited).
  • A number your imported blocks list is never texted, even as a test (422 recipient_blocked).
  • A provider error is returned as 502 send_failed, with any saved key removed from its text.
GET/api/agency/v1/sms-providers/{id}/numbers

Numbers to send from

For Twilio: the SMS-capable numbers on the account, with each toll-free number's verification status. Pass one as sender.phone to finish setup. For SignalHouse: the numbers you already own and numbers you can register. Buying or releasing Twilio numbers stays in the dashboard.

Query parameters (SignalHouse only)

ParameterTypeDescription
area_codestringPreferred area code, e.g. 614. Other numbers are shown when none are left in it.
countrystringTwo-letter country, default US.

Example request

curl https://app.your-white-label.com/api/agency/v1/sms-providers/12/numbers \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Example response 200 OK

{
  "data": {
    "owned": [
      {
        "sid": "PN...",
        "phone_number": "+18885550123",
        "friendly_name": "(888) 555-0123",
        "is_toll_free": true,
        "can_send_sms": true,
        "can_send_mms": true,
        "verification_status": "TWILIO_APPROVED"
      }
    ]
  }
}
POST/api/agency/v1/sms-providers/{id}/signalhouse/registration

Register SignalHouse for 10DLC

The dashboard's SignalHouse setup, step by step. Submit the business details and a number from the numbers endpoint; provisioning then runs by itself (brand, campaign, number) and the provider's status follows it until carriers approve the campaign. SignalHouse charges the brand registration and the number to your own SignalHouse account.

Body

ParameterTypeDescription
company_name, display_name, einstringThe business being registered.
entity_typestringPRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT or GOVERNMENT.
verticalstringThe industry, e.g. PROFESSIONAL, HEALTHCARE or RETAIL.
phone, email, websitestringThe business's contact details.
street, city, state, postal_code, countrystringThe business address.
usecasestringCUSTOMER_CARE, MARKETING, MIXED, ACCOUNT_NOTIFICATION or LOW_VOLUME.
sample_messagestringA message the campaign will send. A review-request sample is used when left out.
phone_numberstringThe number to register, from the numbers endpoint.
area_codestringDefaults to the business phone's area code.

Example request

curl -X POST https://app.your-white-label.com/api/agency/v1/sms-providers/14/signalhouse/registration \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "company_name": "Acme Dental LLC", "ein": "12-3456789", "entity_type": "PRIVATE_PROFIT", "vertical": "HEALTHCARE", "...": "...", "phone_number": "+16145550123" }'

Example response 202 Accepted

{
  "data": { "id": 14, "transport": "signalhouse", "status": "provisioning", "status_message": "...", "...": "..." }
}

Notes

  • POST .../signalhouse/appeal with a reason (10-2,048 characters) appeals a rejected campaign.
  • POST .../signalhouse/retry retries the step that failed, once its cause is fixed.
  • PUT .../signalhouse/number with phone_number (and area_code) uses another number, before the campaign has one.
  • POST .../signalhouse/restart with confirm: true forgets the registration so corrected details can be submitted. After a rejected brand, resubmitting costs a new brand fee.
PUT/api/agency/v1/sms-providers/{id}/organizations/{organization_id}

Assign an SMS provider to an organisation

Choose which provider sends an organisation's texts, and optionally give the organisation its own sender in place of the provider's. A message goes through the customer's own provider when they connected one, otherwise through the provider assigned to their organisation, otherwise through the agency's default.

Body

ParameterTypeDescription
sender.phonestringFor providers whose sender_capability is phone or both.
sender.phone_countrystringTwo-letter country of a national-format phone.
sender.sender_namestring3-11 letters, numbers and spaces, for alpha or both.
sender.short_codestringKudosity only: a 3-8 digit short code.

Example request

curl -X PUT https://app.your-white-label.com/api/agency/v1/sms-providers/12/organizations/88 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "sender": { "phone": "+14155550199" } }'

Example response 200 OK

{
  "data": {
    "id": 88,
    "name": "Acme Dental",
    "owner": { "id": 25, "name": "Jane Doe" },
    "sms_provider_id": 12,
    "sender": { "phone": "+14155550199", "phone_country": "US", "sender_name": null }
  },
  "previous_provider_id": null,
  "warnings": []
}

Notes

  • GET /api/agency/v1/sms-providers/{id}/organizations lists the organisations a provider sends for (search, per_page, page).
  • DELETE .../organizations/{organization_id} removes the organisation and its sender; its texts then use the default provider.
  • POST .../organizations/{organization_id}/test sends a test with the organisation's sender, as its real messages would.
  • Only a ready provider can be assigned. A SignalHouse provider, and a Twilio provider that sends through a Messaging Service, choose the sending number themselves, so a sender given for one is saved but not used (warning override_ignored). To give an organisation its own number with them, give it its own provider.
PUT/api/agency/v1/sms-settings

Text added to every campaign SMS

The text added after the review link in every SMS your campaigns send, such as an opt-out line. Up to 500 characters; {{ organization }} is replaced with the organisation's name when the SMS is sent, and null or an empty string removes it. GET /api/agency/v1/sms-settings returns the current text.

Body

ParameterTypeDescription
append_textstring | nullThe text, or null for none (required).

Example request

curl -X PUT https://app.your-white-label.com/api/agency/v1/sms-settings \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "append_text": "Reply STOP to opt out" }'

Example response 200 OK

{
  "data": { "append_text": "Reply STOP to opt out" }
}

Webhooks

Receive real-time HTTP notifications when events occur. Add your webhook URL on the Webhooks tab of the API & Webhooks page (the agency owner: Platform → AI & Automation → API & Webhooks; customers: Settings → API & Webhooks). To track a review request invite, use the Invite Status endpoint.

PropertyValue
HTTP MethodPOST
Content-Typeapplication/json
User-AgentReviewManagement/V1
Retry PolicyUp to 4 retries after a 5xx response, a timeout or a connection error, waiting 30 seconds, then 1, 2 and 5 minutes
Timeout15 seconds per attempt (5 seconds to connect)

Events

EventTriggered when
review-createdA new review is received from any connected source
review-updatedAn existing review is modified (reply added, rating changed)
review-removedA check finds a review is no longer on its review site (deleted by the reviewer or removed by Google), with when it was detected and when the review was last seen
review-restoredA removed review is back on its review site (Google reinstated it), with when it came back
private-feedback-createdA customer submits a private feedback form (low-rating, complaint, anything routed away from public reviews)
private-feedback-updatedAn existing private feedback record is changed (reply added, rating or message edited)
organization-createdA new organisation is created
organization-updatedAn organisation's details are modified
organization-deletedAn organisation is deleted
location-createdA new location is added
location-updatedA location's details are modified
location-deletedA location is removed
scan-completedA Local Search Grid scan finishes a full snapshot (agency-only)
scan-failedA Local Search Grid scan run errored out before completing (agency-only)

Example payload (review-created)

{
  "webhook_event": "review-created",
  "id": 142,
  "organization_id": 1,
  "location_id": 3,
  "source_name": "google",
  "identifier": "AbcXyz123",
  "avatar": "https://lh3.googleusercontent.com/a/photo.jpg",
  "author": "Sarah Johnson",
  "rating": 5,
  "original_rating": 5,
  "title": null,
  "message": "Outstanding service! The team went above and beyond.",
  "url": "https://maps.google.com/review/...",
  "verified": true,
  "replied": false,
  "reply_message": null,
  "reply_url": null,
  "hidden": false,
  "reply_published_on": null,
  "published_on": "2025-12-15T10:30:00+00:00",
  "review_updated_on": null,
  "updated_at": "2025-12-15T10:35:00+00:00",
  "created_at": "2025-12-15T10:35:00+00:00",
  "meta": {},
  "source_status": "live",
  "source_removed_at": null,
  "source_last_seen_at": null,
  "source_restored_at": null
}

Example payload (private-feedback-created)

Fired when a customer submits a private feedback form. An update (typically a team member's reply) fires private-feedback-updated with the same fields. The meta object mirrors the raw form submission, so keys vary per form. Read the top-level fields for stable values.

{
  "webhook_event": "private-feedback-created",
  "id": 87,
  "organization_id": 1,
  "location_id": 3,
  "rating": 2,
  "author": "Alex Morgan",
  "email": "[email protected]",
  "phone": "+15551234567",
  "message": "The waiting time was longer than expected and I'd appreciate a call back.",
  "replied": false,
  "reply_message": null,
  "reply_published_on": null,
  "source": "email",
  "source_name": "[email protected]",
  "updated_at": "2025-12-15T10:30:00+00:00",
  "created_at": "2025-12-15T10:30:00+00:00",
  "meta": {
    "name": "Alex Morgan",
    "email": "[email protected]",
    "phone": "+15551234567",
    "message": "The waiting time was longer than expected and I'd appreciate a call back.",
    "rating": 2,
    "source": "email",
    "source_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "source_name": "[email protected]"
  }
}

Example payload (scan-completed)

Fired once a Local Search Grid snapshot finishes. Available to tenant-owner webhook configurations only.

{
  "webhook_event": "scan-completed",
  "uuid": "4f3a3b6c-...",
  "status": "completed",
  "snapshot_at": "2026-05-12T10:30:00+00:00",
  "location": "Acme Dental, Downtown",
  "keyword": "dentist near me",
  "keywords": ["dentist near me", "emergency dentist"],
  "grid_size": 7,
  "summary": {
    "average_rank": 5.2,
    "top_3_count": 12,
    "top_4_to_10_count": 23,
    "not_ranking_count": 14
  },
  "report_url": "/scans/4f3a3b6c-.../report"
}

Example payload (scan-failed)

Fired when a snapshot errors out before completing. The error_message is short and safe to display to your team.

{
  "webhook_event": "scan-failed",
  "uuid": "4f3a3b6c-...",
  "status": "failed",
  "error_message": "DataForSEO API key is missing",
  "failed_at": "2026-05-12T10:31:00+00:00"
}
Model Context Protocol

AI Hub (MCP Server)

The AI Hub exposes review data, Google Business Profile metrics and posts, and Local Search Grid scans as Model Context Protocol tools for AI clients such as ChatGPT, Claude, Claude Code and Cursor. This is a separate endpoint from the REST API above, uses a different authentication ability (mcp:access), accepts both AI Hub tokens and sign-in from ChatGPT, Claude and other MCP clients that support sign-in, and speaks JSON-RPC 2.0 instead of REST.

Use the REST API for structured automations and pipelines. Use the MCP endpoint for interactive AI work. Many customers run both.

Endpoint

https://app.your-white-label.com/api/mcp

Protocol

JSON-RPC 2.0

Spec version

2025-06-18

Rate limit

120/min token, 600/min workspace

Setup

There are two ways to connect, both to the same endpoint. ChatGPT, Claude and other MCP clients that support sign-in add https://app.your-white-label.com/api/mcp and sign in with a dashboard login, on a page on the same domain as that address. In ChatGPT on the web, open Plugins (Apps on some accounts), select the plus button, then Add custom MCP server, paste the address, choose OAuth, select Create as a plugin and install the plugin. ChatGPT's Free plan cannot add one, and in a ChatGPT workspace it works only where the workspace's permissions allow it. In Claude, open Customize → Connectors and add a custom connector; on Team and Enterprise plans an owner adds it under Organization settings → Connectors, then each member selects Connect in Customize → Connectors. ChatGPT connects only by signing in. Claude Desktop's config file, Claude Code, Cursor and your own scripts can use an AI Hub token instead.

The agency owner can always connect. Anyone else needs AI Hub included in the plan of the organisation they have open, and the API access permission in that organisation. Sales agents cannot connect as themselves.

For a token, create a connection in AI Hub (the agency owner: Resources → Developer → AI Hub, or the AI Hub tab under Platform → AI & Automation → API & Webhooks; team members and customers: Settings → AI Hub). Copy the config it shows (the token is shown once) and paste it into your MCP client. For Claude Desktop, add it to claude_desktop_config.json (on a Mac in ~/Library/Application Support/Claude, on Windows in %APPDATA%\Claude), then quit Claude Desktop completely and reopen it.

{
  "mcpServers": {
    "my-agency-reviews": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.your-white-label.com/api/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer your-mcp-token"
      }
    }
  }
}

mcp-remote is a small program that runs on your computer and passes Claude Desktop's requests to this endpoint. It is the token option for Claude Desktop's config file: the token sits in the AUTH_HEADER setting, which its --header line reads. It runs with npx, so that computer needs Node.js, a current LTS release. Claude Code and Cursor can connect to the address directly and send the token in an Authorization: Bearer header, so they do not need it.

Authentication

Every request carries a bearer token in the Authorization header. It is either an AI Hub token or an access token from sign-in.

MethodForWhere it comes from
Sign-in (OAuth 2.1)ChatGPT, Claude and other MCP clients that support sign-inThe client signs a person in on the same domain as the MCP address and receives an access token that lasts an hour
AI Hub tokenClaude Desktop's config file (through mcp-remote), Claude Code, Cursor, scripts and other clients that send a fixed bearer tokenCreate connection in AI Hub; the token is shown once

The token must carry the mcp:access ability. Write tools also require mcp:writes, and PII-sensitive calls also require reviews:pii.

The agency-only Local Search Grid tools also require local-search-grid:read, plus local-search-grid:run to create, run or schedule a scan. The Publishing tools require publishing:read, and the Publishing prepare tools also require mcp:writes and publishing:write. The agency-only SMS provider tools require sms-providers:read, and the ones that change anything or send a test also require mcp:writes and sms-providers:manage. The AI Hub screen adds these when you tick the matching boxes on a new connection, and the sign-in page offers the same boxes.

Authorization header

Authorization: Bearer your-mcp-token

Sign-in (OAuth 2.1)

Each sign-in connection is backed by an AI Hub token made from the choices on the sign-in page, so its access tokens reach what that token reaches, with the same abilities, customer limit and rate limits. Sign-in access tokens work only on /api/mcp; the REST API refuses them and takes API tokens. Each connection appears in AI Hub as "Signed in from …", for example "Signed in from ChatGPT" or "Signed in from Claude". An app that returns to an address on the person's own computer or device shows as "… (an app on a computer or device)" or "An app on a computer or device". The connection can be revoked in AI Hub while the person can open AI Hub, and Revoke ends it at once. Losing API access or AI Hub later does not end a connection.

  • Discovery: GET /.well-known/oauth-protected-resource/api/mcp (the same document is also served at /.well-known/oauth-protected-resource) names the resource and its authorization server. GET /.well-known/oauth-authorization-server lists the endpoints below.
  • Client registration: Dynamic Client Registration at POST /oauth/register, or a Client ID Metadata Document (an https client_id URL). Clients are public: token_endpoint_auth_method is none.
  • Authorization: GET /oauth/authorize with response_type code and PKCE, S256 only. The person signs in with their dashboard login on the same domain as the MCP address, sees which assistant is asking and where it returns, and chooses the connection's access. The response carries code, state and iss.
  • Token: POST /oauth/token with grant_type authorization_code or refresh_token. Access tokens last 1 hour (expires_in 3600). Refresh tokens rotate: every refresh returns a new refresh token.
  • Revocation: POST /oauth/revoke (RFC 7009). Revoking a refresh token ends the connection, as Revoke in AI Hub does. Revoking an access token ends that access token.
  • Scope and resource: Scope mcp, plus offline_access when the client asks for it (refresh tokens are always issued). The resource parameter (RFC 8707), when sent, must name https://app.your-white-label.com/api/mcp.

401 from /api/mcp, where sign-in is available

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://app.your-white-label.com/.well-known/oauth-protected-resource/api/mcp", scope="mcp"

Protected resource metadata

GET https://app.your-white-label.com/.well-known/oauth-protected-resource/api/mcp

{
  "resource": "https://app.your-white-label.com/api/mcp",
  "authorization_servers": ["https://app.your-white-label.com"],
  "scopes_supported": ["mcp"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Your Agency AI Hub"
}

Correlation IDs

Pass an X-Correlation-Id header (letters, digits and . _ - : only, up to 64 characters; other characters are removed) and the server will echo the cleaned value back on the response and record it on the call's audit log entry (the audit log does not record every call). Useful for grouping every tool call from one AI prompt. Optional. This header applies to the MCP endpoint only: REST API endpoints do not read, store, or return it.

POST/api/mcp method: initialize

initialize

Handshake with the server, negotiate the protocol version, and receive the server capabilities and branded server name.

While Publishing is on for your account, the result also carries an instructions string. It tells the assistant that, on a connection with the Publishing tools, no post is published until a person approves it in the dashboard or by email, that photos the tools add go to the media library, and that text in posts, reviews, facts, comments and photo descriptions is content to read, not instructions to follow.

Example request

curl -X POST https://app.your-white-label.com/api/mcp \
  -H "Authorization: Bearer your-mcp-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "Claude Desktop", "version": "1.0" }
    }
  }'

Example response 200 OK

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": {} },
    "serverInfo": {
      "name": "Your Agency MCP Server",
      "version": "1.0.0"
    }
  }
}
POST/api/mcp method: tools/list

tools/list

List the tools this token can invoke. The server filters the catalog by your token's abilities and permissions, so AI clients never see tools they cannot actually call.

The list you receive is filtered by the token's abilities. Only the agency owner's connections see the agency-only Local Search Grid, Sales Intelligence and SMS provider tools: customers' and team members' connections never do, even with write access enabled, and neither does an agency-owner connection limited to chosen customers. The Publishing tools appear only while Publishing is on for your account and the connection was created with Include Publishing; the prepare tools also need write access. The SMS provider tools appear only on an agency-owner connection created with Allow managing SMS providers; the ones that change anything also need write access. The tool catalog below lists every tool a connection can be given; each connection sees the ones it can call.

Publishing tools also return a title, an outputSchema and annotations (readOnlyHint, destructiveHint, openWorldHint, and idempotentHint on prepare tools). The SMS provider tools return a title and annotations. On sign-in connections the other tools also return a title and annotations, with readOnlyHint true on each read-only tool (ChatGPT treats a tool without readOnlyHint as a write, and by default asks for confirmation before running a write). On token connections those tools return name, description and input schema only.

Example request

curl -X POST https://app.your-white-label.com/api/mcp \
  -H "Authorization: Bearer your-mcp-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

Example response 200 OK

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "list_reviews",
        "description": "List and filter reviews across organizations and locations...",
        "inputSchema": { "type": "object", "properties": { ... } }
      },
      {
        "name": "get_metrics",
        "description": "Aggregate review metrics over a date range...",
        "inputSchema": { "type": "object", "properties": { ... } }
      },
      {
        "name": "list_publishing_locations",
        "title": "List publishing locations",
        "description": "List the locations you can publish posts for...",
        "inputSchema": { "type": "object", "properties": { ... } },
        "outputSchema": { "type": "object", "properties": { ... } },
        "annotations": { "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false }
      }
    ]
  }
}
POST/api/mcp method: tools/call

tools/call

Invoke one of the registered tools. The response contains both a text content block (for AI client display) and a structuredContent object with the parsed result.

Example request

curl -X POST https://app.your-white-label.com/api/mcp \
  -H "Authorization: Bearer your-mcp-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Correlation-Id: client-prompt-20260421-abc123" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_metrics",
      "arguments": {
        "date_from": "2026-03-22",
        "date_to": "2026-04-21",
        "group_by": "source"
      }
    }
  }'

Example response 200 OK

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "structuredContent": {
      "period": { "from": "2026-03-22", "to": "2026-04-21" },
      "filters": { "organization_id": null, "location_id": null, "source_name": null },
      "totals": {
        "total_reviews": 487,
        "avg_rating": 4.58,
        "responded": 412,
        "response_rate": 0.846,
        "star_distribution": { "5": 362, "4": 79, "3": 21, "2": 12, "1": 13 },
        "sentiment_distribution": { "positive": 441, "neutral": 21, "negative": 25 },
        "source_presence": { "removed_reviews": 3, "removals_detected": 2, "reinstated": 1 }
      },
      "breakdown": [
        { "bucket": "Google", "total_reviews": 318, "avg_rating": 4.61, "responded": 291, "response_rate": 0.915 },
        { "bucket": "Facebook", "total_reviews": 104, "avg_rating": 4.52, "responded": 78, "response_rate": 0.75 },
        { "bucket": "TripAdvisor", "total_reviews": 65, "avg_rating": 4.49, "responded": 43, "response_rate": 0.661 }
      ]
    },
    "content": [
      { "type": "text", "text": "{ \"period\": ..., \"totals\": ..., \"breakdown\": [...] }" }
    ]
  }
}

Tool catalog

Tools an AI connection can be offered, with the group each belongs to. Each connection gets only the tools its access allows. No review reply or post that these tools draft or edit is published until a person approves it; other write tools do not wait for approval. Pass the tool name to tools/call with the matching arguments. Required parameters are marked with an asterisk.

Read tools

(7 tools)
list_reviews Requires reviews.view

Filter and list reviews across organisations and locations the caller can access. Supports filtering by source, date, rating, sentiment, response status, verified flag, and full-text search. Results are paginated.

ParamTypeDescription
organization_idintegerLimit to one organisation
location_idintegerLimit to one location
source_namesarray<string>Review platforms, e.g. ["Google", "Facebook"]
date_fromdateInclusive start date (YYYY-MM-DD)
date_todateInclusive end date (YYYY-MM-DD)
ratingsarray<integer>Star ratings to include, 1-5
sentimentstring"positive", "negative", or "neutral"
respondedbooleanOnly reviews with or without a reply
verifiedbooleanOnly verified or unverified reviews
querystringFull-text search over author, message, and reply
min_message_lengthintegerOnly reviews whose message is longer than this many bytes, not characters: each character outside plain ASCII counts as 2 or more. A review with a playable video passes whatever its message
sort_bystringNewest First | Oldest First | Highest Rating First | Lowest Rating First
pageintegerPage number (default 1)
per_pageintegerRows per page (1-50, default 25)
get_review Requires reviews.view

Fetch a single review by ID with full detail including reply, tags, the most recently actioned auto-respond action (status, times and rule name), and language.

ParamTypeDescription
review_id*integerThe review ID to fetch
list_organizations Requires locations.view

List organisations the caller can access, with optional review-count and avg-rating enrichment. Pass organization_id for full detail including locations.

ParamTypeDescription
organization_idintegerReturn full detail for one org (pagination ignored)
include_statsbooleanAttach review count and avg rating. Default true
searchstringSubstring match on org name
pageintegerPage number (default 1)
per_pageintegerRows per page (1-50, default 25)
list_locations Requires locations.view

List locations accessible to the caller with per-location review count and average rating. Scope to a single organisation with organization_id.

ParamTypeDescription
organization_idintegerLimit to one organisation
pageintegerPage number (default 1)
per_pageintegerRows per page (1-50, default 25)
get_metrics Requires reviews.view

Aggregate review metrics over a date range: totals, avg rating, star distribution, response rate, sentiment breakdown. Optional group_by slices the data. Pass compare_to_date_from and compare_to_date_to for period-over-period deltas.

ParamTypeDescription
organization_idintegerLimit to one organisation
location_idintegerLimit to one location
source_namestringFilter by one source, e.g. "Google"
date_fromdateInclusive start date (YYYY-MM-DD)
date_todateInclusive end date (YYYY-MM-DD)
group_bystringday | week | month | location | organization | source | rating | sentiment
compare_to_date_fromdateBaseline period start
compare_to_date_todateBaseline period end
list_campaigns Requires campaigns.view

List review-request campaigns with paused state, schedule, location, contact list, and full funnel (invited, opened, clicked, reviewed, redirected, testimonials submitted, private feedback, unsubscribed, bounced) plus open, click, redirect, conversion, unsubscribe, and bounce rates.

ParamTypeDescription
campaign_idintegerReturn detailed metrics for one campaign
organization_idintegerLimit to one organisation
date_fromdateCampaign created on or after
date_todateCampaign created on or before
pageintegerPage number
per_pageintegerRows per page (1-50)
get_ai_insights Requires reviews.view

Retrieve pre-computed AI analysis (themes, sentiment shifts, recommendations) for an organisation or location. Returns the most recent completed insight, or a specific period when period_start and period_end are provided.

ParamTypeDescription
organization_id*integerTarget organisation
location_idintegerSpecific location (omit for org-wide insights only)
period_startdateStart of the insight period
period_enddateEnd of the insight period

Read tools with PII access

(3 tools)
list_private_feedback Requires reviews.view

List private feedback submissions (ratings and messages never published publicly). Name, email, and phone are redacted by default; pass include_pii=true to unlock them (requires reviews.pii on the token). With include_pii=true, feedback from organisations where the caller's role cannot view contacts is left out.

ParamTypeDescription
organization_idintegerLimit to one organisation
location_idintegerLimit to one location
date_fromdateSubmitted on or after
date_todateSubmitted on or before
ratingsarray<integer>Star ratings to include, 1-5
include_piibooleanUnlock name/email/phone (requires reviews.pii)
respondedbooleanOnly responded or unresponded
pageintegerPage number
per_pageintegerRows per page (1-50)
list_contacts Requires contacts.view

List review-request contacts with subscription state, latest status, and per-contact engagement counters (invites, opens, clicks, video plays, redirects, testimonials, private feedback, bounces, unsubscribes). Email, phone, and name redacted by default; pass include_pii=true to unlock (requires reviews.pii on the token).

ParamTypeDescription
organization_idintegerLimit to one organisation
contact_list_idintegerLimit to one contact list
subscribedbooleanOnly subscribed (true) or only unsubscribed (false)
date_fromdateCreated on or after
date_todateCreated on or before
include_piibooleanUnlock email/phone/name (requires reviews.pii)
pageintegerPage number
per_pageintegerRows per page (1-50)
get_contact_activity Requires contacts.view

The activity timeline for one contact, newest first: invites, opens, clicks, video plays, redirects, testimonials, private feedback, unsubscribes, bounces, and spam complaints, with the campaign, channel, step number, rating, message, and source attached. Returns the newest 25 events by default and at most 100, with no paging; the summary counts every event. Contact name/email/phone are redacted by default; pass include_pii=true to unlock (requires reviews.pii on the token).

ParamTypeDescription
contact_id*integerThe contact ID to load activity for
limitintegerMax events to return, newest first (1-100, default 25)
include_piibooleanUnlock the contact's name, email, and phone (requires reviews.pii)

Google Business Profile read tools

(2 tools)

Customer-accessible. Both also need the reviews:read token ability, which every AI Hub connection carries.

list_gbp_metrics Requires reviews.view

Pull aggregated Google Business Profile performance metrics for one location and a date range: impressions (search, maps, desktop, mobile), call clicks, website clicks, and direction requests. Includes the equal-length previous period so AI clients can compute trend deltas in one call. Customer-accessible.

ParamTypeDescription
location_id*integerInternal location ID
fromdateInclusive start date (YYYY-MM-DD). Defaults to 29 days before the to date (a 30-day window), or to 30 days ago when no to date is given.
todateInclusive end date (YYYY-MM-DD). Defaults to yesterday.
include_dailybooleanInclude the per-day rows. Default false.
list_gbp_search_terms Requires reviews.view

Pull the search query terms shoppers used to find a location, with their monthly impression counts. Below-threshold rows (Google masks low-volume terms) are returned with below_threshold=true so AI clients can surface them without leaving gaps. Customer-accessible.

ParamTypeDescription
location_id*integerInternal location ID
yearintegerDefaults to current year.
monthinteger1-12. Omit to return every month in the year.
per_pageintegerRows per page (1-50, default 25)
pageintegerPage number (default 1)

Sales Intelligence tools (agency only)

(2 tools)

Shown only to the agency owner's connections. Customer tokens and connections limited to chosen customers never see them. Both tools are read only.

list_sales_intelligence_leads Requires reviews.view

List Sales Intelligence prospect leads, newest first. By default only the self-serve leads captured by your public report form are returned; pass include_outbound to add leads found through outbound prospect search. Filter by date range, business name and pipeline status. Results are paginated.

ParamTypeDescription
searchstringMatch against business name
date_fromdateInclusive start date (YYYY-MM-DD)
date_todateInclusive end date (YYYY-MM-DD)
statusstringPipeline status, e.g. saved, contacted, qualified
include_outboundbooleanInclude leads found through outbound prospect search. Default false
pageintegerPage number (default 1)
per_pageintegerRows per page (1-50, default 25)
get_sales_intelligence_lead Requires reviews.view

Fetch one Sales Intelligence prospect lead by UUID: business profile, contact details, opportunity score, pipeline status, the self-serve submission context, and the URL of the latest report.

ParamTypeDescription
uuid*stringThe lead UUID returned by list_sales_intelligence_leads

Local Search Grid tools (agency only)

(8 tools)

Shown only to the agency owner's connections created with Include Local Search Grid access. The read tools need local-search-grid:read; create_scan, run_scan and schedule_scan also need mcp:writes and local-search-grid:run. Customer tokens and connections limited to chosen customers never see them.

list_scans Requires local_search_grid.view

Paginated metadata for all Local Search Grid scans the agency owns, newest first. Filter by schedule, completion state, recency, or free-text search. Hidden from customer tokens.

ParamTypeDescription
searchstringFree-text over location and keyword
is_scheduledbooleanOnly recurring scans
completedbooleantrue: scans whose latest run has ended, whether or not it ended in failure (add failed=false to leave out runs that ended in failure). false: every other scan, such as one whose run is in progress. Starting a new run clears completed_at, so a scan with earlier snapshots counts as false while that run is in progress
failedbooleanOnly scans whose last run failed
since_daysintegerScans created in the last N days (1-365)
pageintegerPage number
per_pageinteger1-50, default 20
get_scan Requires local_search_grid.view

Return one scan with its per-pin results for the requested snapshot. Defaults to the most recent snapshot. top_n (0-20, default 5) caps the SERP list per pin so the response stays bounded on large grids. Use get_scan_data_points for paginated per-pin access.

ParamTypeDescription
uuid*stringScan UUID
snapshot_atdatetimeISO-8601 timestamp; defaults to the latest snapshot
top_nintegerSERP entries per pin (0-20). Default 5. Pass 20 for the full SERP list per pin.
get_scan_data_points Requires local_search_grid.view

Paginated per-pin data for one snapshot. Returns lat, lng, target_rank, and the top-N competitors (place_id, name, rank) at each pin. The right tool for rank-tracker integrations on large grids; pairs with the data_points REST endpoint.

ParamTypeDescription
uuid*stringScan UUID
snapshot_atdatetimeISO-8601 timestamp; defaults to the latest snapshot for the (scan, keyword) combo
keywordstringRestrict to one keyword on multi-keyword scans
top_nintegerCompetitors per pin (0-20). Default 5. Pass 0 for just lat/lng/target_rank.
pageinteger1-based page
per_pageinteger1-50, default 50
list_scan_snapshots Requires local_search_grid.view

Aggregated rank distribution and visibility score for every snapshot the scan has produced. One row per snapshot. Use this to plot a multi-month trend without paging through every pin.

ParamTypeDescription
uuid*stringScan UUID
keywordstringRestrict the aggregate to one keyword on a multi-keyword scan
get_scan_insights Requires local_search_grid.view

Everything the in-app report computes for one snapshot: summary stats, long-range trends, snapshot-over-snapshot deltas, geographic quadrant strength, top competitors, and rule-based recommendations.

ParamTypeDescription
uuid*stringScan UUID
keywordstringRestrict to one keyword on multi-keyword scans
snapshot_atdatetimeISO-8601 timestamp; defaults to the latest snapshot
create_scan Requires local_search_grid.runAlso requires mcp:writes

Create a brand-new scan, generate the hex-ring pin grid server-side, and queue the first snapshot. Returns immediately; subscribe to scan-completed for the result.

ParamTypeDescription
location*stringHuman-readable name for the dashboard
keywords*array<string>1-20 keyword strings
grid_size*integerOne of 3, 5, 7, 9, 11, 13, 15
distance*numberDistance from center to outer ring (> 0, ≤ 50)
distance_unit*string"km" or "miles"
addressstringGeocoded via Google Maps if lat/lng not supplied
latnumberPin grid center latitude
lngnumberPin grid center longitude
target_place_idstringGoogle Place ID for self-vs-competitor scoring
typestring"business" (default) or "sab"
run_scan Requires local_search_grid.runAlso requires mcp:writes

Snap a new snapshot using the scan's saved grid, keywords, and distance. Returns immediately with status "queued" and fires scan-completed (or scan-failed) when finished. While the scan is already running it queues nothing and returns status "already_running".

ParamTypeDescription
uuid*stringScan UUID
schedule_scan Requires local_search_grid.runAlso requires mcp:writes

Enable or disable a recurring schedule on an existing scan. The cron worker picks up scheduled scans every 15 minutes and triggers a new snapshot whenever the next_run_at falls in the configured day-of-week and time-of-day window. Catches ranking shifts that only happen during business hours.

ParamTypeDescription
uuid*stringScan UUID
is_scheduled*booleantrue turns the schedule on, false disables it
frequencystring"weekly", "bi-weekly", or "monthly"
scheduled_fromstring24-hour HH:MM start
scheduled_tostring24-hour HH:MM end (must be later than scheduled_from)
scheduled_daysarray<integer>Day numbers (0 = Sunday, 6 = Saturday)
timezonestringPHP DateTimeZone identifier, e.g. "America/New_York"

Write tools (review replies held for approval)

(2 tools)
draft_review_response Requires reviews.respondAlso requires mcp:writes

Draft a response to a review. The draft is never sent until a person approves it, in the dashboard or from the approval email of its Auto-Respond rule when the rule has one. Requires write access (mcp:writes) on the token.

ParamTypeDescription
review_id*integerThe review to respond to
message*stringThe drafted reply (max 8000 chars). It is never sent until a person approves it.
tag_reviews Requires reviews.editAlso requires mcp:writes

Attach or detach tags on a set of reviews. Tag changes apply at once, with no approval step. Useful for clustering reviews by theme after summarisation. Caps at 50 reviews per call. Requires write access (mcp:writes).

ParamTypeDescription
review_ids*array<integer>Up to 50 review IDs
attach_tagsarray<string>Tags to attach (max 64 chars each). "Flagged" (in any letter case) is reserved and cannot be attached or removed with this tool
detach_tagsarray<string>Tags to remove. "Flagged" (in any letter case) cannot be removed with this tool

Publishing read tools

(7 tools)

Google Business Profile posts, photos and publishing settings. Listed only while Publishing is on for your account and the connection was created with Include Publishing, which adds publishing:read. A connection never gets more Publishing access than its user holds. Refusals come back as a tool result with isError true and a JSON text block of code, message and fix.

list_publishing_locations Requires publishing.view

List the locations this connection can publish posts for. Each row says whether a connected business profile is ready, whether publishing is on and healthy (with the reason and the fix when it is not), the Autopilot state, the approval rule, whether an approver is set, and this month's usage and what is left. Call it first to find the location_id values the other Publishing tools take. Read only. Needs publishing:read.

ParamTypeDescription
organization_idintegerOnly the locations of this client organisation
location_idsarray<integer>Only these locations (1-100 ids)
filterstringall (default) | ready_not_enabled | enabled | needs_attention | autopilot_active. ready_not_enabled: a profile is ready but publishing is off
pageintegerPage number (default 1)
per_pageintegerRows per page (1-50, default 20)
get_publishing_settings Requires publishing.view

Read one section of a location's publishing settings: facts, instructions, autopilot, schedule or photos. Each value says where it comes from (this location, the agency, or the default) and whether it is locked. Also returns the timezone, the posting window, any open proposals, and the settings version that update_publishing_settings needs. The photos section is Photo Location: whether photos are geotagged and the place used (its words, coordinates and source), or the reason there is none. Read only. Needs publishing:read.

ParamTypeDescription
location_id*integerThe location, from list_publishing_locations
section*stringfacts | instructions | autopilot | schedule | photos
pageintegerThe page of facts, 25 a page (default 1). Facts section only
get_post_requirements Requires publishing.view

Get what a post of a given kind needs at a location: formats, text and title limits, buttons, photo rules, what the profile removes, and how links are handled. Call it before writing a post. Read only. Needs publishing:read.

ParamTypeDescription
location_id*integerThe location, from list_publishing_locations
kind*stringupdate (a news post) | offer (a deal with dates) | event (something on a date)
media_countintegerHow many photos the post will carry, 0-10 (default 0). Some formats change with it
list_posts Requires publishing.view

List posts as short rows, filtered by location, status, kind, where the post began, local dates, waiting for approval, who drafted it, or needing attention. Use get_post for one post in full. Read only. Needs publishing:read.

ParamTypeDescription
organization_idintegerOnly the posts of this client organisation
location_idintegerOnly the posts of this location
statusarray<string>One or more of generating, draft, awaiting_approval, changes_requested, scheduled, published, partially_published, attention, failed, cancelled, expired
kindstringupdate | offer | event
sourcestringWhere the post began: manual | autopilot | review | mcp | api
date_fromdateLocal date (YYYY-MM-DD)
date_todateLocal date (YYYY-MM-DD)
waiting_for_approvalbooleanOnly posts waiting for an approver (true), or none of them (false)
drafted_bystringWho wrote the current version: assistant | person | autopilot
needs_attentionbooleanOnly posts that failed, expired or need a look (true), or none of them (false)
sortstringscheduled_asc (default) | scheduled_desc | updated_desc
pageintegerPage number (default 1)
per_pageintegerRows per page (1-50, default 20)
get_post Requires publishing.view

Get one post: its content, photos, each delivery with its status, failure and fix, the approval state, checks, the actions available now, the revision that update_post and cancel_post take, and a dashboard link. History is returned a page at a time when asked for. Read only. Needs publishing:read.

ParamTypeDescription
post_id*string (uuid)The post, from list_posts or from the tool that made it
sectionsarray<string>content | media | deliveries | approval | checks | history. Default: everything but history
history_pageintegerThe page of history, 20 items a page, newest first (default 1). Ask for the history section too
list_media_assets Requires publishing.view

List photos in the media library, filtered by location, ids, status, type, folder, Autopilot pool, unused, missing a description, or geotag. Each photo says whether it is geotagged, with the place used or the reason there is none. Use media_asset_ids to check on photos added with add_media_from_url. Read only. Needs publishing:read.

ParamTypeDescription
organization_idintegerOnly the photos of this client organisation
location_idintegerOnly the photos this location can use, its client's shared photos included
media_asset_idsarray<string>Only these photos (1-50 uuids)
statusstringprocessing | ready | failed
typestringimage | video
folder_idstring (uuid)Only the photos in this folder
poolstringOnly the photos in this Autopilot list, for example posts (max 24 chars)
unusedbooleanOnly photos no post carries, whatever its status (true), like the Media page's Not in Any Post filter; or only photos a post carries (false). Deleted posts do not count
missing_descriptionbooleanOnly photos with no description (true), or only described ones (false)
geotagstringon (geotagged) | off_for_photo (left out on the photo) | off_for_location (the location's setting is off) | unavailable (no place to use; the reason says why) | not_applicable (videos, failed photos, AI images). Name a location to judge the client's shared photos for it
pageintegerPage number (default 1)
per_pageintegerRows per page (1-50, default 20)
get_publishing_activity Requires publishing.view

Summarise publishing over a period for one location, one client organisation or everything the connection can reach: published, waiting, scheduled, failed by cause, Autopilot runs and usage. Months are calendar months in each location's timezone. Read only. Needs publishing:read.

ParamTypeDescription
organization_idintegerOnly this client organisation
location_idintegerOnly this location
periodstringthis_month (default) | last_month | last_7_days | last_30_days | custom. custom needs date_from and date_to
date_fromdateStart date for a custom period (YYYY-MM-DD)
date_todateEnd date for a custom period (YYYY-MM-DD)

Publishing prepare tools (a person approves every post)

(11 tools)

No tool calls Google itself: they change records in your account, and turning on a channel queues the one listing read that connecting needs. An assistant never approves or publishes a post: every post it drafts or edits waits for a person to approve that exact version, in the dashboard or from the approval email link, with no login. An assistant can set or move a post's time; an approved post keeps its approval. Each needs mcp:writes, publishing:read and publishing:write on the token, and the user's own Publishing permission at the location. Every one accepts dry_run, which checks the call and changes nothing. Times are local to the location and must be at least one hour ahead.

enable_publishing_channel Requires publishing.manageAlso requires mcp:writes

Turn publishing on for up to 50 locations that have a connected business profile ready to publish. Returns one row per location with the result; most are queued and finish within a minute, so check with list_publishing_locations. Nothing is posted. Needs publishing:write.

ParamTypeDescription
location_ids*array<integer>The locations to turn publishing on for, from list_publishing_locations (1-50, no repeats)
dry_runbooleanCheck the call and describe what would happen, without changing anything. Default false
update_publishing_settings Requires publishing.manageAlso requires mcp:writes

Change a location's publishing facts, instructions, schedule, timezone, Autopilot settings or photo location where they are not locked. Send timezone and languages each in a call of their own. New facts arrive unconfirmed until a person confirms them. It cannot change the approval rule, approvers, notice addresses or consent: a person changes approvers and notice addresses in the dashboard, and every post needs a person's approval. Needs publishing:write.

ParamTypeDescription
location_id*integerThe location, from list_publishing_locations
section*stringfacts | instructions | schedule | autopilot | photos
expected_version*integersettings_version from get_publishing_settings
changes*objectAt least one key. facts: add, update (up to 100 each, with type, fields and optional evidence; update also takes the fact id). instructions: text (max 5000), controls. schedule: timezone (IANA zone), default_post_time (HH:MM), posting_window (days, from, to), cadence (weekly | fortnightly | monthly), approval_lead_days (1-14), languages (1-5). autopilot: content_mix (angles), image_mode (library | none), streams. photos: photo_geotag (true | false | null to follow the agency's default), photo_place ({town} by name, add the region for a shared name such as "Newport, Wales", or {geonameid}; null goes back to the automatic place)
dry_runbooleanCheck the call and describe what would happen, without changing anything. Default false
set_autopilot_status Requires publishing.manageAlso requires mcp:writes

Pause Autopilot at a location, or start it where a person approves every post. Autopilot writes drafts on a schedule and each one waits for a person's approval; this tool approves nothing. Needs publishing:write.

ParamTypeDescription
location_id*integerThe location, from list_publishing_locations
status*stringpaused stops new drafts | active starts or resumes them
dry_runbooleanCheck the call and describe what would happen, without changing anything. Default false
draft_post Requires publishing.createAlso requires mcp:writes

Save a post draft from the assistant's own text. It never publishes: a person must approve it. Use request_post_approval to send it to the approvers. Needs publishing:write. Accepts idempotency_key, so a retried call never makes a second post.

ParamTypeDescription
location_id*integerThe location, from list_publishing_locations
kind*stringupdate | offer | event
body*stringThe post text (1-5000 chars)
titlestringThe title of an offer or event (max 255 chars)
detailsobjectOffer or event details: starts_at, ends_at (local YYYY-MM-DD or YYYY-MM-DDTHH:MM, no zone), coupon_code (max 60), redeem_url (https), terms (max 5000)
link_urlstringAn https link for the button (max 2048 chars)
ctastringlearn_more | book | order | shop | sign_up | call
media_asset_idsarray<string>Photos from list_media_assets, in the order they show (up to 10 uuids, no repeats)
scheduled_forstringLocal time at the location, like 2026-10-05T09:30
languagestringA language code (max 12 chars); empty uses the location's primary post language
idempotency_keystringYour own key for this request (1-64 chars: letters, digits, dot, underscore, colon, hyphen). Repeating the call with the same key and arguments returns the first result
dry_runbooleanCheck the call and describe what would happen, without changing anything. Default false
generate_post Requires publishing.createAlso requires mcp:writes

Ask the account's AI writer for a post draft, with an optional topic. Returns at once with the post in Writing; call get_post until it is a draft. Counts toward the location's monthly AI limit, and is limited to 10 calls a minute per connection. It never publishes. Needs publishing:write. With dry_run it returns the plan without writing.

ParamTypeDescription
location_id*integerThe location, from list_publishing_locations
kind*stringupdate | offer | event
topicstringWhat this one post should be about (max 500 chars)
servicestringA service fact id from get_publishing_settings (max 64 chars)
scheduled_forstringLocal time at the location, like 2026-10-05T09:30
idempotency_keystringYour own key for this request (1-64 chars). Repeating the call with the same key and arguments returns the first result
dry_runbooleanReturn the plan without writing. Default false
update_post Requires publishing.createAlso requires mcp:writes

Edit a draft, a post waiting for approval or with changes requested, a scheduled post, or an expired one. Editing a scheduled post moves it back to waiting for a person's approval; any other post keeps its status (a draft stays a draft). Needs expected_revision from get_post, and publishing:write.

ParamTypeDescription
post_id*string (uuid)The post, from list_posts or get_post
expected_revision*integerThe revision from get_post
titlestring | nullThe title of an offer or event (max 255 chars)
bodystringThe post text (1-5000 chars)
detailsobject | nullOffer or event details, the same keys as draft_post. Local times, no zone
link_urlstring | nullAn https link for the button (max 2048 chars)
ctastring | nulllearn_more | book | order | shop | sign_up | call
media_asset_idsarray<string>The photos in the order they show (up to 10 uuids); an empty list removes them
dry_runbooleanCheck the call and describe what would happen, without changing anything. Default false
request_post_approval Requires publishing.createAlso requires mcp:writes

Send up to 20 posts to their location's approvers by email. This is how a post an assistant prepared moves toward publishing: a person approves it from the email or the dashboard. Refused when a location has no approver. Needs publishing:write.

ParamTypeDescription
post_ids*array<string>The posts to send (1-20 uuids, no repeats)
notestringA short note for the approvers (max 500 chars)
dry_runbooleanCheck the call and describe what would happen, without changing anything. Default false
reschedule_post Requires publishing.createAlso requires mcp:writes

Change when a post goes out. Times are local to the location and cannot be within the next hour. An approved post stays approved; the tool approves and publishes nothing. Needs publishing:write.

ParamTypeDescription
post_id*string (uuid)The post, from list_posts or get_post
scheduled_for*stringLocal time at the location, like 2026-10-05T09:30
dry_runbooleanCheck the call and describe what would happen, without changing anything. Default false
cancel_post Requires publishing.createAlso requires mcp:writes

Cancel a post before it publishes. A post that is publishing or already published cannot be cancelled here; a person removes it in the dashboard. Needs publishing:write.

ParamTypeDescription
post_id*string (uuid)The post, from list_posts or get_post
expected_revisionintegerThe revision from get_post; when given, a newer revision refuses the call
dry_runbooleanCheck the call and describe what would happen, without changing anything. Default false
add_media_from_url Requires publishing.mediaAlso requires mcp:writes

Add a photo to a location's media library from a public HTTPS link, with a description of what it shows. With organization_wide it is filed for every location of that client. Returns at once with the photo processing and whether it will be geotagged at that location; check it with list_media_assets. Needs publishing:write. Accepts idempotency_key, so a retried call never adds a second photo.

ParamTypeDescription
location_id*integerThe location, from list_publishing_locations
organization_widebooleanFile the photo for every location of this client. Default false
url*stringA public https link to the photo (max 2048 chars)
description*stringWhat the photo shows (1-1000 chars)
alt_textstringAlt text (max 500 chars)
titlestringTitle (max 255 chars)
folder_idstring (uuid)A folder in the media library
poolsarray<string>Autopilot lists to put the photo in (up to 10, each max 24 chars)
geotagbooleanTag this photo with the business's town, name and services when it goes out with a post. Default true; false leaves this photo out
idempotency_keystringYour own key for this request (1-64 chars). Repeating the call with the same key and arguments returns the first result
dry_runbooleanCheck the call and describe what would happen, without changing anything. Default false
update_media_asset Requires publishing.mediaAlso requires mcp:writes

Change a photo's title, description, alt text, folder, Autopilot pools or geotag. Needs publishing:write.

ParamTypeDescription
media_asset_id*string (uuid)The photo, from list_media_assets
titlestring | nullTitle (max 255 chars)
descriptionstring | nullWhat the photo shows (max 1000 chars)
alt_textstring | nullAlt text (max 500 chars)
folder_idstring (uuid) | nullA folder id, or null for no folder
poolsarray<string> | nullThe Autopilot lists the photo is in (up to 10); null or an empty list takes it out of all of them
geotagbooleanTag this photo with the business's town, name and services when it goes out with a post (true), or leave it out (false). The change reaches every location the photo serves and every post still waiting to go out
dry_runbooleanCheck the call and describe what would happen, without changing anything. Default false

SMS provider tools (agency only)

(14 tools)

Shown only to the agency owner's connections created with Allow managing SMS providers. The read tools need sms-providers:read; the tools that change anything, and send_test_sms, also need mcp:writes and sms-providers:manage. Customer tokens and connections limited to chosen customers never see them. API keys given to these tools are saved encrypted and replaced with [redacted] in the audit log, and the tools never show them back in full: secret credentials are masked. Identifiers such as a Twilio Account SID are shown in full. A refused call comes back as a tool result with code, message and fix.

list_sms_providers Requires sms_providers.view

List the agency's SMS providers: type, whether it is the default, whether it is ready to send, its status, its sender, and how many organisations it sends for. Secret credentials are masked; identifiers such as a Twilio Account SID are shown in full. The text added to every campaign SMS is in meta.append_text.

ParamTypeDescription
searchstringFilter by provider name
pageintegerPage number
per_pageintegerRows per page
get_sms_provider Requires sms_providers.view

Get one SMS provider: its status and what it still needs (for example a Twilio number, a toll-free verification or a SignalHouse 10DLC registration step), its sender and its credentials, with secret ones masked.

ParamTypeDescription
provider_id*integerThe SMS provider id from list_sms_providers
list_sms_provider_types Requires sms_providers.view

List the SMS provider types that can be set up (SignalHouse, Twilio, Brevo, GatewayAPI, Bird, Kudosity, TextGrid, Telnyx, Clickatell, Amazon SNS, Vonage, Seven.io, httpSMS and the built-in testing service), with the exact credentials, sender and settings fields each one takes. Called before create_sms_provider.

ParamTypeDescription
transportstringOnly this type, e.g. "twilio"
list_sms_provider_organizations Requires sms_providers.view

List the organisations an SMS provider is assigned to, with the sender each one uses instead of the provider's own.

ParamTypeDescription
provider_id*integerThe SMS provider id
searchstringFilter by organisation name
pageintegerPage number
per_pageintegerRows per page
list_sms_provider_numbers Requires sms_providers.view

List the numbers a Twilio or SignalHouse provider can send from. Twilio: the account's own SMS-capable numbers, with toll-free verification status. SignalHouse: the account's own numbers and numbers available to register, by area code. Buying Twilio numbers is done in the dashboard.

ParamTypeDescription
provider_id*integerThe SMS provider id
area_codestringSignalHouse only: preferred area code, e.g. "614"
countrystringSignalHouse only: two-letter country, default US
create_sms_provider Requires sms_providers.manageAlso requires mcp:writes

Set up a new SMS provider with its credentials and sender. The connection is checked with the provider before anything is saved. Twilio needs a number already on the account; SignalHouse continues with manage_signalhouse_registration. The result shows the new provider with its secret credentials masked.

ParamTypeDescription
transport*stringThe provider type from list_sms_provider_types
namestringDisplay name; the type's name when left out
credentialsobjectWhat signs in to the provider, by the field names of its type, e.g. Twilio {"sid", "token"}
senderobjectWho messages come from: phone, phone_country, sender_name, short_code or channel_id, as the type takes
settingsobjectOther fields of the type, e.g. Amazon SNS {"region", "message_type"}
update_sms_provider Requires sms_providers.manageAlso requires mcp:writes

Change an SMS provider. Only what is sent changes: it is merged over the saved values and the connection is checked again; if the provider refuses, nothing changes. For Twilio, sender.phone finishes a setup that waits for a number.

ParamTypeDescription
provider_id*integerThe SMS provider id
namestringNew display name
credentialsobjectCredential fields to replace
senderobjectSender fields to replace
settingsobjectSetting fields to replace
delete_sms_provider Requires sms_providers.manageAlso requires mcp:writes

Delete an SMS provider. The organisations it was assigned to then send through the agency's default provider (or their customer's own). This cannot be undone.

ParamTypeDescription
provider_id*integerThe SMS provider id
confirm*booleanMust be true: the person asked for this provider to be deleted
set_default_sms_provider Requires sms_providers.manageAlso requires mcp:writes

Make a ready SMS provider the default. The default sends for every organisation that has no provider assigned and whose customer has not connected their own.

ParamTypeDescription
provider_id*integerThe SMS provider id
assign_sms_provider Requires sms_providers.manageAlso requires mcp:writes

Assign a ready SMS provider to an organisation, so its review requests by SMS go through that provider (unless its customer connected their own), optionally with the organisation's own sender. Replaces any provider the organisation had.

ParamTypeDescription
provider_id*integerThe SMS provider id
organization_id*integerThe organisation id from list_organizations
senderobjectThis organisation's own sender: phone (with phone_country), sender_name, or a Kudosity short_code. Left out, the provider's own sender is used
unassign_sms_provider Requires sms_providers.manageAlso requires mcp:writes

Remove an organisation from an SMS provider. Its own sender is cleared and its review requests by SMS then go through the agency's default provider (or its customer's own).

ParamTypeDescription
provider_id*integerThe SMS provider id
organization_id*integerAn organisation the provider is assigned to
manage_signalhouse_registration Requires sms_providers.manageAlso requires mcp:writes

Register a connected SignalHouse provider for US 10DLC texting, and recover a stopped registration. SignalHouse charges brand and number fees to the agency's own account. Provisioning then runs by itself; get_sms_provider shows its status.

ParamTypeDescription
provider_id*integerThe SMS provider id
action*string"register", "appeal", "retry", "change_number" or "restart"
detailsobjectFor "register": the business being registered and the sending number
phone_numberstringFor "change_number": the new sending number
area_codestringFor "change_number": preferred area code
reasonstringFor "appeal": why a rejected campaign should be reconsidered (10-2,048 characters)
confirmbooleanFor "restart": must be true; a rejected brand costs a new fee to register again
send_test_sms Requires sms_providers.manageAlso requires mcp:writes

Send one real test text through a ready SMS provider to a number the person gave, optionally as one of its organisations (with that organisation's sender). The provider charges for it. Numbers on a block list are refused; at most five tests a minute.

ParamTypeDescription
provider_id*integerThe SMS provider id
to*stringThe phone to text, international format (or national with phone_country)
phone_countrystringTwo-letter country of a national-format number
messagestringOptional text; a short test sentence otherwise
organization_idintegerSend as this organisation (it must be assigned to the provider)
update_sms_settings Requires sms_providers.manageAlso requires mcp:writes

Change the agency-wide text added after the review link in every campaign SMS, such as an opt-out line (up to 500 characters; {{ organization }} becomes the organisation's name; null or empty removes it).

ParamTypeDescription
append_text*string | nullThe text, or null for none

MCP error codes

MCP errors follow JSON-RPC 2.0. The server wraps all infrastructure errors (auth, rate limit, malformed JSON) in a JSON-RPC envelope instead of returning HTML, so AI clients can parse them cleanly.

Where sign-in is available on the domain, every 401 from /api/mcp also carries a WWW-Authenticate header with resource_metadata and scope="mcp", plus error="invalid_token" when a token was sent, so MCP clients can offer to sign in. The JSON-RPC error body does not change. The endpoint takes POST: with a valid token, GET and DELETE answer HTTP 405 with Allow: POST and a -32600 error.

The Publishing and SMS provider tools answer a refused call as a tool result instead: isError is true and the text block holds JSON with code, message and fix, plus fix_tool and fix_args when another call would help. An unknown tool name is still a JSON-RPC error.

CodeMeaningWhen
-32700Parse errorRequest body is not valid JSON
-32600Invalid requestMissing method, wrong jsonrpc version, or malformed envelope
-32601Method not foundUnknown method, or tools/call pointing at a tool that does not exist
-32602Invalid paramsValidation failed, unknown parameter, or missing required parameter
-32603Internal errorUnexpected server-side failure
-32001UnauthenticatedToken missing, invalid, or lacks mcp:access
-32001Missing permissionToken lacks the required ability (e.g. mcp:writes) or semantic permission
-32001Access deniedPassed an organization_id or location_id outside the caller's scope
-32001Subscription inactive or pausedThe subscription behind the call is not active or is paused. The HTTP status is 403 Forbidden
-32002Not foundTool resolved the request but no matching record exists
-32002Rate limit exceededPer-token or per-workspace rate limit hit; Retry-After header included

Example error response

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32001,
    "message": "Your token is missing the required permission: reviews.respond."
  }
}

Guide available

For the full walkthrough on signing in from ChatGPT and Claude, token creation, permissions, PII controls, write approvals, and the audit log, see AI Hub (MCP Server): Setup & Usage.

Still need a hand?

Tell us what you’re trying to do. We’ll help you find the next step.

Get support

Search the help center