The /ratings endpoint records guest star ratings for employees, departments, and outlets. Ratings are used for employee performance analytics, service recovery alerts, and leaderboards.
Create a Rating
POST /v2/ratings
Content-Type: application/json
Authentication is optional. If a valid token is provided, the rating is attributed to the authenticated user.
Request
{
"employeeId": "abc123",
"value": 5,
"propertyId": "prop456",
"organizationId": "org789",
"departmentId": "dept111",
"outletId": "out222",
"guestId": "guest333",
"visitId": "visit444",
"tipId": "tip555",
"source": "kiosk",
"tags": ["friendly", "fast"],
"comment": "Excellent service!",
"environment": "live"
}
Required Fields
| Field | Type | Rules |
|---|---|---|
employeeId | string | Required |
value | integer | Required; must be 1, 2, 3, 4, or 5 |
All other fields are optional but enrich analytics and service recovery detection.
Response
{
"success": true,
"ratingId": "rating_xxxxxxxxxxx",
"rating": {
"ratingId": "rating_xxxxxxxxxxx",
"employeeId": "abc123",
"value": 5,
"source": "kiosk",
"environment": "live"
}
}
Linking Ratings to Tips
When a guest rates and tips in the same session (the standard kiosk flow), link the rating to the tip by including tipId in the rating request. This enables analytics like "tips with rating >= 4" and prevents double-counting in conversion funnel metrics.
Linking Ratings to Visits
Include visitId to link the rating to a hotel stay record. This powers the tipping adoption funnel analytics: what percentage of checked-in guests left a rating or tip.
Query Ratings
GET /v2/ratings?employeeId=abc123&environment=live
Query Parameters
| Parameter | Description |
|---|---|
employeeId | Filter by employee |
departmentId | Filter by department |
propertyId | Filter by property |
organizationId | Filter by organization |
guestId | Filter by guest |
visitId | Filter by visit/stay |
startDate | ISO8601 start of date range |
endDate | ISO8601 end of date range |
limit | Max records (default 100, max 500) |
environment | live / sandbox / demo |
Response
{
"ratings": [
{
"ratingId": "rating_xxxxxxxxxxx",
"employeeId": "abc123",
"value": 5,
"source": "kiosk",
"environment": "live",
"metadata": { "created": "2026-03-25T14:00:00Z" }
}
],
"count": 1,
"avgRating": 5.0
}
The response includes count and avgRating calculated across all results matching the filters (not just the current limit page).
Service Recovery
Ratings with value of 1 or 2 can trigger automatic service recovery alerts for managers, depending on the property's Insights alert configuration. The rating is stored normally regardless of alert configuration.