Skip to main content

Host Reviews

Overview​

This resource represents hosts' Reviews for the guest for a given Booking. Host reviews allow hosts to rate and comment on guests after their stay.

info

States

A Host Review can be in one of two states:

  1. Draft – either an empty shell or a partially-filled review with minimal validation. It can be modified any number of times and is identified by a null submitted_at value.
  2. Submitted – the final, immutable version of the review, identified by a non-null submitted_at value.

Restrictions

  • A Booking can have only one Host Review and it must share the same source as the Booking.
  • Each Host Review can have at most one Review Reply.

Parameters​

NameTypeRead/WriteDescription
accountIntegerReadAccount's ID related to the Host Review
rentalIntegerReadRental's ID related to the Host Review
sourceIntegerReadSource's ID related to the Host Review
replyUUIDReadReply's (ReviewReply)'s ID related to the Host Review
bookingIntegerReadBooking's ID related to the Host Review
idUUIDReadHost Review's ID.
commentTextReadHost Review's comment.
private_commentTextReadPrivate comment from the host (not meant to be exposed publicly).
shareableBooleanReadWhether Host Review is permitted for public use.
is_guest_recommendedBooleanReadWhether the host recommends guest.
criteriaObjectReadGuest ratings in specific criteria.
criteria.cleanlinessObjectReadDetails of given criterion.
criteria.cleanliness.ratingDecimalReadRating of guests' cleanliness
criteria.cleanliness.commentTextReadComment on guests' cleanliness
criteria.communicationObjectReadDetails of given criterion.
criteria.communication.ratingDecimalReadRating of guests' communication
criteria.communication.commentTextReadComment on guests' communication
criteria.respect_house_rulesObjectReadDetails of given criterion.
criteria.respect_house_rules.ratingDecimalReadRating of guests' respect of house rules
criteria.respect_house_rules.commentTextReadComment on guests' respect of house rules
created_atTimeReadHost Review's create time.
updated_atTimeReadHost Review's update time.
submitted_atTimeReadHost Review's submission time. Once filled, no further updates are possible for given object.
expires_atTimeReadHost Review's expiry time. Once that time is passed, submission will no longer be possible.
dismissed_byStringReadWhom the Host Review was dismissed by
dismissal_reasonStringReadThe Reason why the Host Review was dismissed
dismissed_atTimeReadWhen the Host Review was dismissed

List host reviews​

List all host reviews (from host to guest) for a given account(s).

GET /host_reviews
response.json
{
  "links": {
    "host_reviews.source": "https://www.bookingsync.com/api/v3/sources/{host_reviews.source}",
    "host_reviews.booking": "https://www.bookingsync.com/api/v3/bookings/{host_reviews.booking}",
    "host_reviews.rental": "https://www.bookingsync.com/api/v3/rentals/{host_reviews.rental}",
    "host_reviews.account": "https://www.bookingsync.com/api/v3/accounts/{host_reviews.account}",
    "host_reviews.reply": "https://www.bookingsync.com/api/v3/review_replies/{host_reviews.reply}"
  },
  "host_reviews": [
    {
      "links": {
        "account": 111,
        "booking": 222,
        "rental": 333,
        "reply": null,
        "source": 444
      },
      "id": "555-6666-7777-8888-999999999999",
      "comment": "Great guests! They were very respectful of the property and left everything clean and tidy.",
      "private_comment": null,
      "shareable": true,
      "is_guest_recommended": true,
      "criteria": {
        "cleanliness": {
          "rating": "5.0",
          "comment": "Left the property in excellent condition"
        },
        "communication": {
          "rating": "4.5",
          "comment": "Good communication throughout the stay"
        },
        "respect_house_rules": {
          "rating": "5.0",
          "comment": "Followed all house rules perfectly"
        }
      },
      "submitted_at": "2023-12-01T11:00:00Z",
      "expires_at": "2023-12-15T23:59:59Z",
      "created_at": "2023-12-01T11:00:00Z",
      "updated_at": "2023-12-01T11:00:00Z",
      "dismissed_at": null,
      "dismissed_by": null,
      "dismissal_reason": null
    }
  ],
  "meta": {}
}

Get a single host review​

Returns a single host review identified by ID.

GET /host_reviews/:host_review_id
response.json
{
  "links": {
    "host_reviews.source": "https://www.bookingsync.com/api/v3/sources/{host_reviews.source}",
    "host_reviews.booking": "https://www.bookingsync.com/api/v3/bookings/{host_reviews.booking}",
    "host_reviews.rental": "https://www.bookingsync.com/api/v3/rentals/{host_reviews.rental}",
    "host_reviews.account": "https://www.bookingsync.com/api/v3/accounts/{host_reviews.account}",
    "host_reviews.reply": "https://www.bookingsync.com/api/v3/review_replies/{host_reviews.reply}"
  },
  "host_reviews": [
    {
      "links": {
        "account": 111,
        "booking": 222,
        "rental": 333,
        "reply": null,
        "source": 444
      },
      "id": "555-6666-7777-8888-999999999999",
      "comment": "Great guests! They were very respectful of the property and left everything clean and tidy.",
      "private_comment": null,
      "shareable": true,
      "is_guest_recommended": true,
      "criteria": {
        "cleanliness": {
          "rating": "5.0",
          "comment": "Left the property in excellent condition"
        },
        "communication": {
          "rating": "4.5",
          "comment": "Good communication throughout the stay"
        },
        "respect_house_rules": {
          "rating": "5.0",
          "comment": "Followed all house rules perfectly"
        }
      },
      "submitted_at": "2023-12-01T11:00:00Z",
      "expires_at": "2023-12-15T23:59:59Z",
      "created_at": "2023-12-01T11:00:00Z",
      "updated_at": "2023-12-01T11:00:00Z",
      "dismissed_at": null,
      "dismissed_by": null,
      "dismissal_reason": null
    }
  ],
  "meta": {}
}

Create a new host review​

Create submitted host review​

Creates a submitted host review for given booking. Such a host review will be no longer editable and requires all data to be filled (comment, shareable, is_guest_recommended, source_id, submitted_at, all criteria with at least rating).

POST /bookings/:booking_id/host_reviews

Create draft host review​

Creates a draft host review for given booking. Such a host review will be editable until submitted, it requires bare minimum for a successful creation (shareable, source_id)

POST /bookings/:booking_id/host_reviews/draft

Edit draft review​

Submit draft host review​

Submits host review making it final and no longer editable. Apart from shareable and source_id which can be set only during creation, all other attibutes (comment, is_guest_recommended, submitted_at, all criteria with at least rating) are required.

PUT /host_reviews/draft/:host_review_id/submit

Modify draft host review without submitting​

Updates host review attributes without submitting it, thus allowing for further editions. Apart from shareable and source_id which can be set only during creation, all other attibutes are optional.

PUT /host_reviews/draft/:host_review_id