Developer Reference

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 in the Cheers dashboard or contact your 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: API requests are rate-limited to ensure fair usage. If you exceed the rate limit, you'll receive a 429 Too Many Requests response.

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)
`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)

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
`subscription_tier`	string	Subscription level
`parent_organization_id`	integer	Parent organization ID (null if root)

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",
    "subscription_tier": "pro",
    "parent_organization_id": null
  }
]

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 My Business account ID
`google_location_id`	string	Google My Business 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
`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
`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
`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,
    "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

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

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

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

Error Handling

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

Status Code	Description
`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

Error Response Format

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

Pagination

Use limit and offset parameters to paginate through large result sets.

Pagination Example

# First page (records 0-99)
GET /reviews?organization_id=123&limit=100&offset=0

# Second page (records 100-199)
GET /reviews?organization_id=123&limit=100&offset=100

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=2026-03-17T00:00:00Z

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

Need Help?

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