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 or DELETE /employee-links	500 requests per 60 seconds	Shared per API key across single employee-link provisioning and termination requests.
Bulk POST or DELETE /employee-links	10 batch requests per 60 seconds	Up to 100 items per batch. Items are processed with bounded concurrency of 10 and return per-item results. Bulk calls also consume one slot from the shared 500-request standard bucket.
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). Agent-scoped taps are attributed to the resolved destination 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 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 attributed to the tap. For an agent-scoped card, this is the validated destination organization; otherwise it is the card organization.
`source`	string	Recorded source of the visit
`used`	boolean	Whether the tap resulted in a completed action

For an agent-scoped URL, Cheers resolves and validates destination before inserting the tap. The tap keeps the agent card_id and stores the destination organization_id.

The tap organization is the source of truth for the rest of the link-tree journey; downstream link interactions reuse it.

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. Agent attribution is retained when Cheers can match the review to a recorded journey.

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.

This export preserves canonical provider organization ownership. For agent-by-destination reporting use GET /employee-links/reviews, which requires persisted journey evidence and does not promise DMA-level attribution for unmatched shared-profile reviews.

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. Agent-scoped link-tree interactions reuse the organization saved on the originating tap.

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 attributed to the interaction. For an agent-scoped journey, this is the destination organization saved on the tap.

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 root employee; agent scope reuses one active card across DMA/brand destinations.

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	Active non-ADMIN Cheers organization representing the DMA/brand destination for this request
`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 link tree by default. Agent scope requires linktree; direct remains available for location scope
`card_scope`	location \| agent (body)	Optional	location (default) keeps the existing one-card-per-employee/location behavior; agent reuses one active tenant-root card across destinations
`review_link_id`	integer (body)	Optional	Allowed location or ancestor review link for location-scoped direct mode; omit for agent scope
`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, or stable employee card ID in agent scope
`organization_id`	integer	Target DMA/brand organization used for this link and, in agent scope, this URL's destination
`card_organization_id`	integer \| null	Tenant-root organization that owns the card; returned only in agent scope
`agent_id`	string	Agent identifier supplied in the request
`destination_mode`	string	linktree or direct
`card_scope`	string \| null	agent when the opt-in agent-scoped contract is used
`review_link_id`	integer \| null	Explicit direct review link for a location-scoped direct card; null for agent-scoped link-tree cards
`url`	URL	Complete public card URL. In agent scope, append or use the numeric destination organization ID shown in the URL
`landing_page_url`	URL \| null	Complete Cheers link-tree URL in linktree mode, carrying the same destination in agent scope
`created_employee`	boolean	Whether this request created the employee
`created_link`	boolean	Whether this request created the card/link
`destination`	integer \| null	Numeric target organization ID returned only in agent scope; it is not encoded and does not require decoding
`base_url`	URL \| null	Stable public card tap URL returned only in agent scope; add destination and source parameters per survey

Repeated requests with the same case-insensitive agent_id reuse one root employee. Agent scope creates or reuses one active card owned by the tenant-root organization, regardless of how many DMA/brand destinations are used.

card_scope defaults to location, so existing integrations and cards keep their current behavior. Agent scope is opt-in and never converts or updates a location-scoped card.

In agent scope, organization_id is the initial active non-ADMIN DMA/brand organization. Cheers returns its numeric ID as destination and uses it to select that organization's link tree; no destination code is decoded, generated, or stored as a separate routing record.

Agent destinations must have an explicit BRAND, LOCATION, DEPARTMENT, or SERVICE_AREA type, and the card root must be an active ADMIN organization. Untyped organizations are rejected before provisioning.

Store base_url once per agent. For each survey, set destination to the mapped organization_id and source=survey. The complete URL can be rebuilt without another provisioning call.

Use the returned base_url, not a manually constructed legacy /api/v1/tap URL. Dedicated /api/agent/v1 and /agent/v1 routes stop agent journeys on pre-agent releases during rollback; existing location-card URLs are unchanged.

Employee lookup, batch grouping, and uniqueness use the database lower(btrim(...)) normalization, including Unicode. Preserve the original agent_id rather than implementing client-side case folding.

Cheers validates destination before inserting the tap. Link-tree interactions reuse the organization saved on that tap, so tap and link-interaction exports retain DMA/brand attribution while keeping the agent card_id.

Store the returned base_url, not a redirected URL containing tap. Cheers creates a fresh saved journey at entry; profile, contact, preview and tracking follow-ups must match that card and destination and expire after 24 hours. To select another destination or restart an expired journey, open base_url with the intended destination again. Disabled agent cards or link trees reject follow-ups.

Reviews are attributed to an agent and destination organization only when Cheers can match the review to journey evidence. A shared platform profile without deterministic evidence cannot promise DMA-level review attribution.

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_id may differ to produce destination-specific URLs for the same card.

Bulk processing preserves input order and processes repeated case-insensitive agent_id values sequentially, including across card scopes and destinations. Different agents run with at most 10 items in flight. Send at most 100 items per batch; each item reports its own status and failure.

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 non-ADMIN organization 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
}

One stable card per agent with a DMA/brand destination

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",
    "card_scope": "agent",
    "destination_mode": "linktree"
  }'

Response

{
  "employee_id": "8b194ed6-88a0-4f42-a280-d63ea47b5718",
  "card_id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": 456,
  "card_organization_id": 123,
  "agent_id": "AGENT-0042",
  "card_scope": "agent",
  "destination_mode": "linktree",
  "destination": 456,
  "base_url": "https://app.cheers.tech/api/agent/v1/tap?card-id=550e8400-e29b-41d4-a716-446655440000",
  "review_link_id": null,
  "url": "https://app.cheers.tech/api/agent/v1/tap?card-id=550e8400-e29b-41d4-a716-446655440000&destination=456",
  "landing_page_url": "https://app.cheers.tech/agent/v1?id=550e8400-e29b-41d4-a716-446655440000&destination=456",
  "created_employee": false,
  "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",
        "card_scope": "agent",
        "destination_mode": "linktree"
      },
      {
        "organization_id": 789,
        "agent_id": "AGENT-0042",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "card_scope": "agent",
        "destination_mode": "linktree"
      }
    ]
  }'

Response

{
  "requested": 2,
  "succeeded": 2,
  "failed": 0,
  "created_employee_count": 1,
  "created_link_count": 1,
  "results": [
    { "index": 0, "status": 201, "employee_id": "8b194ed6-88a0-4f42-a280-d63ea47b5718", "card_id": "550e8400-e29b-41d4-a716-446655440000", "destination": 456, "url": "https://app.cheers.tech/api/agent/v1/tap?card-id=550e8400-e29b-41d4-a716-446655440000&destination=456" },
    { "index": 1, "status": 200, "employee_id": "8b194ed6-88a0-4f42-a280-d63ea47b5718", "card_id": "550e8400-e29b-41d4-a716-446655440000", "destination": 789, "url": "https://app.cheers.tech/api/agent/v1/tap?card-id=550e8400-e29b-41d4-a716-446655440000&destination=789" }
  ]
}

GET/employee-links/reviews

Retrieve reviews attributed to one agent card at one destination organization using persisted journey evidence. Canonical provider ownership stays unchanged. This is attribution evidence, not a guarantee that a click caused a review.

Query Parameters

Parameter	Type	Required	Description
`card_id`	UUID	Required	The active agent-scoped card returned by employee-link provisioning.
`organization_id`	integer	Required	The DMA/brand destination, permitted by this API key and within the card's tenant.
`limit`	integer	Optional	Page size, default 100; maximum 1000.
`offset`	integer	Optional	Zero-based offset, default 0. Results are ordered by review creation time and ID, newest first.

Response Fields

Field	Type	Description
`card_id`	UUID	The requested agent card.
`organization_id`	integer	The collection destination; not necessarily the provider-profile owner's organization.
`reviews`	array	Active reviews with destination evidence, including earned_credit, update_credit, update_credit_count, and last_credited_at.
`total`	integer \| null	Total active matching reviews, before pagination.
`lifetime_earned_review_count`	integer	Distinct earned reviews with destination evidence, including provider-removed history. Update-only credit is not added to this count.
`attribution_basis`	string	persisted_destination_evidence. Unmatched reviews are omitted, not assigned to the card's home organization.

100 requests per API key per 60 seconds. Requires agent mode; existing /reviews remains the canonical provider-organization export.

For tap and link-interaction metrics, use the existing organization-scoped exports and group by the same card_id. Review attribution is not verified conversion identity.

Request

curl "https://app.cheers.tech/api/public/v1/employee-links/reviews?card_id=550e8400-e29b-41d4-a716-446655440000&organization_id=456" -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "card_id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": 456,
  "reviews": [],
  "total": 0,
  "limit": 100,
  "offset": 0,
  "lifetime_earned_review_count": 0,
  "attribution_basis": "persisted_destination_evidence"
}

DELETE/employee-links

Terminate one agent or deactivate up to 100 agents. Deactivation is a soft delete: matching cards are marked inactive, and an employee is archived only for an unscoped termination. The endpoint is idempotent and repeating a request returns zero newly deactivated links.

Request Body

Parameter	Type	Required	Description
`items`	termination object[] (body)	Optional	Bulk form containing 1–100 objects with only agent_id and optional organization_id; do not combine with top-level or query selectors
`agent_id`	string (body or query)	Optional	Required for the single-item form; supplied per item in bulk
`organization_id`	integer (body or query)	Optional	Limit deactivation to cards in this organization and keep the employee active elsewhere. Omit to deactivate every card/link and archive the employee; null or empty is invalid in bulk items.

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
`requested`	integer	Number of bulk items requested
`succeeded`	integer	Number of bulk items completed successfully
`failed`	integer	Number of bulk items that failed
`results`	array	Ordered per-item results; unknown agents report 404 employee_not_found and write failures report 500

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

Deletion is soft: employees, cards, links, taps, interactions, reviews, and attribution history are retained; only is_active flags change.

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

If employee archival fails after cards were deactivated, the failed item's result includes those card IDs/counts and employee_archived: false. Retry to finish archival; the bulk total includes known deactivations from partial failures.

DELETE organization_id scopes card ownership, not destination routing. Pass the returned card_organization_id (root for agent scope) to disable root-owned agent cards while preserving the employee and child-location cards. Omit it only for whole-employee termination. A child DMA ID cannot revoke one destination from a shared root card.

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

Bulk items accept only agent_id and optional organization_id. A provided null or empty organization_id, an unknown item field, or top-level/query selectors mixed with items is rejected before any write.

All bulk item shapes and organization authorization are validated before writes. Same case-insensitive agent_id items run sequentially in input order; different agents run with a maximum of 10 in flight.

Bulk responses preserve input order. Full success returns 200; any item failure returns 207 Multi-Status. Successful items remain committed, so retry failed indexes when possible or safely retry the unchanged request.

The bulk deactivated_link_count is the sum of per-item counts and counts only cards newly marked inactive. An employee is archived only by an unscoped item.

The standard 500-request bucket is shared by single POST and DELETE calls; bulk POST and DELETE share the 10-batch-request bucket and each bulk request also consumes one standard slot.

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"]
}

Bulk soft delete (up to 100 agents)

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 '{
    "items": [
      { "agent_id": "AGENT-0042", "organization_id": 456 },
      { "agent_id": "AGENT-0043" },
      { "agent_id": "AGENT-0042", "organization_id": 789 }
    ]
  }'

Response

{
  "requested": 3,
  "succeeded": 2,
  "failed": 1,
  "deactivated_link_count": 2,
  "results": [
    { "index": 0, "status": 200, "agent_id": "AGENT-0042", "organization_id": 456, "deactivated_link_count": 1, "deactivated_card_ids": ["550e8400-e29b-41d4-a716-446655440000"] },
    { "index": 1, "status": 404, "agent_id": "AGENT-0043", "error": "employee_not_found" },
    { "index": 2, "status": 200, "agent_id": "AGENT-0042", "organization_id": 789, "deactivated_link_count": 1, "deactivated_card_ids": ["660e8400-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