Cheers Public API

The Cheers API allows you to programmatically access your organization's review data, badges, taps, and more. All API endpoints require authentication via API key.

Base URLhttps://app.cheers.tech/api/public/v1

Authentication

All API requests require a Bearer token in the Authorization header. To obtain an API key, visit your organization settings or contact your Cheers account administrator.

Example Request

curl -X GET "https://app.cheers.tech/api/public/v1/organizations?organization_id=123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Rate Limits

Limits use a sliding 60-second window and are scoped by API key and endpoint. A request that passes the limiter consumes a slot even if later validation fails.

Surface	Limit	Details
GET endpoints	100 requests per 60 seconds	Per API key and endpoint. Different GET endpoints have independent counters.
Single POST /employee-links	500 requests per 60 seconds	Creates or reuses one employee and one location card.
Bulk POST /employee-links	10 batches per 60 seconds	Up to 100 items per batch (up to 1,000 link attempts per minute). Batch calls also count toward the 500-request POST budget.
DELETE /employee-links	500 requests per 60 seconds	Per API key.
PATCH /cards	500 requests per 60 seconds	Per API key.

A limited request returns 429 Too Many Requests with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Wait for Retry-After seconds, then retry the same request unchanged.

Common Parameters

Most endpoints support the following query parameters for filtering, pagination, and date-based queries.

Parameter	Type	Required	Description
`organization_id`	integer	Optional	Filter by specific organization ID
`parent_organization_id`	integer	Optional	Get data for all child organizations
`from`	ISO 8601 datetime	Optional	Filter records updated after this time
`to`	ISO 8601 datetime	Optional	Filter records updated before this time
`created_from`	ISO 8601 datetime	Optional	Filter records created after this time
`created_to`	ISO 8601 datetime	Optional	Filter records created before this time
`limit`	integer	Optional	Maximum records to return (default: 100; max 1000 with offset pagination, max 999 on cursor/checkpoint exports)
`offset`	integer	Optional	Number of records to skip for pagination

Note: Either organization_id or parent_organization_id is required for all endpoints.

Endpoints

GET/organizations

Retrieve organization details.

Query Parameters

Parameter	Type	Required	Description
`organization_id`	integer	Optional	Specific organization ID (one of organization_id or parent_organization_id required)
`parent_organization_id`	integer	Optional	Get all child organizations (one of organization_id or parent_organization_id required)
`city`	string	Optional	Exact city match, case-insensitive
`state`	string	Optional	Exact state name or code match, case-insensitive
`is_active`	boolean	Optional	Filter active or inactive locations

Response Fields

Field	Type	Description
`id`	integer	Organization ID
`name`	string	Organization name
`created_at`	datetime	When the organization was created
`updated_at`	datetime	Last update timestamp
`billing_status`	string	Billing status (NOT PAID, PAID, EXEMPT)
`plan_tier`	string	Product tier (STARTER, GROWTH, PRO, ENTERPRISE)
`subscription_tier`	string	Legacy billing mirror; use billing_status going forward
`parent_organization_id`	integer	Parent organization ID (null if root)
`city`	string	Location city
`state`	string	Location state or region
`latitude`	number	Location latitude
`longitude`	number	Location longitude
`timezone`	string	IANA timezone
`is_active`	boolean	Whether the location is active

Request

curl -X GET "https://app.cheers.tech/api/public/v1/organizations?organization_id=123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "id": 123,
    "name": "Acme Restaurant",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-06-20T14:45:00Z",
    "billing_status": "PAID",
    "plan_tier": "GROWTH",
    "subscription_tier": "PAID",
    "parent_organization_id": null
  }
]

GET/location-links

Map each scoped business location to its configured Cheers survey URL and Trustpilot destination.

Query Parameters

Parameter	Type	Required	Description
`organization_id`	integer	Optional	One location in the API key hierarchy (exactly one scope selector is required)
`parent_organization_id`	integer	Optional	The key organization and all current descendants (exactly one scope selector is required)
`state`	string	Optional	Optional exact state filter, case-insensitive (for example TX)

Response Fields

Field	Type	Description
`organization_id`	integer	Cheers organization/location ID
`name`	string	Location name
`parent_organization_id`	integer	Parent organization ID
`address fields`	string	Structured address, city, state, country, and postal code
`latitude, longitude`	number	Configured location coordinates
`timezone`	string	IANA location timezone
`cheers_survey_urls`	array	Active Cheers card URLs with source=survey attribution
`trustpilot_destinations`	array	Active Trustpilot destinations configured for this location
`mapping_status`	string	ready or an explicit missing-link status

A missing status reflects real configuration state; the API never fabricates a destination.

Every usable configured card and Trustpilot review destination is returned; oversized responses fail with 413 instead of being silently truncated.

The database derives and verifies the exact organization hierarchy for every request.

Request

curl -X GET "https://app.cheers.tech/api/public/v1/location-links?parent_organization_id=123&state=TX" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "organization_id": 1300,
    "name": "Houston",
    "city": "Houston",
    "state": "TX",
    "cheers_survey_urls": [{ "card_id": "550e8400-e29b-41d4-a716-446655440000", "url": "https://app.cheers.tech/api/v1/tap?card-id=550e8400-e29b-41d4-a716-446655440000&source=survey" }],
    "trustpilot_destinations": [{ "link_id": 101, "name": "Trustpilot", "url": "https://www.trustpilot.com/evaluate/example.com" }],
    "mapping_status": "ready"
  }
]

GET/organization-connections

Retrieve platform connections for organizations (Google, Yelp, Facebook, etc.).

Query Parameters

Parameter	Type	Required	Description
`organization_id`	integer	Optional	Specific organization ID (one of organization_id or parent_organization_id required)
`parent_organization_id`	integer	Optional	Get connections for all child organizations (one of organization_id or parent_organization_id required)

Response Fields

Field	Type	Description
`organization_id`	integer	Organization ID
`google_place_id`	string	Google Places ID
`google_account_id`	string	Google Business Profile account ID
`google_location_id`	string	Google Business Profile location ID
`yelp_business_id`	string	Yelp business ID
`tripadvisor_location_id`	string	Tripadvisor location ID
`facebook_page_id`	string	Facebook page ID
`facebook_url`	string	Facebook page URL
`trustpilot_company_website`	string	Trustpilot company identifier
`bbb_profile_url`	string	Better Business Bureau profile URL
`created_at`	datetime	When the connection was created

Request

curl -X GET "https://app.cheers.tech/api/public/v1/organization-connections?organization_id=123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "organization_id": 123,
    "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
    "google_account_id": "accounts/123456789",
    "google_location_id": "locations/987654321",
    "yelp_business_id": "acme-restaurant-new-york",
    "tripadvisor_location_id": null,
    "facebook_page_id": "123456789012345",
    "facebook_url": "https://facebook.com/acmerestaurant",
    "trustpilot_company_website": null,
    "bbb_profile_url": null,
    "created_at": "2024-01-15T10:30:00Z"
  }
]

GET/cards

Retrieve badge/card information for your organization.

Query Parameters

Parameter	Type	Required	Description
`organization_id`	integer	Optional	Specific organization ID (one of organization_id or parent_organization_id required)
`parent_organization_id`	integer	Optional	Get cards for all child organizations (one of organization_id or parent_organization_id required)

Response Fields

Field	Type	Description
`id`	string (UUID)	Unique card identifier
`created_at`	datetime	When the card was created
`updated_at`	datetime	Last update timestamp
`cardholder_name`	string	Name of the badge holder
`employee_id`	string (UUID)	Employee represented by the card
`organization_id`	integer	Organization ID
`title`	string	Badge holder's title/position
`photo_url`	string	URL to badge holder's photo
`encode_url`	string	Encoded URL for the badge
`linktree_enabled`	boolean	Whether linktree is enabled for this card
`direct_link_id`	integer	Explicit direct review destination, when configured
`badge_number`	string	Custom badge identifier

Request

curl -X GET "https://app.cheers.tech/api/public/v1/cards?organization_id=123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-03-01T09:00:00Z",
    "updated_at": "2024-03-15T14:30:00Z",
    "cardholder_name": "John Smith",
    "organization_id": 123,
    "title": "Server",
    "photo_url": "https://storage.cheers.tech/photos/john-smith.jpg",
    "encode_url": "https://app.cheers.tech/t/abc123",
    "linktree_enabled": true,
    "badge_number": "EMP-001"
  }
]

PATCH/cards

Update a card's organization assignment.

Request Body

Parameter	Type	Required	Description
`cardId`	string (body)	Optional	Card UUID to update (one of cardId or badge_number required)
`badge_number`	string (body)	Optional	Badge number for bulk update (one of cardId or badge_number required)
`organization_id`	integer (body)	Required	Target organization ID

Either cardId or badge_number is required in the request body.

Request

curl -X PATCH "https://app.cheers.tech/api/public/v1/cards" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cardId": "550e8400-e29b-41d4-a716-446655440000", "organization_id": 456}'

Response

{
  "success": true
}

GET/taps

Retrieve tap events (when a customer taps a badge).

Query Parameters

Parameter	Type	Required	Description
`organization_id`	integer	Optional	Specific organization ID (one of organization_id or parent_organization_id required)
`parent_organization_id`	integer	Optional	Get taps for all child organizations (one of organization_id or parent_organization_id required)

Response Fields

Field	Type	Description
`id`	integer	Tap ID
`created_at`	datetime	When the tap occurred
`updated_at`	datetime	Last update timestamp
`card_id`	string (UUID)	Associated card ID
`organization_id`	integer	Organization ID
`source`	string	Recorded source of the visit
`used`	boolean	Whether the tap resulted in a completed action

Request

curl -X GET "https://app.cheers.tech/api/public/v1/taps?organization_id=123&from=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "id": 12345,
    "created_at": "2024-06-15T18:30:00Z",
    "updated_at": "2024-06-15T18:30:00Z",
    "card_id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": 123,
    "source": "badge",
    "used": true
  }
]

GET/reviews

Retrieve customer reviews from all connected platforms.

Query Parameters

Parameter	Type	Required	Description
`organization_id`	integer	Optional	Specific organization ID (one of organization_id or parent_organization_id required)
`parent_organization_id`	integer	Optional	Get reviews for all child organizations (one of organization_id or parent_organization_id required)
`format`	string	Optional	Use "v2" or "new" for full response fields

Response Fields

Field	Type	Description
`id`	integer	Review ID
`created_at`	datetime	When the review was received
`updated_at`	datetime	Last update timestamp
`rating`	integer	Rating value (1-5)
`card_id`	string	Associated card ID (if attributed)
`review_text`	string	Full review text
`organization_id`	integer	Organization ID
`source`	string	Platform source (GOOGLE, YELP, FACEBOOK, etc.)
`reviewer_name`	string	Reviewer's display name
`reviewer_photo_url`	string	Reviewer's profile photo
`owner_response`	string	Business owner's response
`response_timestamp`	datetime	When the response was posted
`review_url`	string	Direct link to the review
`internal`	boolean	Whether this is an internal Cheers review
`not_showing`	boolean	Whether the review is retained in API history but no longer showing on the source platform
`not_showing_at`	datetime	When Cheers detected the review was no longer showing on the source platform; null when not_showing is false

Use format=v2 to get all available fields including source and reviewer information.

Reviews with not_showing=true are retained for API history but hidden from Cheers review counts and views.

not_showing_at is the time Cheers detected the review was no longer showing on the source platform, not necessarily the exact platform deletion time.

from and to filters include the time Cheers first ingested a review and include not_showing_at for reviews where not_showing=true, so rolling syncs recover late arrivals and deletion visibility changes.

The ingestion timestamp is not exported; clients must trust the server-side activity-window decision instead of re-filtering returned rows by visible timestamps.

Request

curl -X GET "https://app.cheers.tech/api/public/v1/reviews?organization_id=123&format=v2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "id": 5678,
    "created_at": "2024-06-10T12:00:00Z",
    "updated_at": "2024-06-10T12:00:00Z",
    "rating": 5,
    "card_id": "550e8400-e29b-41d4-a716-446655440000",
    "review_text": "Amazing service! John was incredibly helpful.",
    "organization_id": 123,
    "source": "GOOGLE",
    "reviewer_name": "Jane D.",
    "reviewer_photo_url": "https://lh3.googleusercontent.com/...",
    "owner_response": "Thank you for the kind words!",
    "response_timestamp": "2024-06-11T09:00:00Z",
    "review_url": "https://search.google.com/local/reviews?...",
    "internal": false,
    "not_showing": false,
    "not_showing_at": null
  }
]

GET/links

Retrieve review links configured for your organization.

Query Parameters

Parameter	Type	Required	Description
`organization_id`	integer	Optional	Specific organization ID (one of organization_id or parent_organization_id required)
`parent_organization_id`	integer	Optional	Get links for all child organizations (one of organization_id or parent_organization_id required)

Response Fields

Field	Type	Description
`id`	integer	Link ID
`created_at`	datetime	When the link was created
`updated_at`	datetime	Last update timestamp
`url`	string	Review link URL
`organization_id`	integer	Organization ID
`name`	string	Display name for the link
`subtitle`	string	Optional subtext displayed under the link name
`sms_template`	string	SMS template text
`is_verify`	boolean	Whether this is a verification link

Request

curl -X GET "https://app.cheers.tech/api/public/v1/links?organization_id=123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "id": 101,
    "created_at": "2024-02-01T10:00:00Z",
    "updated_at": "2024-02-01T10:00:00Z",
    "url": "https://search.google.com/local/writereview?placeid=ChIJN1t_tDeuEmsRUsoyG83frY4",
    "organization_id": 123,
    "name": "Leave a Google Review",
    "subtitle": "Leave a review",
    "sms_template": null,
    "is_verify": false
  }
]

GET/link_interactions

Retrieve link click/interaction events.

Query Parameters

Parameter	Type	Required	Description
`organization_id`	integer	Optional	Specific organization ID (one of organization_id or parent_organization_id required)
`parent_organization_id`	integer	Optional	Get interactions for all child organizations (one of organization_id or parent_organization_id required)

Response Fields

Field	Type	Description
`id`	integer	Interaction ID
`link_id`	integer	Associated link ID
`card_id`	string (UUID)	Associated card ID
`created_at`	datetime	When the interaction occurred
`updated_at`	datetime	Last update timestamp
`used`	boolean	Whether the interaction was completed
`organization_id`	integer	Organization ID

Request

curl -X GET "https://app.cheers.tech/api/public/v1/link_interactions?organization_id=123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "id": 9876,
    "link_id": 101,
    "card_id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-06-15T18:31:00Z",
    "updated_at": "2024-06-15T18:31:00Z",
    "used": true,
    "organization_id": 123
  }
]

POST/employee-links

Create or update one employee review link, or provision up to 100 links with an items array. One case-insensitive agent_id maps to one employee across the root organization.

Request Body

Parameter	Type	Required	Description
`items`	employee link object[] (body)	Optional	Batch form containing 1–100 objects with the same fields below; omit for a single-item request
`organization_id`	integer (body)	Required	Cheers location organization ID
`agent_id`	string (body)	Required	Caller-owned agent identifier; case-insensitively unique within the root organization
`first_name`	string (body)	Required	Employee first name
`last_name`	string (body)	Optional	Employee last name
`title`	string (body)	Optional	Employee title
`email`	string (body)	Optional	Employee email address
`phone_number`	string (body)	Optional	Employee phone number
`photo_url`	URL (body)	Optional	Supported public image URL, such as a public Supabase Storage object
`destination_mode`	linktree \| direct (body)	Optional	Use the Cheers landing page by default, or follow a direct review destination
`review_link_id`	integer (body)	Optional	Allowed location or ancestor review link; valid only in direct mode
`reactivate`	boolean (body)	Optional	Set true to reactivate an archived agent and provision a fresh link; otherwise archived agents return employee_archived

Response Fields

Field	Type	Description
`employee_id`	string (UUID)	Cheers employee ID
`card_id`	string (UUID)	Stable employee/location card ID
`organization_id`	integer	Cheers location organization ID
`agent_id`	string	Agent identifier supplied in the request
`destination_mode`	string	linktree or direct
`review_link_id`	integer \| null	Explicit direct review link when configured
`url`	URL	Public redirect URL for the employee/location pair
`landing_page_url`	URL \| null	Direct Cheers landing-page URL in linktree mode
`created_employee`	boolean	Whether this request created the employee
`created_link`	boolean	Whether this request created the card/link

Repeated requests with the same case-insensitive agent_id reuse one root employee; each location receives at most one active card for that employee.

Batch responses preserve input order. Full success returns 200; partial failure returns 207 with per-item status values. Successful items remain committed and are safe to retry.

Repeated agent_id values in one batch must use identical employee metadata, while organization and destination fields may differ.

API-provisioned cards are digital-only and never enter the physical badge print queue.

The API key must belong to the root organization, and organization_id must be an active location within that tenant.

Archived agents are never reactivated as a side effect; send reactivate: true to bring one back.

Request

curl -X POST "https://app.cheers.tech/api/public/v1/employee-links" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "agent_id": "AGENT-0042",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "destination_mode": "linktree"
  }'

Response

{
  "employee_id": "8b194ed6-88a0-4f42-a280-d63ea47b5718",
  "card_id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": 456,
  "agent_id": "AGENT-0042",
  "destination_mode": "linktree",
  "review_link_id": null,
  "url": "https://app.cheers.tech/api/v1/tap?card-id=550e8400-e29b-41d4-a716-446655440000",
  "landing_page_url": "https://app.cheers.tech/urltree?id=550e8400-e29b-41d4-a716-446655440000",
  "created_employee": true,
  "created_link": true
}

Batch (up to 100 links)

Request

curl -X POST "https://app.cheers.tech/api/public/v1/employee-links" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "organization_id": 456,
        "agent_id": "AGENT-0042",
        "first_name": "Ada",
        "last_name": "Lovelace"
      },
      {
        "organization_id": 789,
        "agent_id": "AGENT-0042",
        "first_name": "Ada",
        "last_name": "Lovelace"
      }
    ]
  }'

Response

{
  "requested": 2,
  "succeeded": 2,
  "failed": 0,
  "created_employee_count": 1,
  "created_link_count": 2,
  "results": [
    {
      "index": 0,
      "status": 201,
      "employee_id": "8b194ed6-88a0-4f42-a280-d63ea47b5718",
      "card_id": "550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "index": 1,
      "status": 201,
      "employee_id": "8b194ed6-88a0-4f42-a280-d63ea47b5718",
      "card_id": "550e8400-e29b-41d4-a716-446655440001"
    }
  ]
}

DELETE/employee-links

Terminate an agent. Deactivates the agent's review links and archives the employee. Idempotent: repeating the call returns 200 with zero newly deactivated links.

Request Body

Parameter	Type	Required	Description
`agent_id`	string (body or query)	Required	Caller-owned agent identifier supplied when the link was provisioned
`organization_id`	integer (body or query)	Optional	Limit deactivation to this location's link and keep the employee active elsewhere. Omit to deactivate every link and archive the employee.

Response Fields

Field	Type	Description
`employee_id`	string (UUID)	Cheers employee ID
`agent_id`	string	Agent identifier supplied in the request
`organization_id`	integer \| null	Location scope applied, or null for all locations
`employee_archived`	boolean	Whether the employee is now archived
`deactivated_link_count`	integer	Links deactivated by this request
`deactivated_card_ids`	string[]	Card IDs deactivated by this request

A deactivated link stops resolving; visitors who follow it see the inactive-link page instead of a review destination.

Historical taps and reviews stay attributed to the agent after termination.

An unknown agent_id returns 404 employee_not_found; an organization_id outside the tenant returns 403.

Request

curl -X DELETE "https://app.cheers.tech/api/public/v1/employee-links" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "AGENT-0042" }'

Response

{
  "employee_id": "8b194ed6-88a0-4f42-a280-d63ea47b5718",
  "agent_id": "AGENT-0042",
  "organization_id": null,
  "employee_archived": true,
  "deactivated_link_count": 1,
  "deactivated_card_ids": ["550e8400-e29b-41d4-a716-446655440000"]
}

GET/gbp-performance

Retrieve daily Google Business Profile Search, Maps, and customer-action metrics by location.

Query Parameters

Parameter	Type	Required	Description
`organization_id`	integer	Optional	Specific location (one of organization_id or parent_organization_id required)
`parent_organization_id`	integer	Optional	Root organization and all permitted descendants
`from`	ISO date or datetime	Optional	First calendar date; defaults to the previous 30 complete UTC dates
`to`	ISO date or datetime	Optional	Last calendar date
`limit`	integer	Optional	Maximum rows, up to 500
`offset`	integer	Optional	Rows to skip

Response Fields

Field	Type	Description
`organization_id`	integer	Cheers location organization ID
`date`	date	Metric calendar date
`data_status`	complete \| unavailable	Whether an observation exists for the connected location/day
`search_views`	integer \| null	Combined desktop and mobile Search impressions
`maps_views`	integer \| null	Combined desktop and mobile Maps impressions
`website_clicks`	integer \| null	Website actions
`phone_calls`	integer \| null	Call actions
`direction_requests`	integer \| null	Direction actions
`total_actions`	integer \| null	Website clicks + phone calls + direction requests
`bookings`	integer \| null	Bookings, reported separately from total_actions
`last_updated_at`	datetime \| null	Freshness timestamp for the observation

Missing observations are returned as unavailable with null metrics, never as misleading zeroes.

Request

curl -X GET "https://app.cheers.tech/api/public/v1/gbp-performance?parent_organization_id=123&from=2026-08-01&to=2026-08-07&limit=500" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "organization_id": 456,
    "date": "2026-08-01",
    "data_status": "complete",
    "search_views": 320,
    "maps_views": 184,
    "website_clicks": 12,
    "phone_calls": 8,
    "direction_requests": 5,
    "total_actions": 25,
    "bookings": 2,
    "last_updated_at": "2026-08-02T12:00:00.000Z"
  }
]

GET/search-performance

Retrieve daily Google Search Console, Google Analytics, referral, and Cheers Search Visibility metrics by location.

Query Parameters

Parameter	Type	Required	Description
`organization_id`	integer	Optional	Specific non-ADMIN location (exactly one scope selector is required)
`parent_organization_id`	integer	Optional	Root organization and all permitted non-ADMIN descendants
`from`	ISO date or datetime	Optional	First calendar date; defaults to the previous 30 complete UTC dates
`to`	ISO date or datetime	Optional	Last calendar date
`limit`	integer	Optional	Maximum location/day rows, up to 500
`offset`	integer	Optional	Rows to skip

Response Fields

Field	Type	Description
`organization_id`	integer	Cheers location organization ID
`date`	date	Metric calendar date
`data_status`	complete \| partial \| unavailable	Combined source availability for the location/day
`search_impressions, search_clicks`	integer \| null	Authoritative Search Console property totals
`search_ctr`	number \| null	Search click-through rate as a 0–1 ratio
`average_search_position`	number \| null	Average Search Console position
`sessions and channel fields`	integer \| null	GA4 total, organic, direct, referral, social, and paid sessions
`search_visibility_score`	number \| null	Stored Cheers Search Visibility score
`source status/freshness`	string \| datetime \| null	Per-source maintained ingest receipts, fetch status, and freshness metadata

A row is complete only when both GSC and GA4 observations exist. Missing source metrics stay null.

Use X-Total-Count, X-Limit, and X-Offset for pagination.

Request

curl -X GET "https://app.cheers.tech/api/public/v1/search-performance?parent_organization_id=123&from=2026-08-01&to=2026-08-07&limit=500" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "organization_id": 456,
    "date": "2026-08-01",
    "data_status": "complete",
    "search_impressions": 950,
    "search_clicks": 74,
    "search_ctr": 0.0779,
    "average_search_position": 6.4,
    "sessions": 410,
    "organic_sessions": 220,
    "referral_sessions": 31,
    "search_visibility_score": 72,
    "last_updated_at": "2026-08-04T12:00:00.000Z"
  }
]

GET/search-keywords

Retrieve daily Google Search Console query metrics by location.

Query Parameters

Parameter	Type	Required	Description
`organization_id`	integer	Optional	Specific non-ADMIN location (exactly one scope selector is required)
`parent_organization_id`	integer	Optional	Root organization and all permitted non-ADMIN descendants
`from`	ISO date or datetime	Optional	First calendar date; maximum 31-day window
`to`	ISO date or datetime	Optional	Last calendar date
`limit`	integer	Optional	Maximum rows, up to 500
`offset`	integer	Optional	Rows to skip

Response Fields

Field	Type	Description
`organization_id`	integer	Cheers location organization ID
`date`	date	Metric calendar date
`query`	string	Google Search query
`impressions, clicks`	integer	Daily query impressions and clicks
`search_ctr`	number \| null	Daily query click-through rate as a 0–1 ratio
`average_search_position`	number \| null	Daily query average position
`coverage`	string	Explicit bounded-retention contract
`last_updated_at`	datetime	Freshness timestamp

Query rows are a top-500 daily diagnostic dimension and must not be summed as property totals.

Each request is limited to a 31-day window.

Advance offset by X-Limit while X-Has-More is true.

Request

curl -X GET "https://app.cheers.tech/api/public/v1/search-keywords?parent_organization_id=123&from=2026-08-01&to=2026-08-07&limit=500" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "organization_id": 456,
    "date": "2026-08-01",
    "query": "best electricity provider",
    "impressions": 85,
    "clicks": 7,
    "search_ctr": 0.0824,
    "average_search_position": 5.2,
    "coverage": "daily_top_500_queries_by_impressions_per_location"
  }
]

GET/website-optimization-scores

Retrieve Website Optimization audit state and versioned site scores.

Query Parameters

Parameter	Type	Required	Description
`organization_id`	integer	Optional	Specific organization in the API key hierarchy
`parent_organization_id`	integer	Optional	Root organization and all permitted descendants
`from`	ISO date or datetime	Optional	First audit week_start date
`to`	ISO date or datetime	Optional	Last audit week_start date
`limit`	integer	Optional	Maximum rows, up to 500
`offset`	integer	Optional	Rows to skip

Response Fields

Field	Type	Description
`audit_run_id`	UUID	Stable audit run identifier
`organization_id`	integer	Cheers organization ID
`week_start`	date	Audit week
`data_status`	complete \| unavailable	Whether comparable site scores exist
`availability_reason`	string \| null	Typed unavailable reason
`audit_status, audit_phase`	string	Audit lifecycle state
`score fields`	number \| null	Overall, schema, AI readiness, content, performance, and crawlability scores
`score_model_version`	integer \| null	Score formula version required for comparison

Queued, failed, blocked, or unscored audits retain null scores; zero is never substituted.

Compare score movement only when the score_model_version supports that comparison.

Advance offset by X-Limit while X-Has-More is true.

Request

curl -X GET "https://app.cheers.tech/api/public/v1/website-optimization-scores?parent_organization_id=123&from=2026-07-01&to=2026-08-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "audit_run_id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": 456,
    "week_start": "2026-08-17",
    "data_status": "complete",
    "overall_score": 82,
    "schema_score": 70,
    "ai_readiness_score": 88,
    "content_score": 80,
    "performance_score": 76,
    "crawlability_score": 91,
    "score_model_version": 15
  }
]

GET/map-pack-rankings

Retrieve every grid-point rank observation from completed Google Local Finder runs.

Query Parameters

Parameter	Type	Required	Description
`organization_id`	integer	Required	One non-ADMIN location in the API key hierarchy
`from`	ISO date or datetime	Optional	First UTC capture date; maximum 31-day window
`to`	ISO date or datetime	Optional	Last UTC capture date
`limit`	integer	Optional	Maximum grid rows, up to 999
`cursor`	string	Optional	Opaque X-Next-Cursor value from the previous page

Response Fields

Field	Type	Description
`organization_id`	integer	Cheers location organization ID
`tracked_keyword_id, keyword`	UUID \| string	Tracked search term identity
`run_id`	UUID	Group key for one completed grid run
`grid_generation`	integer	Versioned grid identity
`grid_row, grid_col`	integer	Zero-based grid placement
`latitude, longitude`	number	Exact query point coordinates
`run_data_status`	complete \| partial \| unknown	Run-level grid completeness
`grid-point counts`	integer \| null	Expected, succeeded, and failed point counts
`business_rank`	integer \| null	Numerical rank within the observed results
`rank_status`	ranked \| not_ranked	Explicit null-rank meaning

The supported default grid expects 25 rows. A partial completed run can contain fewer; inspect run_data_status and the grid-point counts.

A null business_rank means not found in the observed results, not rank zero.

Raw provider result payloads are not exposed.

Enumerate locations with /organizations, then export one location at a time in windows of at most 31 days.

Follow X-Next-Cursor while X-Has-More is true; nonzero offsets are rejected.

Request

curl -X GET "https://app.cheers.tech/api/public/v1/map-pack-rankings?organization_id=456&from=2026-08-01&to=2026-08-07&limit=500" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "organization_id": 456,
    "keyword": "electric company",
    "run_id": "0787d09e-89a3-4dab-ac2a-cb7927d30aa2",
    "grid_generation": 3,
    "grid_row": 0,
    "grid_col": 0,
    "latitude": 29.7604,
    "longitude": -95.3698,
    "business_rank": 7,
    "rank_status": "ranked",
    "run_data_status": "complete",
    "grid_points_expected": 25,
    "grid_points_succeeded": 25,
    "grid_points_failed": 0
  }
]

GET/ai-visibility

Retrieve daily brand appearance, rank, and citation metrics by location, prompt, and AI platform.

Query Parameters

Parameter	Type	Required	Description
`organization_id`	integer	Optional	Specific location (one of organization_id or parent_organization_id required)
`parent_organization_id`	integer	Optional	Root organization and all permitted descendants
`from`	ISO date or datetime	Optional	First calendar date
`to`	ISO date or datetime	Optional	Last calendar date
`limit`	integer	Optional	Maximum rows, up to 1000
`cursor`	string	Optional	Opaque X-Next-Cursor value from the previous page

Response Fields

Field	Type	Description
`brand_id`	integer \| null	Cheers organization ID for the tracked brand
`brand_name`	string \| null	Tracked brand name
`location_id`	integer	Cheers location organization ID
`location_name`	string \| null	Location name
`date`	date	Metric calendar date
`ai_prompt_id`	string	Tracked prompt ID
`ai_prompt`	string \| null	Tracked prompt text
`ai_platform_id`	string	AI platform/provider identifier
`ai_platform`	string \| null	AI platform/provider name
`data_status`	complete \| partial \| unavailable	Coverage status based on valid observations
`runs`	integer	Valid observations included in the row
`minimum_complete_runs`	integer	Quality threshold for complete status; not the prompt schedule
`appearances`	integer \| null	Observed appearances; null when no valid observations exist
`appearance_rate_pct`	number \| null	Appearance rate reported as a percentage
`avg_rank_when_present`	number \| null	Average rank when the provider supplies a dependable rank
`citations`	integer \| null	Observed citations; null when no valid observations exist
`citation_rate_pct`	number \| null	Citation rate reported as a percentage
`last_updated_at`	datetime	Freshness timestamp

Four or more valid observations are complete, one to three are partial, and zero is unavailable.

minimum_complete_runs is a quality threshold, not the tracked prompt's scheduling cadence.

Unavailable performance fields are null; zero in a partial or complete row is an observed zero.

A null avg_rank_when_present is intentional for platforms that do not provide a dependable numbered rank.

Use the X-Next-Cursor response header for scalable pagination; nonzero offsets are rejected.

Request

curl -X GET "https://app.cheers.tech/api/public/v1/ai-visibility?parent_organization_id=123&from=2026-08-01&to=2026-08-07&limit=1000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "brand_id": 123,
    "brand_name": "Example Energy",
    "location_id": 456,
    "location_name": "Houston",
    "date": "2026-08-01",
    "ai_prompt_id": "9018cc4f-5170-42b3-9bfd-493d91bf2f81",
    "ai_prompt": "best electricity provider in Houston",
    "ai_platform_id": "chatgpt",
    "ai_platform": "ChatGPT",
    "data_status": "complete",
    "runs": 20,
    "minimum_complete_runs": 4,
    "appearances": 12,
    "appearance_rate_pct": 60,
    "avg_rank_when_present": null,
    "citations": 7,
    "citation_rate_pct": 35,
    "last_updated_at": "2026-08-02T12:00:00.000Z"
  }
]

Error Handling

All endpoints return consistent error responses with appropriate HTTP status codes.

Status Code	Description
`207`	Multi-Status - Batch completed with one or more failed items
`400`	Bad Request - Missing or invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - No access to requested resource
`404`	Not Found - Resource does not exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error
`503`	Service Unavailable - Rate limiter or another required service is unavailable

Error Response Format

{
  "error": "Error message describing the issue"
}

Pagination

For taps and reviews, omit offset to use immutable cursor pagination. Follow the X-Next-Cursor header until X-Has-More is false, then save the final X-Checkpoint for the next incremental run.

Pagination Example

# Start an immutable export (1-999 rows per page)
GET /reviews?parent_organization_id=123&format=v2&limit=500

# Continue the same session; send no other query parameters
GET /reviews?cursor=VALUE_FROM_X_NEXT_CURSOR

# Start the next incremental run after the prior final page commits
GET /reviews?checkpoint=VALUE_FROM_X_CHECKPOINT

Cursor sessions expire after six hours; metadata-only checkpoints expire after seven days. Upsert by record ID and only advance a checkpoint after every page succeeds. Explicit offset is legacy compatibility mode.

Filtering by Date

Use ISO 8601 format for date filtering:

Date Filtering Examples

# Reviews updated in the last 7 days
GET /reviews?organization_id=123&from=2024-06-08T00:00:00Z

# Reviews created in January 2024
GET /reviews?organization_id=123&created_from=2024-01-01T00:00:00Z&created_to=2024-01-31T23:59:59Z

Need Help?

For API support, contact us at info@cheers.tech