Skip to main content

​
Overview

The Reviews API allows tourists to rate and review their tour experiences, and enables guides to respond to reviews. Reviews include ratings, comments, and engagement metrics like likes and replies.

​
Get All Reviews

curl -X GET "https://api.kinconecta.com/api/reviews" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Endpoint

GET /api/reviews

​
Response

Returns an array of all reviews.
​
reviews
Array<Review>
List of all reviews in the system

​
Get Review by ID

curl -X GET "https://api.kinconecta.com/api/reviews/123" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Endpoint

GET /api/reviews/{id}

​
Path Parameters

​
id
Long
required
The unique identifier of the review to retrieve

​
Response

Returns a single Review object or 404 if not found. See the “Get All Reviews” section above for the full Review object structure.

​
Create Review

curl -X POST "https://api.kinconecta.com/api/reviews" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tripId": 456,
    "tourId": 789,
    "guideId": 101,
    "touristId": 202,
    "rating": 5,
    "comment": "Amazing tour of Barcelona! Carlos was incredibly knowledgeable about Gaudi and made the experience unforgettable."
  }'

​
Endpoint

POST /api/reviews

​
Request Body

​
tripId
Long
required
ID of the trip being reviewed
​
tourId
Long
required
ID of the tour that was taken
​
guideId
Long
required
ID of the guide who led the tour
​
touristId
Long
required
ID of the tourist writing the review
​
rating
Short
required
Star rating from 1 to 5
  • 1: Poor
  • 2: Fair
  • 3: Good
  • 4: Very Good
  • 5: Excellent
​
comment
String
Optional written review comment describing the experience

​
Response

Returns the created Review object with generated fields (id, createdAt, updatedAt, likesCount, repliesCount).

​
Example Response

{
  "id": 123,
  "tripId": 456,
  "tourId": 789,
  "guideId": 101,
  "touristId": 202,
  "rating": 5,
  "comment": "Amazing tour of Barcelona! Carlos was incredibly knowledgeable about Gaudi and made the experience unforgettable.",
  "likesCount": 0,
  "repliesCount": 0,
  "createdAt": "2026-03-10T15:30:00Z",
  "updatedAt": "2026-03-10T15:30:00Z",
  "deletedAt": null
}

​
Update Review

curl -X PUT "https://api.kinconecta.com/api/reviews/123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5,
    "comment": "Updated: Amazing tour of Barcelona! Carlos was incredibly knowledgeable."
  }'

​
Endpoint

PUT /api/reviews/{id}

​
Path Parameters

​
id
Long
required
The unique identifier of the review to update

​
Request Body

Include the fields you want to update. Typically rating and/or comment.
​
rating
Short
Updated star rating (1-5)
​
comment
String
Updated review comment

​
Response

Returns the updated Review object or 404 if not found.

​
Delete Review

curl -X DELETE "https://api.kinconecta.com/api/reviews/123" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Endpoint

DELETE /api/reviews/{id}

​
Path Parameters

​
id
Long
required
The unique identifier of the review to delete

​
Response

Returns 204 No Content on successful deletion (soft delete - sets deletedAt timestamp).

​
Review Replies

Guides can respond to reviews left by tourists. Review replies are managed through a separate endpoint.

​
Get All Review Replies

curl -X GET "https://api.kinconecta.com/api/review-replies" \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/review-replies Returns an array of all review replies.

​
Get Review Reply by ID

curl -X GET "https://api.kinconecta.com/api/review-replies/456" \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/review-replies/{id}

​
Create Review Reply

curl -X POST "https://api.kinconecta.com/api/review-replies" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewId": 123,
    "guideId": 101,
    "message": "Thank you so much for your kind words! It was a pleasure showing you around Barcelona."
  }'
Endpoint: POST /api/review-replies

​
Request Body

​
reviewId
Long
required
ID of the review being replied to
​
guideId
Long
required
ID of the guide writing the reply
​
message
String
required
The reply message content

​
ReviewReply Response Fields

​
id
Long
Unique identifier for the reply
​
reviewId
Long
ID of the parent review
​
guideId
Long
ID of the guide who wrote the reply
​
message
String
The reply message content
​
createdAt
Date
Timestamp when the reply was created
​
updatedAt
Date
Timestamp when the reply was last updated

​
Update Review Reply

Endpoint: PUT /api/review-replies/{id}

​
Delete Review Reply

Endpoint: DELETE /api/review-replies/{id} Returns 204 No Content on successful deletion.

​
Best Practices

​
Review Verification

Only allow tourists to review tours they have actually completed. Verify the trip status before accepting review submissions.

​
Rating Calculations

When displaying guide ratings, calculate the average from all their reviews and display the total review count for credibility.

​
Moderation

Implement content moderation for review comments to prevent spam or inappropriate content.

​
Engagement Metrics

The likesCount and repliesCount fields help surface the most helpful reviews. Consider implementing like functionality and displaying guide replies prominently.

Build docs developers (and LLMs) love

Get started for freeTalk to us