Cheers Public API

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.

Either cardId or badge_number is required in the request body.

Only cards already assigned to your organization or one of its descendants can be moved.

With cardId, a card already in the target organization returns {"id", "organization_id", "updated": false}.

With badge_number, every matching card you control is moved and the response is {"updated", "updated_count", "updated_ids", "target_organization_id"}.

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.

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.

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 1,000 items and 100 link writes per batch; each item reports its own status and failure. A batch over the write budget returns 400 batch_work_limit_exceeded before any write; it still uses one bulk rate-limit slot, so split batches by the write budget before sending.

For card_scope agent, the agent card does not depend on the destination: the first item for an agent writes it, and later destinations for that agent in the same batch are validated and answered without another write. For an initial sync, one item per agent is enough; build each destination URL from base_url by appending &destination=<organization_id>. Destinations are validated when the link is opened: an organization outside the agent's tenant, inactive, or of an unsupported type shows the inactive-link page instead of redirecting.

If an agent-scope agent's employee or card write fails twice in one batch, its remaining destinations in that batch return the same error without another write attempt. Successful items stay committed, and retrying the failed items or the unchanged request is safe.

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.

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.

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.

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

Google reports each metric on its own delay (Search impressions up to about 10 days). Metrics after Google's latest reported day are null with availability_reason not_yet_reported_by_google; request a range ending earlier for complete totals.

GSC and GA4 facts belong to the organization with the connected property, commonly a BRAND. Other organization/date rows may be placeholders; totals are not automatically attributed to individual locations.

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.

The legacy coverage suffix per_location refers to the returned organization_id, which may be a BRAND; it does not imply organization_type=LOCATION.

Query rows are a top-500 per-organization/day 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.

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.

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.

Points whose provider result was unusable (an out-of-market list, or unverifiable listing identity) are omitted and counted in grid_points_invalid.

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.

organization_id returns one organization only. A brand or root organization owns no location rows, so organization_id=<root> with the default scope is an empty 200 with an X-Warning header that names the request to use instead. For every location, use parent_organization_id=<root>; add scope=all to include brand-wide prompts.

scope defaults to location, so existing integrations keep the same rows. scope=brand adds brand-wide prompts, measured once for the brand. scope=all returns both without double counting: a location prompt is only ever returned as location rows, never as a brand total.

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

Most prompts run once per platform per day, so one daily row usually has runs: 1 and data_status: partial. Partial means thin evidence in that row, not failed collection. For a complete reading, sum runs and appearances over several days (for example a week) and compare the sum of runs with minimum_complete_runs.

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.

Rank and written-answer appearances are separate: a map/place listing can supply a rank even when appearances is zero. The existing avg_rank_when_present field name does not mean the average is filtered to written-answer appearances.

rank_samples counts recorded ranks, not runs or appearances. A known zero remains zero even when runs is zero; an unknown legacy count remains null. Neither a zero count nor a null rank proves that the business was absent or that the platform cannot supply rankings.

data_status describes run coverage, not rank coverage. For a combined rank across compatible rows, weight each non-null avg_rank_when_present by its positive rank_samples count; do not average the row averages equally or replace missing ranks with zero.

Use the X-Next-Cursor response header for scalable pagination; nonzero offsets are rejected. Keep the same scope, organization, dates and limit on every page of one export.

A 503 with a Retry-After header means the query timed out under load after one automatic retry. Wait Retry-After seconds and repeat the same request, with the same cursor.