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=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