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

{
  "recipientType": "outlet",
  "recipientId": "outlet222",
  "value": 5,
  "guestId": "guest333",
  "visitId": "visit444",
  "source": "kiosk",
  "submissionState": "in_progress",
  "environment": "live"
}

Required Fields

FieldTypeRules
recipientTypestringRequired; employee, outlet, or department
recipientIdstringRequired; ID of that exact destination
valueintegerRequired; must be 1, 2, 3, 4, or 5

The server resolves property, department, and outlet context from the canonical destination. Do not substitute an employee for an outlet or department.

Response

{
  "success": true,
  "ratingId": "rating_xxxxxxxxxxx",
  "feedbackToken": "short_lived_continuation_token",
  "rating": {
    "ratingId": "rating_xxxxxxxxxxx",
    "recipientType": "outlet",
    "recipientId": "outlet222",
    "value": 5,
    "source": "kiosk",
    "submissionState": "in_progress",
    "environment": "live"
  }
}

Update the Same Rating

Webkiosk creates the rating as soon as the guest selects a star. If the guest changes the value, completes the flow, or adds an optional comment, update the same ratingId with the returned token:

PATCH /v2/ratings
Content-Type: application/json

{
  "ratingId": "rating_xxxxxxxxxxx",
  "feedbackToken": "short_lived_continuation_token",
  "value": 5,
  "comment": "The whole team was excellent.",
  "submissionState": "completed"
}

The comment is stored on the rating. Aplauso does not create a separate survey or comment record for this flow.

Linking Ratings to Tips

When a guest rates and tips in the same session, include the ratingId in the tip request. The tip points back to the existing rating; it does not copy the comment or change the canonical destination.

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?recipientType=outlet&recipientId=outlet222&environment=live

Query Parameters

ParameterDescription
recipientType + recipientIdFilter by the exact employee, outlet, or department destination
departmentIdRoll up records in a department
propertyIdFilter by property
organizationIdFilter by organization
guestIdFilter by guest
visitIdFilter by visit/stay
startDateISO8601 start of date range
endDateISO8601 end of date range
limitMax records (default 100, max 500)
environmentlive / sandbox / demo

Response

{
  "ratings": [
    {
      "ratingId": "rating_xxxxxxxxxxx",
      "recipientType": "outlet",
      "recipientId": "outlet222",
      "value": 5,
      "comment": "The whole team was excellent.",
      "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).

Hierarchy filters provide reporting roll-ups. They do not relabel collective ratings as employee ratings.

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.