{"openapi":"3.1.0","info":{"title":"Cheers Public API (legacy snapshot)","version":"1.0.0","description":"Legacy, partial marketing-site snapshot retained for existing consumers. This specification is no longer maintained and is not the current API contract. See https://app.cheers.tech/docs for current endpoints, fields, pagination, permissions, and rate limits.","x-legacy-snapshot":true},"servers":[{"url":"https://app.cheers.tech/api/public/v1"}],"externalDocs":{"description":"Current Cheers API documentation","url":"https://app.cheers.tech/docs"},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key"}}},"paths":{"/organizations":{"get":{"operationId":"organizations","summary":"Organizations","description":"Retrieve organization details.","tags":["Cheers Public API"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"organization_id","in":"query","required":false,"description":"Specific organization ID (one of organization_id or parent_organization_id required)","schema":{"type":"integer"}},{"name":"parent_organization_id","in":"query","required":false,"description":"Get all child organizations (one of organization_id or parent_organization_id required)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Organization ID"},"name":{"type":"string","description":"Organization name"},"created_at":{"type":"string","format":"date-time","description":"When the organization was created"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"subscription_tier":{"type":"string","description":"Subscription level"},"parent_organization_id":{"type":"integer","description":"Parent organization ID (null if root)"}}}},"example":[{"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}]}}},"400":{"description":"Missing or invalid parameters"},"401":{"description":"Invalid or missing API key"},"403":{"description":"No access to requested resource"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error"}}}},"/organization-connections":{"get":{"operationId":"organizationConnections","summary":"Organization Connections","description":"Retrieve platform connections for organizations (Google, Yelp, Facebook, etc.).","tags":["Cheers Public API"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"organization_id","in":"query","required":false,"description":"Specific organization ID (one of organization_id or parent_organization_id required)","schema":{"type":"integer"}},{"name":"parent_organization_id","in":"query","required":false,"description":"Get connections for all child organizations (one of organization_id or parent_organization_id required)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"organization_id":{"type":"integer","description":"Organization ID"},"google_place_id":{"type":"string","description":"Google Places ID"},"google_account_id":{"type":"string","description":"Google My Business account ID"},"google_location_id":{"type":"string","description":"Google My Business location ID"},"yelp_business_id":{"type":"string","description":"Yelp business ID"},"tripadvisor_location_id":{"type":"string","description":"TripAdvisor location ID"},"facebook_page_id":{"type":"string","description":"Facebook page ID"},"facebook_url":{"type":"string","description":"Facebook page URL"},"trustpilot_company_website":{"type":"string","description":"Trustpilot company identifier"},"bbb_profile_url":{"type":"string","description":"Better Business Bureau profile URL"},"created_at":{"type":"string","format":"date-time","description":"When the connection was created"}}}},"example":[{"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"}]}}},"400":{"description":"Missing or invalid parameters"},"401":{"description":"Invalid or missing API key"},"403":{"description":"No access to requested resource"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error"}}}},"/cards":{"get":{"operationId":"cardsGet","summary":"Cards (Badges) - List","description":"Retrieve badge/card information for your organization.","tags":["Cheers Public API"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"organization_id","in":"query","required":false,"description":"Specific organization ID (one of organization_id or parent_organization_id required)","schema":{"type":"integer"}},{"name":"parent_organization_id","in":"query","required":false,"description":"Get cards for all child organizations (one of organization_id or parent_organization_id required)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique card identifier"},"created_at":{"type":"string","format":"date-time","description":"When the card was created"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"cardholder_name":{"type":"string","description":"Name of the badge holder"},"organization_id":{"type":"integer","description":"Organization ID"},"title":{"type":"string","description":"Badge holder's title/position"},"photo_url":{"type":"string","description":"URL to badge holder's photo"},"encode_url":{"type":"string","description":"Encoded URL for the badge"},"linktree_enabled":{"type":"boolean","description":"Whether linktree is enabled for this card"},"badge_number":{"type":"string","description":"Custom badge identifier"}}}},"example":[{"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"}]}}},"400":{"description":"Missing or invalid parameters"},"401":{"description":"Invalid or missing API key"},"403":{"description":"No access to requested resource"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error"}}},"patch":{"operationId":"cardsPatch","summary":"Cards (Badges) - Update","description":"Update a card's organization assignment.","tags":["Cheers Public API"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cardId":{"type":"string","description":"Card UUID to update (one of cardId or badge_number required)"},"badge_number":{"type":"string","description":"Badge number for bulk update (one of cardId or badge_number required)"},"organization_id":{"type":"integer","description":"Target organization ID"}},"required":["organization_id"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"400":{"description":"Missing or invalid parameters"},"401":{"description":"Invalid or missing API key"},"403":{"description":"No access to requested resource"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error"}}}},"/taps":{"get":{"operationId":"taps","summary":"Taps","description":"Retrieve tap events (when a customer taps a badge).","tags":["Cheers Public API"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"organization_id","in":"query","required":false,"description":"Specific organization ID (one of organization_id or parent_organization_id required)","schema":{"type":"integer"}},{"name":"parent_organization_id","in":"query","required":false,"description":"Get taps for all child organizations (one of organization_id or parent_organization_id required)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Tap ID"},"created_at":{"type":"string","format":"date-time","description":"When the tap occurred"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"card_id":{"type":"string","format":"uuid","description":"Associated card ID"},"organization_id":{"type":"integer","description":"Organization ID"},"used":{"type":"boolean","description":"Whether the tap resulted in a completed action"}}}},"example":[{"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}]}}},"400":{"description":"Missing or invalid parameters"},"401":{"description":"Invalid or missing API key"},"403":{"description":"No access to requested resource"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error"}}}},"/reviews":{"get":{"operationId":"reviews","summary":"Reviews","description":"Retrieve customer reviews from all connected platforms.","tags":["Cheers Public API"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"organization_id","in":"query","required":false,"description":"Specific organization ID (one of organization_id or parent_organization_id required)","schema":{"type":"integer"}},{"name":"parent_organization_id","in":"query","required":false,"description":"Get reviews for all child organizations (one of organization_id or parent_organization_id required)","schema":{"type":"integer"}},{"name":"format","in":"query","required":false,"description":"Use \"v2\" or \"new\" for full response fields","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Review ID"},"created_at":{"type":"string","format":"date-time","description":"When the review was received"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"rating":{"type":"integer","description":"Rating value (1-5)"},"card_id":{"type":"string","description":"Associated card ID (if attributed)"},"review_text":{"type":"string","description":"Full review text"},"organization_id":{"type":"integer","description":"Organization ID"},"source":{"type":"string","description":"Platform source (GOOGLE, YELP, FACEBOOK, etc.)"},"reviewer_name":{"type":"string","description":"Reviewer's display name"},"reviewer_photo_url":{"type":"string","description":"Reviewer's profile photo"},"owner_response":{"type":"string","description":"Business owner's response"},"response_timestamp":{"type":"string","format":"date-time","description":"When the response was posted"},"review_url":{"type":"string","description":"Direct link to the review"},"internal":{"type":"boolean","description":"Whether this is an internal Cheers review"}}}},"example":[{"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}]}}},"400":{"description":"Missing or invalid parameters"},"401":{"description":"Invalid or missing API key"},"403":{"description":"No access to requested resource"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error"}}}},"/links":{"get":{"operationId":"links","summary":"Links","description":"Retrieve review links configured for your organization.","tags":["Cheers Public API"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"organization_id","in":"query","required":false,"description":"Specific organization ID (one of organization_id or parent_organization_id required)","schema":{"type":"integer"}},{"name":"parent_organization_id","in":"query","required":false,"description":"Get links for all child organizations (one of organization_id or parent_organization_id required)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Link ID"},"created_at":{"type":"string","format":"date-time","description":"When the link was created"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"url":{"type":"string","description":"Review link URL"},"organization_id":{"type":"integer","description":"Organization ID"},"name":{"type":"string","description":"Display name for the link"},"sms_template":{"type":"string","description":"SMS template text"},"is_verify":{"type":"boolean","description":"Whether this is a verification link"}}}},"example":[{"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}]}}},"400":{"description":"Missing or invalid parameters"},"401":{"description":"Invalid or missing API key"},"403":{"description":"No access to requested resource"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error"}}}},"/link_interactions":{"get":{"operationId":"linkInteractions","summary":"Link Interactions","description":"Retrieve link click/interaction events.","tags":["Cheers Public API"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"organization_id","in":"query","required":false,"description":"Specific organization ID (one of organization_id or parent_organization_id required)","schema":{"type":"integer"}},{"name":"parent_organization_id","in":"query","required":false,"description":"Get interactions for all child organizations (one of organization_id or parent_organization_id required)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Interaction ID"},"link_id":{"type":"integer","description":"Associated link ID"},"card_id":{"type":"string","format":"uuid","description":"Associated card ID"},"created_at":{"type":"string","format":"date-time","description":"When the interaction occurred"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"used":{"type":"boolean","description":"Whether the interaction was completed"},"organization_id":{"type":"integer","description":"Organization ID"}}}},"example":[{"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}]}}},"400":{"description":"Missing or invalid parameters"},"401":{"description":"Invalid or missing API key"},"403":{"description":"No access to requested resource"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error"}}}}}}