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.
https://app.your-white-label.com/api/v1Authentication
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-tokenToken permissions
| Permission | Access |
|---|---|
| reviews:read | View reviews and review sources |
| reviews:create | Create reviews |
| reviews:update | Update reviews and publish review replies |
| reviews:delete | Delete reviews |
| request:read | View campaigns |
| request:create | Send review invites |
| organizations:read | View organisations and locations |
| organizations:create | Create organisations and locations |
| organizations:update | Update organisations and locations |
| organizations:delete | Delete organisations and locations |
Rate limiting
60 requests per minute per token. Every response includes rate limit headers.
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum requests per window (60) |
| X-RateLimit-Remaining | Remaining requests in current window |
| Retry-After | Seconds to wait before retrying (only on 429) |
Errors
Standard HTTP status codes. Errors return JSON with a message field.
| Code | Status | Description |
|---|---|---|
| 200 | OK | Request succeeded |
| 201 | Created | Resource successfully created |
| 202 | Accepted | Request accepted and queued |
| 401 | Unauthenticated | Missing or invalid API token |
| 402 | Upgrade Required | Plan limit or plan feature required (e.g. location limit, auto-respond) |
| 403 | Forbidden | Token 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. |
| 404 | Not Found | Resource does not exist |
| 409 | Conflict | Resource already in the requested state (e.g. review already replied) |
| 422 | Validation Error | Request body failed validation |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Server Error | Something went wrong on our end |
| 502 | Upstream Error | The 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."
]
}
}/api/v1/reviewsList reviews
Retrieve a paginated list of reviews across all connected sources. Filter by rating, organisation, location, or review source.
Requires reviews:read
Query parameters
| Parameter | Type | Description |
|---|---|---|
| rating | integer | Filter by rating (1-5) |
| organization_id | integer | Filter by organisation |
| location_id | integer | Filter by location |
| source_names[] | array | Filter by source names (e.g. Google, Facebook) |
| source_status | string | removed: 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) |
| page | integer | Page 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".
/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
}
}/api/v1/reviewsCreate 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
| Parameter | Type | Description |
|---|---|---|
| author | string | Reviewer name (required, max 255 chars) |
| rating | integer | Star rating 1-5 (required) |
| published_on | date | Publication date in Y-m-d format (required) |
| organization_id | integer | Organisation ID (required) |
| location_id | integer | Location ID, must belong to the organisation (required) |
| source | integer | Integration ID from the Writable Sources endpoint (required) |
| message | string | Review content |
| title | string | Review title (max 255 chars) |
| avatar | file | Reviewer 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.
/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
| Parameter | Type | Description |
|---|---|---|
| author | string | Reviewer name (max 255 chars) |
| rating | integer | Star rating 1-5 |
| message | string | Review content |
| title | string | Review title (max 255 chars) |
| published_on | date | Publication date in Y-m-d format |
| avatar | file | Reviewer 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.
/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.
/api/v1/reviews/sourcesWritable 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
| Parameter | Type | Description |
|---|---|---|
| organization_id | integer | Filter by organisation |
| location_id | integer | Filter by location |
| page | integer | Page 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": { ... }
}/api/v1/organizationsList 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": { ... }
}/api/v1/organizationsCreate 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
| Parameter | Type | Description |
|---|---|---|
| name | string | Organisation name (required, max 255 chars, unique) |
| logo | file | Logo 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"
}/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"
}/api/v1/organizations/{id}Update organisation
Update an existing organisation's name or logo.
Requires organizations:update
Request body
| Parameter | Type | Description |
|---|---|---|
| name | string | Organisation name (max 255 chars, unique) |
| logo | file | Logo 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"}'/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."
}/api/v1/locationsList 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
| Parameter | Type | Description |
|---|---|---|
| organization_id | integer | Limit to one organisation (optional) |
| search | string | Free-text search over location and organisation names (optional) |
| per_page | integer | Items 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.
/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.
/api/v1/locationsCreate location
Create a new location inside one of your organisations. Plan location limits apply, exactly as in the dashboard.
Requires organizations:create
Request body
| Parameter | Type | Description |
|---|---|---|
| organization_id | integer | The organisation the location will belong to (required) |
| name | string | Location 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.
/api/v1/locations/{id}Update location
Rename an existing location.
Requires organizations:update
Request body
| Parameter | Type | Description |
|---|---|---|
| name | string | Location 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"
}
}/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.
/api/v1/request-reviews/campaignsList campaigns
Retrieve your review request campaigns. Use campaign UUIDs to send invites via the Send Invite endpoint.
Requires request:read
Query parameters
| Parameter | Type | Description |
|---|---|---|
| organization_id | integer | Filter campaigns by organisation |
| search | string | Search 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": { ... }
}/api/v1/request-reviews/campaigns/{campaign}/inviteSend 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
| Parameter | Type | Description |
|---|---|---|
| campaign | uuid | Campaign UUID (required path parameter, from List Campaigns) |
| string | Contact email. Required when phone is not provided. | |
| phone | string | Phone in E.164 format (e.g. +14275238194). Required when email is not provided. |
| first_name | string | Contact first name (max 255 chars) |
| last_name | string | Contact last name (max 255 chars) |
| send_after_hours | integer | Hours 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
| Field | Type | Description |
|---|---|---|
| id | uuid | UUID 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. |
| status | string | "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". |
| reason | string | null | Why it was skipped: "suppressed", "unsubscribed", "not_subscribed" or "invalid_identifier". null when accepted. |
| message | string | "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).
/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
| Parameter | Type | Description |
|---|---|---|
| id | uuid | The 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
| Field | Type | Description |
|---|---|---|
| status | string | Where 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_at | datetime | null | When that status was reached. null for not_invited when your blocked list or an invalid address keeps the contact from being invited. |
| completed | object | null | When the status is completed: type (redirected, testimonial_submitted or private_feedback_given), the star rating picked and the review site (source). |
| subscription | string | subscribed, unconfirmed or unsubscribed. |
| invited_at | datetime | When the newest invite was received. |
| next_message | object | null | The 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_known | boolean | false 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. |
| stopped | object | null | Why 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. |
| messages | array | Every 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. |
| events | array | What 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_invites | integer | Invites 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.
/api/v1/sourcesList 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
}
]
}/api/v1/countriesList 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" },
...
]/api/v1/meCurrent 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]"
}/api/v1/gbp/metricsGoogle 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
| Parameter | Type | Description |
|---|---|---|
| location_id | integer | Internal location ID (required, from /api/v1/locations). |
| from | date | Inclusive 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. |
| to | date | Inclusive end date in Y-m-d format. Defaults to yesterday. |
| include_daily | boolean | Include 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.
/api/v1/gbp/search-termsGBP 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
| Parameter | Type | Description |
|---|---|---|
| location_id | integer | Internal location ID (required). |
| year | integer | Defaults to the current year. |
| month | integer | 1-12. Omit to return every month in the year. |
| per_page | integer | Default 50, max 200. |
| page | integer | 1-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/v1Agency tokens have full access across all customer accounts. There are no scoped permissions here, so the token acts as a super admin.
/api/agency/v1/customersCreate 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
| Parameter | Type | Description |
|---|---|---|
| name | string | Customer name (required) |
| company | string | Organisation/company name (required) |
| string | Login email address (required) | |
| password | string | Password, min 8 characters (required) |
| custom_plan_id | string | Plan ID to assign (required) |
| phone | string | Phone in E.164 format (optional) |
| location_limit | integer | Override plan location limit (optional; 0 = unlimited) |
| member_limit | integer | Override plan member limit. 0 = unlimited (optional) |
| send_invite | boolean | Email login details to the customer (optional) |
| send_google_connect_link | boolean | Email 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_link | boolean | Same as send_google_connect_link but for Facebook Pages. Independent of the Google flag: send one, the other, both, or neither (optional). |
| country | string | ISO 3166-1 alpha-2 code. Required if Stripe Tax is enabled. |
| postal_code | string | Required 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.
/api/agency/v1/customers/{customer}Switch customer plan
Change the customer's assigned plan.
Request body
| Parameter | Type | Description |
|---|---|---|
| custom_plan_id | string | The 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" }]
}
}/api/agency/v1/customers/{customer}/location-limitUpdate location & member limits
Override the customer's location or member limit independently of their plan defaults. Two separate endpoints.
Request body
| Parameter | Type | Description |
|---|---|---|
| location_limit | integer | PUT .../location-limit: number of locations allowed (0 = unlimited) |
| member_limit | integer | PUT .../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." }/api/agency/v1/customers/{customer}/add-creditsAdd credits
Add email or SMS credits to a customer's account. Credits can optionally expire.
Request body
| Parameter | Type | Description |
|---|---|---|
| type | string | Credit type: "email" or "sms" (required) |
| credits | integer | Number of credits to add, min 1 (required) |
| expires_at | date | Expiry date in Y-m-d format (optional) |
| notes | string | Note 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
}/api/agency/v1/customers/{customer}/pausePause & 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." }/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." }/api/agency/v1/customersList all customers
Retrieve a paginated list of all your customers with their plans and organisations.
Parameters
| Parameter | Type | Description |
|---|---|---|
| search | string | Search 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 }
}/api/agency/v1/custom-plansList 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"
}
]
}/api/agency/v1/ordersOrders (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/..."]
}
]
}
]
}/api/agency/v1/scansList 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
| Parameter | Type | Description |
|---|---|---|
| search | string | Free-text over location and keyword. |
| is_scheduled | boolean | Only recurring scans. |
| completed | boolean | true: 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. |
| failed | boolean | Only scans whose last run failed. |
| since_days | integer | Limit to scans created in the last N days (1-365). |
| per_page | integer | 1-100, default 20. |
| page | integer | 1-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.
/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
| Parameter | Type | Description |
|---|---|---|
| uuid | string | Scan UUID (required path parameter). |
| snapshot_at | datetime | ISO-8601 timestamp from available_snapshots. Defaults to the latest snapshot. |
| top_n | integer | SERP 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.
/api/agency/v1/scans/{uuid}/data_pointsLSG 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
| Parameter | Type | Description |
|---|---|---|
| uuid | string | Scan UUID (required path parameter). |
| snapshot_at | datetime | ISO-8601 timestamp. Defaults to the latest snapshot for the (scan, keyword) combo. |
| keyword | string | Restrict to one keyword on multi-keyword scans. |
| top_n | integer | Competitors per pin (0-20). Default 5. Pass 0 for just lat/lng/target_rank. |
| per_page | integer | 1-500. Default 100. |
| page | integer | 1-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.
/api/agency/v1/scans/{uuid}/snapshotsSnapshot 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
| Parameter | Type | Description |
|---|---|---|
| uuid | string | Scan UUID (required path parameter). |
| keyword | string | Restrict 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).
/api/agency/v1/scans/{uuid}/insightsDeep 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
| Parameter | Type | Description |
|---|---|---|
| uuid | string | Scan UUID (required path parameter). |
| keyword | string | Restrict to one keyword on multi-keyword scans. |
| snapshot_at | datetime | ISO-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.
/api/agency/v1/scansCreate 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
| Parameter | Type | Description |
|---|---|---|
| location | string | Human-readable name (required). Shows in the dashboard. |
| address | string | Used only if lat/lng are not supplied (server geocodes via Google Maps). |
| keywords | array<string> | 1-20 keyword strings (required). |
| grid_size | integer | One of 3, 5, 7, 9, 11, 13, 15 (required). |
| distance | number | Distance from the center to the outer ring, greater than 0, max 50 (required). |
| distance_unit | string | "km" or "miles" (required). |
| type | string | "business" (default) or "sab" for service-area businesses. |
| target_place_id | string | Google Place ID, used to score "self" pins in competitor analysis. |
| lat | number | Pin grid center latitude. |
| lng | number | Pin 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).
/api/agency/v1/scans/{uuid}/runRe-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.
/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
| Parameter | Type | Description |
|---|---|---|
| location | string | Display name shown in the dashboard. |
| address | string | Display-only. |
| keywords | array<string> | Full replacement set, 1-20 strings, each ≤ 100 chars. |
| target_place_id | string | Google Place ID. Used to score "self" in competitor analysis. |
| type | string | "business" or "sab". |
| grid_size | integer | Geometry. One of 3, 5, 7, 9, 11, 13, 15. |
| distance | number | Geometry. > 0 and ≤ 50. |
| distance_unit | string | Geometry. "km" or "miles". |
| lat | number | Geometry. New pin grid center latitude. |
| lng | number | Geometry. New pin grid center longitude. |
| regenerate_pins | boolean | Required 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.
/api/agency/v1/scans/{uuid}/archiveArchive 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.
/api/agency/v1/scans/{uuid}/scheduleSchedule 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
| Parameter | Type | Description |
|---|---|---|
| is_scheduled | boolean | true turns the schedule on, false disables it (required). |
| frequency | string | "weekly", "bi-weekly", or "monthly" (required when enabling). |
| scheduled_from | string | 24-hour HH:MM, e.g. "09:00" (required when enabling). |
| scheduled_to | string | 24-hour HH:MM, must be strictly later than scheduled_from. |
| scheduled_days | array<integer> | Day numbers (Carbon style: 0 = Sunday, 6 = Saturday). |
| timezone | string | PHP 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.
/api/agency/v1/connect-linksCreate customer connect link
Mint a single-use, location-scoped OAuth link. Hand the resulting connect_url to your customer over your own channel (your email template, in-app message, chat) and they sign in directly with Google or Facebook, with no platform login. Only one active link is allowed per (location, provider) at a time, so re-issuing for the same pair automatically revokes the prior one.
Request body
| Parameter | Type | Description |
|---|---|---|
| provider | string | "google" or "facebook" (required). |
| location_id | integer | EMR location the customer's integration will be attached to (required). List and create locations via /api/v1/locations. |
| ttl_days | integer | How long the link stays usable, 1 to 30 (optional, defaults to 7). |
Example request
curl -X POST https://app.your-white-label.com/api/agency/v1/connect-links \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"provider": "google",
"location_id": 42,
"ttl_days": 7
}'Example response 201 Created
{
"data": {
"token": "4f3a3b6c-1f8e-4c1f-9a2d-6e8b9c0f1234",
"provider": "google",
"location_id": 42,
"connect_url": "https://app.your-white-label.com/connect/4f3a3b6c-1f8e-4c1f-9a2d-6e8b9c0f1234",
"status": "active",
"expires_at": "2026-06-11T19:57:52+00:00",
"last_started_at": null,
"completed_oauth_at": null,
"used_at": null,
"revoked_at": null,
"created_at": "2026-06-04T19:57:52+00:00"
}
}Notes
- connect_url is the customer-facing landing page. Send it however you like: your own transactional email, SMS, chat tool, or copy-paste.
- Re-issuing for the same (location_id, provider) revokes the prior active token automatically. Issuing for a different provider on the same location leaves the other provider's link untouched.
- The status field rolls up the lifecycle timestamps into one of: active, used, expired, revoked. Use it instead of re-deriving from the underlying *_at columns.
- Returns 404 if location_id does not exist in your tenant database. Returns 403 if the API token does not belong to a tenant owner. Only your agency account can mint customer connect links.
/api/agency/v1/connect-linksList connect links
Paginated list of connect links, newest first. Filterable by location, provider, and a coarse status filter. Useful for building an audit view of which customers have outstanding (unfinished) links versus completed connections.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| location_id | integer | Limit to one location (optional). |
| provider | string | "google" or "facebook" (optional). |
| active | boolean | When true, returns only tokens that are still usable (not expired, not revoked, not used). Accepts "true"/"false"/"1"/"0". |
| per_page | integer | Items per page, 1 to 100. Defaults to 20. |
Example request
curl "https://app.your-white-label.com/api/agency/v1/connect-links?provider=google&active=true&per_page=10" \
-H "Authorization: Bearer {token}"Example response 200 OK
{
"data": [
{
"token": "4f3a3b6c-...",
"provider": "google",
"location_id": 42,
"connect_url": "https://app.your-white-label.com/connect/4f3a3b6c-...",
"status": "active",
"expires_at": "2026-06-11T19:57:52+00:00",
"last_started_at": null,
"completed_oauth_at": null,
"used_at": null,
"revoked_at": null,
"created_at": "2026-06-04T19:57:52+00:00"
}
],
"links": { "first": "...", "last": "...", "prev": null, "next": null },
"meta": { "current_page": 1, "from": 1, "last_page": 1, "per_page": 10, "to": 1, "total": 1 }
}/api/agency/v1/connect-links/{token}Get connect link
Look up a single connect link by its token UUID. Poll this endpoint to detect when a customer has finished the OAuth round-trip (completed_oauth_at populates) and when they have selected a Google location / Facebook page (used_at populates and status flips to "used").
URL parameters
| Parameter | Type | Description |
|---|---|---|
| token | string | The UUID token returned from the create endpoint (required). |
Example request
curl https://app.your-white-label.com/api/agency/v1/connect-links/4f3a3b6c-... \
-H "Authorization: Bearer {token}"Example response 200 OK
{
"data": {
"token": "4f3a3b6c-...",
"provider": "google",
"location_id": 42,
"connect_url": "https://app.your-white-label.com/connect/4f3a3b6c-...",
"status": "used",
"expires_at": "2026-06-11T19:57:52+00:00",
"last_started_at": "2026-06-04T20:02:11+00:00",
"completed_oauth_at": "2026-06-04T20:03:14+00:00",
"used_at": "2026-06-04T20:04:08+00:00",
"revoked_at": null,
"created_at": "2026-06-04T19:57:52+00:00"
}
}/api/agency/v1/connect-links/{token}Revoke connect link
Revoke a connect link so the customer can no longer use it. Idempotent: revoking an already-revoked or already-used token is a no-op and still returns 200. The response always includes the current resource state so you can confirm the status without a follow-up GET.
URL parameters
| Parameter | Type | Description |
|---|---|---|
| token | string | The UUID token to revoke (required). |
Example request
curl -X DELETE https://app.your-white-label.com/api/agency/v1/connect-links/4f3a3b6c-... \
-H "Authorization: Bearer {token}"Example response 200 OK
{
"data": {
"token": "4f3a3b6c-...",
"provider": "google",
"location_id": 42,
"connect_url": "https://app.your-white-label.com/connect/4f3a3b6c-...",
"status": "revoked",
"expires_at": "2026-06-11T19:57:52+00:00",
"last_started_at": null,
"completed_oauth_at": null,
"used_at": null,
"revoked_at": "2026-06-04T20:10:00+00:00",
"created_at": "2026-06-04T19:57:52+00:00"
}
}/api/agency/v1/sms-providers/typesSMS 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.
/api/agency/v1/sms-providersList 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
| Parameter | Type | Description |
|---|---|---|
| search | string | Matches the provider's name. |
| per_page | integer | 1-100, default 20. |
| page | integer | 1-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.
/api/agency/v1/sms-providersSet 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
| Parameter | Type | Description |
|---|---|---|
| transport | string | The provider type, from the types endpoint (required). |
| name | string | Display name. The type's name when left out. |
| credentials | object | What signs in to the provider, by the field names of its type. |
| sender | object | Who messages come from: a phone, a sender name or another sender field of its type. |
| settings | object | Other 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.
/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
| Parameter | Type | Description |
|---|---|---|
| name | string | New display name. |
| credentials | object | Credential fields to replace. |
| sender | object | Sender fields to replace. For Twilio, sender.phone finishes a setup that waits for a number. |
| settings | object | Setting 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.
/api/agency/v1/sms-providers/{id}/testSend a test SMS
Sends one real text through a ready provider. The provider charges for it as for any other message.
Body
| Parameter | Type | Description |
|---|---|---|
| phone | string | International format, or national with phone_country (required). |
| phone_country | string | Two-letter country code. |
| message | string | Up 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.
/api/agency/v1/sms-providers/{id}/numbersNumbers 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)
| Parameter | Type | Description |
|---|---|---|
| area_code | string | Preferred area code, e.g. 614. Other numbers are shown when none are left in it. |
| country | string | Two-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"
}
]
}
}/api/agency/v1/sms-providers/{id}/signalhouse/registrationRegister 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
| Parameter | Type | Description |
|---|---|---|
| company_name, display_name, ein | string | The business being registered. |
| entity_type | string | PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT or GOVERNMENT. |
| vertical | string | The industry, e.g. PROFESSIONAL, HEALTHCARE or RETAIL. |
| phone, email, website | string | The business's contact details. |
| street, city, state, postal_code, country | string | The business address. |
| usecase | string | CUSTOMER_CARE, MARKETING, MIXED, ACCOUNT_NOTIFICATION or LOW_VOLUME. |
| sample_message | string | A message the campaign will send. A review-request sample is used when left out. |
| phone_number | string | The number to register, from the numbers endpoint. |
| area_code | string | Defaults 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.
/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
| Parameter | Type | Description |
|---|---|---|
| sender.phone | string | For providers whose sender_capability is phone or both. |
| sender.phone_country | string | Two-letter country of a national-format phone. |
| sender.sender_name | string | 3-11 letters, numbers and spaces, for alpha or both. |
| sender.short_code | string | Kudosity 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.
/api/agency/v1/sms-settingsText 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
| Parameter | Type | Description |
|---|---|---|
| append_text | string | null | The 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.
| Property | Value |
|---|---|
| HTTP Method | POST |
| Content-Type | application/json |
| User-Agent | ReviewManagement/V1 |
| Retry Policy | Up to 4 retries after a 5xx response, a timeout or a connection error, waiting 30 seconds, then 1, 2 and 5 minutes |
| Timeout | 15 seconds per attempt (5 seconds to connect) |
Events
| Event | Triggered when |
|---|---|
| review-created | A new review is received from any connected source |
| review-updated | An existing review is modified (reply added, rating changed) |
| review-removed | A 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-restored | A removed review is back on its review site (Google reinstated it), with when it came back |
| private-feedback-created | A customer submits a private feedback form (low-rating, complaint, anything routed away from public reviews) |
| private-feedback-updated | An existing private feedback record is changed (reply added, rating or message edited) |
| organization-created | A new organisation is created |
| organization-updated | An organisation's details are modified |
| organization-deleted | An organisation is deleted |
| location-created | A new location is added |
| location-updated | A location's details are modified |
| location-deleted | A location is removed |
| scan-completed | A Local Search Grid scan finishes a full snapshot (agency-only) |
| scan-failed | A 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"
}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/mcpProtocol
JSON-RPC 2.0Spec version
2025-06-18Rate limit
120/min token, 600/min workspaceSetup
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.
| Method | For | Where it comes from |
|---|---|---|
| Sign-in (OAuth 2.1) | ChatGPT, Claude and other MCP clients that support sign-in | The client signs a person in on the same domain as the MCP address and receives an access token that lasts an hour |
| AI Hub token | Claude Desktop's config file (through mcp-remote), Claude Code, Cursor, scripts and other clients that send a fixed bearer token | Create 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-tokenSign-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.
/api/mcp method: initializeinitialize
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"
}
}
}/api/mcp method: tools/listtools/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 }
}
]
}
}/api/mcp method: tools/calltools/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.viewFilter 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.
| Param | Type | Description |
|---|---|---|
| organization_id | integer | Limit to one organisation |
| location_id | integer | Limit to one location |
| source_names | array<string> | Review platforms, e.g. ["Google", "Facebook"] |
| date_from | date | Inclusive start date (YYYY-MM-DD) |
| date_to | date | Inclusive end date (YYYY-MM-DD) |
| ratings | array<integer> | Star ratings to include, 1-5 |
| sentiment | string | "positive", "negative", or "neutral" |
| responded | boolean | Only reviews with or without a reply |
| verified | boolean | Only verified or unverified reviews |
| query | string | Full-text search over author, message, and reply |
| min_message_length | integer | Only 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_by | string | Newest First | Oldest First | Highest Rating First | Lowest Rating First |
| page | integer | Page number (default 1) |
| per_page | integer | Rows per page (1-50, default 25) |
get_review Requires reviews.viewFetch 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.
| Param | Type | Description |
|---|---|---|
| review_id* | integer | The review ID to fetch |
list_organizations Requires locations.viewList organisations the caller can access, with optional review-count and avg-rating enrichment. Pass organization_id for full detail including locations.
| Param | Type | Description |
|---|---|---|
| organization_id | integer | Return full detail for one org (pagination ignored) |
| include_stats | boolean | Attach review count and avg rating. Default true |
| search | string | Substring match on org name |
| page | integer | Page number (default 1) |
| per_page | integer | Rows per page (1-50, default 25) |
list_locations Requires locations.viewList locations accessible to the caller with per-location review count and average rating. Scope to a single organisation with organization_id.
| Param | Type | Description |
|---|---|---|
| organization_id | integer | Limit to one organisation |
| page | integer | Page number (default 1) |
| per_page | integer | Rows per page (1-50, default 25) |
get_metrics Requires reviews.viewAggregate 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.
| Param | Type | Description |
|---|---|---|
| organization_id | integer | Limit to one organisation |
| location_id | integer | Limit to one location |
| source_name | string | Filter by one source, e.g. "Google" |
| date_from | date | Inclusive start date (YYYY-MM-DD) |
| date_to | date | Inclusive end date (YYYY-MM-DD) |
| group_by | string | day | week | month | location | organization | source | rating | sentiment |
| compare_to_date_from | date | Baseline period start |
| compare_to_date_to | date | Baseline period end |
list_campaigns Requires campaigns.viewList 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.
| Param | Type | Description |
|---|---|---|
| campaign_id | integer | Return detailed metrics for one campaign |
| organization_id | integer | Limit to one organisation |
| date_from | date | Campaign created on or after |
| date_to | date | Campaign created on or before |
| page | integer | Page number |
| per_page | integer | Rows per page (1-50) |
get_ai_insights Requires reviews.viewRetrieve 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.
| Param | Type | Description |
|---|---|---|
| organization_id* | integer | Target organisation |
| location_id | integer | Specific location (omit for org-wide insights only) |
| period_start | date | Start of the insight period |
| period_end | date | End of the insight period |
Read tools with PII access
(3 tools)list_private_feedback Requires reviews.viewList 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.
| Param | Type | Description |
|---|---|---|
| organization_id | integer | Limit to one organisation |
| location_id | integer | Limit to one location |
| date_from | date | Submitted on or after |
| date_to | date | Submitted on or before |
| ratings | array<integer> | Star ratings to include, 1-5 |
| include_pii | boolean | Unlock name/email/phone (requires reviews.pii) |
| responded | boolean | Only responded or unresponded |
| page | integer | Page number |
| per_page | integer | Rows per page (1-50) |
list_contacts Requires contacts.viewList 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).
| Param | Type | Description |
|---|---|---|
| organization_id | integer | Limit to one organisation |
| contact_list_id | integer | Limit to one contact list |
| subscribed | boolean | Only subscribed (true) or only unsubscribed (false) |
| date_from | date | Created on or after |
| date_to | date | Created on or before |
| include_pii | boolean | Unlock email/phone/name (requires reviews.pii) |
| page | integer | Page number |
| per_page | integer | Rows per page (1-50) |
get_contact_activity Requires contacts.viewThe 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).
| Param | Type | Description |
|---|---|---|
| contact_id* | integer | The contact ID to load activity for |
| limit | integer | Max events to return, newest first (1-100, default 25) |
| include_pii | boolean | Unlock 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.viewPull 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.
| Param | Type | Description |
|---|---|---|
| location_id* | integer | Internal location ID |
| from | date | Inclusive 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. |
| to | date | Inclusive end date (YYYY-MM-DD). Defaults to yesterday. |
| include_daily | boolean | Include the per-day rows. Default false. |
list_gbp_search_terms Requires reviews.viewPull 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.
| Param | Type | Description |
|---|---|---|
| location_id* | integer | Internal location ID |
| year | integer | Defaults to current year. |
| month | integer | 1-12. Omit to return every month in the year. |
| per_page | integer | Rows per page (1-50, default 25) |
| page | integer | Page 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.viewList 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.
| Param | Type | Description |
|---|---|---|
| search | string | Match against business name |
| date_from | date | Inclusive start date (YYYY-MM-DD) |
| date_to | date | Inclusive end date (YYYY-MM-DD) |
| status | string | Pipeline status, e.g. saved, contacted, qualified |
| include_outbound | boolean | Include leads found through outbound prospect search. Default false |
| page | integer | Page number (default 1) |
| per_page | integer | Rows per page (1-50, default 25) |
get_sales_intelligence_lead Requires reviews.viewFetch 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.
| Param | Type | Description |
|---|---|---|
| uuid* | string | The 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.viewPaginated 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.
| Param | Type | Description |
|---|---|---|
| search | string | Free-text over location and keyword |
| is_scheduled | boolean | Only recurring scans |
| completed | boolean | true: 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 |
| failed | boolean | Only scans whose last run failed |
| since_days | integer | Scans created in the last N days (1-365) |
| page | integer | Page number |
| per_page | integer | 1-50, default 20 |
get_scan Requires local_search_grid.viewReturn 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.
| Param | Type | Description |
|---|---|---|
| uuid* | string | Scan UUID |
| snapshot_at | datetime | ISO-8601 timestamp; defaults to the latest snapshot |
| top_n | integer | SERP entries per pin (0-20). Default 5. Pass 20 for the full SERP list per pin. |
get_scan_data_points Requires local_search_grid.viewPaginated 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.
| Param | Type | Description |
|---|---|---|
| uuid* | string | Scan UUID |
| snapshot_at | datetime | ISO-8601 timestamp; defaults to the latest snapshot for the (scan, keyword) combo |
| keyword | string | Restrict to one keyword on multi-keyword scans |
| top_n | integer | Competitors per pin (0-20). Default 5. Pass 0 for just lat/lng/target_rank. |
| page | integer | 1-based page |
| per_page | integer | 1-50, default 50 |
list_scan_snapshots Requires local_search_grid.viewAggregated 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.
| Param | Type | Description |
|---|---|---|
| uuid* | string | Scan UUID |
| keyword | string | Restrict the aggregate to one keyword on a multi-keyword scan |
get_scan_insights Requires local_search_grid.viewEverything 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.
| Param | Type | Description |
|---|---|---|
| uuid* | string | Scan UUID |
| keyword | string | Restrict to one keyword on multi-keyword scans |
| snapshot_at | datetime | ISO-8601 timestamp; defaults to the latest snapshot |
create_scan Requires local_search_grid.runAlso requires mcp:writesCreate 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.
| Param | Type | Description |
|---|---|---|
| location* | string | Human-readable name for the dashboard |
| keywords* | array<string> | 1-20 keyword strings |
| grid_size* | integer | One of 3, 5, 7, 9, 11, 13, 15 |
| distance* | number | Distance from center to outer ring (> 0, ≤ 50) |
| distance_unit* | string | "km" or "miles" |
| address | string | Geocoded via Google Maps if lat/lng not supplied |
| lat | number | Pin grid center latitude |
| lng | number | Pin grid center longitude |
| target_place_id | string | Google Place ID for self-vs-competitor scoring |
| type | string | "business" (default) or "sab" |
run_scan Requires local_search_grid.runAlso requires mcp:writesSnap 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".
| Param | Type | Description |
|---|---|---|
| uuid* | string | Scan UUID |
schedule_scan Requires local_search_grid.runAlso requires mcp:writesEnable 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.
| Param | Type | Description |
|---|---|---|
| uuid* | string | Scan UUID |
| is_scheduled* | boolean | true turns the schedule on, false disables it |
| frequency | string | "weekly", "bi-weekly", or "monthly" |
| scheduled_from | string | 24-hour HH:MM start |
| scheduled_to | string | 24-hour HH:MM end (must be later than scheduled_from) |
| scheduled_days | array<integer> | Day numbers (0 = Sunday, 6 = Saturday) |
| timezone | string | PHP DateTimeZone identifier, e.g. "America/New_York" |
Write tools (review replies held for approval)
(2 tools)draft_review_response Requires reviews.respondAlso requires mcp:writesDraft 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.
| Param | Type | Description |
|---|---|---|
| review_id* | integer | The review to respond to |
| message* | string | The drafted reply (max 8000 chars). It is never sent until a person approves it. |
tag_reviews Requires reviews.editAlso requires mcp:writesAttach 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).
| Param | Type | Description |
|---|---|---|
| review_ids* | array<integer> | Up to 50 review IDs |
| attach_tags | array<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_tags | array<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.viewList 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.
| Param | Type | Description |
|---|---|---|
| organization_id | integer | Only the locations of this client organisation |
| location_ids | array<integer> | Only these locations (1-100 ids) |
| filter | string | all (default) | ready_not_enabled | enabled | needs_attention | autopilot_active. ready_not_enabled: a profile is ready but publishing is off |
| page | integer | Page number (default 1) |
| per_page | integer | Rows per page (1-50, default 20) |
get_publishing_settings Requires publishing.viewRead 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.
| Param | Type | Description |
|---|---|---|
| location_id* | integer | The location, from list_publishing_locations |
| section* | string | facts | instructions | autopilot | schedule | photos |
| page | integer | The page of facts, 25 a page (default 1). Facts section only |
get_post_requirements Requires publishing.viewGet 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.
| Param | Type | Description |
|---|---|---|
| location_id* | integer | The location, from list_publishing_locations |
| kind* | string | update (a news post) | offer (a deal with dates) | event (something on a date) |
| media_count | integer | How many photos the post will carry, 0-10 (default 0). Some formats change with it |
list_posts Requires publishing.viewList 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.
| Param | Type | Description |
|---|---|---|
| organization_id | integer | Only the posts of this client organisation |
| location_id | integer | Only the posts of this location |
| status | array<string> | One or more of generating, draft, awaiting_approval, changes_requested, scheduled, published, partially_published, attention, failed, cancelled, expired |
| kind | string | update | offer | event |
| source | string | Where the post began: manual | autopilot | review | mcp | api |
| date_from | date | Local date (YYYY-MM-DD) |
| date_to | date | Local date (YYYY-MM-DD) |
| waiting_for_approval | boolean | Only posts waiting for an approver (true), or none of them (false) |
| drafted_by | string | Who wrote the current version: assistant | person | autopilot |
| needs_attention | boolean | Only posts that failed, expired or need a look (true), or none of them (false) |
| sort | string | scheduled_asc (default) | scheduled_desc | updated_desc |
| page | integer | Page number (default 1) |
| per_page | integer | Rows per page (1-50, default 20) |
get_post Requires publishing.viewGet 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.
| Param | Type | Description |
|---|---|---|
| post_id* | string (uuid) | The post, from list_posts or from the tool that made it |
| sections | array<string> | content | media | deliveries | approval | checks | history. Default: everything but history |
| history_page | integer | The page of history, 20 items a page, newest first (default 1). Ask for the history section too |
list_media_assets Requires publishing.viewList 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.
| Param | Type | Description |
|---|---|---|
| organization_id | integer | Only the photos of this client organisation |
| location_id | integer | Only the photos this location can use, its client's shared photos included |
| media_asset_ids | array<string> | Only these photos (1-50 uuids) |
| status | string | processing | ready | failed |
| type | string | image | video |
| folder_id | string (uuid) | Only the photos in this folder |
| pool | string | Only the photos in this Autopilot list, for example posts (max 24 chars) |
| unused | boolean | Only 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_description | boolean | Only photos with no description (true), or only described ones (false) |
| geotag | string | on (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 |
| page | integer | Page number (default 1) |
| per_page | integer | Rows per page (1-50, default 20) |
get_publishing_activity Requires publishing.viewSummarise 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.
| Param | Type | Description |
|---|---|---|
| organization_id | integer | Only this client organisation |
| location_id | integer | Only this location |
| period | string | this_month (default) | last_month | last_7_days | last_30_days | custom. custom needs date_from and date_to |
| date_from | date | Start date for a custom period (YYYY-MM-DD) |
| date_to | date | End 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:writesTurn 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.
| Param | Type | Description |
|---|---|---|
| location_ids* | array<integer> | The locations to turn publishing on for, from list_publishing_locations (1-50, no repeats) |
| dry_run | boolean | Check the call and describe what would happen, without changing anything. Default false |
update_publishing_settings Requires publishing.manageAlso requires mcp:writesChange 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.
| Param | Type | Description |
|---|---|---|
| location_id* | integer | The location, from list_publishing_locations |
| section* | string | facts | instructions | schedule | autopilot | photos |
| expected_version* | integer | settings_version from get_publishing_settings |
| changes* | object | At 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_run | boolean | Check the call and describe what would happen, without changing anything. Default false |
set_autopilot_status Requires publishing.manageAlso requires mcp:writesPause 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.
| Param | Type | Description |
|---|---|---|
| location_id* | integer | The location, from list_publishing_locations |
| status* | string | paused stops new drafts | active starts or resumes them |
| dry_run | boolean | Check the call and describe what would happen, without changing anything. Default false |
draft_post Requires publishing.createAlso requires mcp:writesSave 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.
| Param | Type | Description |
|---|---|---|
| location_id* | integer | The location, from list_publishing_locations |
| kind* | string | update | offer | event |
| body* | string | The post text (1-5000 chars) |
| title | string | The title of an offer or event (max 255 chars) |
| details | object | Offer 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_url | string | An https link for the button (max 2048 chars) |
| cta | string | learn_more | book | order | shop | sign_up | call |
| media_asset_ids | array<string> | Photos from list_media_assets, in the order they show (up to 10 uuids, no repeats) |
| scheduled_for | string | Local time at the location, like 2026-10-05T09:30 |
| language | string | A language code (max 12 chars); empty uses the location's primary post language |
| idempotency_key | string | Your 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_run | boolean | Check the call and describe what would happen, without changing anything. Default false |
generate_post Requires publishing.createAlso requires mcp:writesAsk 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.
| Param | Type | Description |
|---|---|---|
| location_id* | integer | The location, from list_publishing_locations |
| kind* | string | update | offer | event |
| topic | string | What this one post should be about (max 500 chars) |
| service | string | A service fact id from get_publishing_settings (max 64 chars) |
| scheduled_for | string | Local time at the location, like 2026-10-05T09:30 |
| idempotency_key | string | Your own key for this request (1-64 chars). Repeating the call with the same key and arguments returns the first result |
| dry_run | boolean | Return the plan without writing. Default false |
update_post Requires publishing.createAlso requires mcp:writesEdit 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.
| Param | Type | Description |
|---|---|---|
| post_id* | string (uuid) | The post, from list_posts or get_post |
| expected_revision* | integer | The revision from get_post |
| title | string | null | The title of an offer or event (max 255 chars) |
| body | string | The post text (1-5000 chars) |
| details | object | null | Offer or event details, the same keys as draft_post. Local times, no zone |
| link_url | string | null | An https link for the button (max 2048 chars) |
| cta | string | null | learn_more | book | order | shop | sign_up | call |
| media_asset_ids | array<string> | The photos in the order they show (up to 10 uuids); an empty list removes them |
| dry_run | boolean | Check the call and describe what would happen, without changing anything. Default false |
request_post_approval Requires publishing.createAlso requires mcp:writesSend 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.
| Param | Type | Description |
|---|---|---|
| post_ids* | array<string> | The posts to send (1-20 uuids, no repeats) |
| note | string | A short note for the approvers (max 500 chars) |
| dry_run | boolean | Check the call and describe what would happen, without changing anything. Default false |
reschedule_post Requires publishing.createAlso requires mcp:writesChange 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.
| Param | Type | Description |
|---|---|---|
| post_id* | string (uuid) | The post, from list_posts or get_post |
| scheduled_for* | string | Local time at the location, like 2026-10-05T09:30 |
| dry_run | boolean | Check the call and describe what would happen, without changing anything. Default false |
cancel_post Requires publishing.createAlso requires mcp:writesCancel 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.
| Param | Type | Description |
|---|---|---|
| post_id* | string (uuid) | The post, from list_posts or get_post |
| expected_revision | integer | The revision from get_post; when given, a newer revision refuses the call |
| dry_run | boolean | Check the call and describe what would happen, without changing anything. Default false |
add_media_from_url Requires publishing.mediaAlso requires mcp:writesAdd 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.
| Param | Type | Description |
|---|---|---|
| location_id* | integer | The location, from list_publishing_locations |
| organization_wide | boolean | File the photo for every location of this client. Default false |
| url* | string | A public https link to the photo (max 2048 chars) |
| description* | string | What the photo shows (1-1000 chars) |
| alt_text | string | Alt text (max 500 chars) |
| title | string | Title (max 255 chars) |
| folder_id | string (uuid) | A folder in the media library |
| pools | array<string> | Autopilot lists to put the photo in (up to 10, each max 24 chars) |
| geotag | boolean | Tag 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_key | string | Your own key for this request (1-64 chars). Repeating the call with the same key and arguments returns the first result |
| dry_run | boolean | Check the call and describe what would happen, without changing anything. Default false |
update_media_asset Requires publishing.mediaAlso requires mcp:writesChange a photo's title, description, alt text, folder, Autopilot pools or geotag. Needs publishing:write.
| Param | Type | Description |
|---|---|---|
| media_asset_id* | string (uuid) | The photo, from list_media_assets |
| title | string | null | Title (max 255 chars) |
| description | string | null | What the photo shows (max 1000 chars) |
| alt_text | string | null | Alt text (max 500 chars) |
| folder_id | string (uuid) | null | A folder id, or null for no folder |
| pools | array<string> | null | The Autopilot lists the photo is in (up to 10); null or an empty list takes it out of all of them |
| geotag | boolean | Tag 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_run | boolean | Check 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.viewList 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.
| Param | Type | Description |
|---|---|---|
| search | string | Filter by provider name |
| page | integer | Page number |
| per_page | integer | Rows per page |
get_sms_provider Requires sms_providers.viewGet 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.
| Param | Type | Description |
|---|---|---|
| provider_id* | integer | The SMS provider id from list_sms_providers |
list_sms_provider_types Requires sms_providers.viewList 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.
| Param | Type | Description |
|---|---|---|
| transport | string | Only this type, e.g. "twilio" |
list_sms_provider_organizations Requires sms_providers.viewList the organisations an SMS provider is assigned to, with the sender each one uses instead of the provider's own.
| Param | Type | Description |
|---|---|---|
| provider_id* | integer | The SMS provider id |
| search | string | Filter by organisation name |
| page | integer | Page number |
| per_page | integer | Rows per page |
list_sms_provider_numbers Requires sms_providers.viewList 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.
| Param | Type | Description |
|---|---|---|
| provider_id* | integer | The SMS provider id |
| area_code | string | SignalHouse only: preferred area code, e.g. "614" |
| country | string | SignalHouse only: two-letter country, default US |
create_sms_provider Requires sms_providers.manageAlso requires mcp:writesSet 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.
| Param | Type | Description |
|---|---|---|
| transport* | string | The provider type from list_sms_provider_types |
| name | string | Display name; the type's name when left out |
| credentials | object | What signs in to the provider, by the field names of its type, e.g. Twilio {"sid", "token"} |
| sender | object | Who messages come from: phone, phone_country, sender_name, short_code or channel_id, as the type takes |
| settings | object | Other fields of the type, e.g. Amazon SNS {"region", "message_type"} |
update_sms_provider Requires sms_providers.manageAlso requires mcp:writesChange 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.
| Param | Type | Description |
|---|---|---|
| provider_id* | integer | The SMS provider id |
| name | string | New display name |
| credentials | object | Credential fields to replace |
| sender | object | Sender fields to replace |
| settings | object | Setting fields to replace |
delete_sms_provider Requires sms_providers.manageAlso requires mcp:writesDelete 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.
| Param | Type | Description |
|---|---|---|
| provider_id* | integer | The SMS provider id |
| confirm* | boolean | Must be true: the person asked for this provider to be deleted |
set_default_sms_provider Requires sms_providers.manageAlso requires mcp:writesMake 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.
| Param | Type | Description |
|---|---|---|
| provider_id* | integer | The SMS provider id |
assign_sms_provider Requires sms_providers.manageAlso requires mcp:writesAssign 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.
| Param | Type | Description |
|---|---|---|
| provider_id* | integer | The SMS provider id |
| organization_id* | integer | The organisation id from list_organizations |
| sender | object | This 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:writesRemove 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).
| Param | Type | Description |
|---|---|---|
| provider_id* | integer | The SMS provider id |
| organization_id* | integer | An organisation the provider is assigned to |
manage_signalhouse_registration Requires sms_providers.manageAlso requires mcp:writesRegister 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.
| Param | Type | Description |
|---|---|---|
| provider_id* | integer | The SMS provider id |
| action* | string | "register", "appeal", "retry", "change_number" or "restart" |
| details | object | For "register": the business being registered and the sending number |
| phone_number | string | For "change_number": the new sending number |
| area_code | string | For "change_number": preferred area code |
| reason | string | For "appeal": why a rejected campaign should be reconsidered (10-2,048 characters) |
| confirm | boolean | For "restart": must be true; a rejected brand costs a new fee to register again |
send_test_sms Requires sms_providers.manageAlso requires mcp:writesSend 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.
| Param | Type | Description |
|---|---|---|
| provider_id* | integer | The SMS provider id |
| to* | string | The phone to text, international format (or national with phone_country) |
| phone_country | string | Two-letter country of a national-format number |
| message | string | Optional text; a short test sentence otherwise |
| organization_id | integer | Send as this organisation (it must be assigned to the provider) |
update_sms_settings Requires sms_providers.manageAlso requires mcp:writesChange 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).
| Param | Type | Description |
|---|---|---|
| append_text* | string | null | The 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.
| Code | Meaning | When |
|---|---|---|
| -32700 | Parse error | Request body is not valid JSON |
| -32600 | Invalid request | Missing method, wrong jsonrpc version, or malformed envelope |
| -32601 | Method not found | Unknown method, or tools/call pointing at a tool that does not exist |
| -32602 | Invalid params | Validation failed, unknown parameter, or missing required parameter |
| -32603 | Internal error | Unexpected server-side failure |
| -32001 | Unauthenticated | Token missing, invalid, or lacks mcp:access |
| -32001 | Missing permission | Token lacks the required ability (e.g. mcp:writes) or semantic permission |
| -32001 | Access denied | Passed an organization_id or location_id outside the caller's scope |
| -32001 | Subscription inactive or paused | The subscription behind the call is not active or is paused. The HTTP status is 403 Forbidden |
| -32002 | Not found | Tool resolved the request but no matching record exists |
| -32002 | Rate limit exceeded | Per-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.