--- title: "Reviews API" slug: "reviews-api" updated: 2026-10-21T08:16:19Z published: 2026-10-21T08:16:19Z canonical: "support.carehome.co.uk/reviews-api" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.carehome.co.uk/llms.txt > Use this file to discover all available pages before exploring further. # Reviews API Retrieve your published carehome.co.uk reviews as JSON, so you can import them into your own CMS or a third-party platform. > [!NOTE] > **Who can use it:** the Reviews API is available to Enhanced and Platinum subscribers. You need some technical knowledge to use it. > > > **Permitted use:** import reviews into your own CMS or a third-party platform. Do not use the Reviews API to display reviews on public-facing websites or apps; use our Review Widgets for that. See our [API terms of use](https://www.carehome.co.uk/terms/#api). ## Overview | Method | Endpoint | Returns | | --- | --- | --- | | GET | `/index.cfm/reviews` | Your published reviews, with ratings and replies | | GET | `/index.cfm/reviews/ratings` | Rating categories (`rr_id`), such as Staff or Cleanliness | | GET | `/index.cfm/reviews/stars` | Star values (`rrs_id`), such as Good or Excellent | | GET | `/index.cfm/reviews/connections` | Reviewer connections (`rc_id`), such as Daughter of Resident | Base URL `https://api.carehome.co.uk`. Authentication, errors, support and the other review endpoints (Review Score, certificate, 'Review Us' poster and reviews PDF) are covered in the [Reviews API overview](https://support.carehome.co.uk/docs/reviews-api-overview). ## List reviews ``` GET /index.cfm/reviews ``` Returns every published review for the record your API key belongs to, as a JSON array. There is no pagination; the full list is returned in one response. - **Single setting key:** returns that setting's reviews. - **Group key:** returns reviews for every active setting in the group. Use `id` and `api_key` on each review to see which setting it belongs to. Reviews are ordered by setting, then from oldest to newest. ### Query parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `api_key` | string | Yes | Your API key. | ### Example request ``` curl "https://api.carehome.co.uk/index.cfm/reviews?api_key=YOUR_API_KEY" ``` ### Example response `200 OK`, `Content-Type: application/json`. The values below are illustrative, not a real review. ``` [ { "api_key": "YOUR_API_KEY", "id": 65432100000, "r_id": 1234567, "date": "2026-09-09 07:25:24.6 +00:00", "first_name": "N/A", "last_name": "N/A", "display_name": "Example Reviewer", "email": "", "telephone": "", "description": "Example review text. This is not a real review.", "rc_id": "9", "dateRelatedTo": "2026-08-01", "has_reply": true, "ratings": "10:12,11:12,12:12,13:12,14:12,15:12,16:12,17:12,18:12,19:11,37:12,38:12", "average_rating": "4.92", "archived": 0, "submitted": "2026-09-09 07:25:24.6 +00:00", "first_published": "2026-09-17 11:59:16.1 +00:00", "last_published": "2026-09-17 11:59:16.1 +00:00", "reply": { "name": "Example Name", "position": "Home Manager", "content": "Example reply text.", "date": "2026-09-15 11:59:03.2 +00:00" }, "is_included_in_review_score": true } ] ``` ### Review object | Field | Type | Description | | --- | --- | --- | | `r_id` | integer | Unique ID of the review. | | `id` | integer | ID of the setting the review is for. | | `api_key` | string | API key of the setting the review is for. With a group key, this identifies the individual setting. | | `display_name` | string | The name the reviewer chose to show with their review. | | `description` | string | The review text. | | `rc_id` | string | The reviewer's connection to the setting. Look it up with [List reviewer connections](/docs/reviews-api#list-reviewer-connections). | | `dateRelatedTo` | string | The month the review's experience relates to, as `YYYY-MM-01`. Empty string if not given. | | `ratings` | string | Comma-separated `rr_id:rrs_id` pairs, one per rating category. See [Reading ratings](/docs/reviews-api#reading-ratings). | | `average_rating` | string or null | Average star value across the review's ratings, out of 5, to two decimal places. `null` if there is no rating value. | | `submitted` | string | When the review was submitted. See [Dates](/docs/reviews-api#dates). | | `first_published` | string | When the review was first published. | | `last_published` | string | When the review was most recently published. The same as `first_published` unless the review has been republished, for example after an edit. | | `has_reply` | boolean | `true` if the setting has a published reply to this review. | | `reply` | object or null | The setting's published reply. See [Reply object](/docs/reviews-api#reply-object). `null` when `has_reply` is `false`. | | `is_included_in_review_score` | boolean | `true` if the review counts towards the setting's current Review Score, which uses reviews first published in the last 24 months. | | `archived` | integer | `1` if the review was submitted more than two years ago, otherwise `0`. To decide whether a review still affects the Review Score, use `is_included_in_review_score`, which is based on the publication date. | | `date` | string | When the review was submitted. Same value as `submitted`; kept for existing integrations. | | `first_name` | string | Always `"N/A"`. Kept for existing integrations. | | `last_name` | string | Always `"N/A"`. Kept for existing integrations. | | `email` | string | Always an empty string. Kept for existing integrations. | | `telephone` | string | Always an empty string. Kept for existing integrations. | ### Reply object | Field | Type | Description | | --- | --- | --- | | `name` | string | Name of the person who wrote the reply. | | `position` | string | Their job title. | | `content` | string | The reply text. | | `date` | string | When the reply was written. A reply can be dated before `first_published`, because settings can reply while a review is waiting to be published. | ### Dates All date-times are in UTC, in this format: ``` YYYY-MM-DD hh:mm:ss.f +00:00 2026-09-17 11:59:16.1 +00:00 ``` Convert them to UK time for display if you need to. Some older reviews only have a publication date, so their `first_published` time shows as `00:00:00.0`. ### Reading ratings Each pair in `ratings` is `rr_id:rrs_id`: the rating category, then the star value given. Match them against [List rating categories](/docs/reviews-api#list-rating-categories) and [List star values](/docs/reviews-api#list-star-values). For example, `19:11` means Value for Money (`rr_id` 19) was rated Good (`rrs_id` 11, worth 4 stars). A review has one pair for each rating category its setting type uses, so the number of pairs depends on the setting type. See [List rating categories](/docs/reviews-api#list-rating-categories). ## List rating categories ``` GET /index.cfm/reviews/ratings ``` Returns the rating categories for your setting's type, in display order. The categories differ by setting type, as shown below. With a group key this endpoint returns an empty array (`[]`), because rating categories belong to setting types rather than groups. Use the lists below, or call the endpoint with one of your settings' keys. | Field | Type | Description | | --- | --- | --- | | `rr_id` | integer | Rating category ID, as used in `ratings`. | | `rr_name` | string | Category name. | | `rr_sequence` | integer | Display order. | ### Residential homes, nursing homes and extra care housing Full response, 12 categories: ``` [ { "rr_id": 37, "rr_name": "Overall Experience", "rr_sequence": 1 }, { "rr_id": 14, "rr_name": "Facilities", "rr_sequence": 3 }, { "rr_id": 10, "rr_name": "Care / Support", "rr_sequence": 5 }, { "rr_id": 15, "rr_name": "Cleanliness", "rr_sequence": 6 }, { "rr_id": 38, "rr_name": "Treated with Dignity", "rr_sequence": 7 }, { "rr_id": 16, "rr_name": "Food & Drink", "rr_sequence": 8 }, { "rr_id": 11, "rr_name": "Staff", "rr_sequence": 9 }, { "rr_id": 17, "rr_name": "Activities", "rr_sequence": 10 }, { "rr_id": 12, "rr_name": "Management", "rr_sequence": 11 }, { "rr_id": 18, "rr_name": "Safety / Security", "rr_sequence": 13 }, { "rr_id": 13, "rr_name": "Rooms", "rr_sequence": 14 }, { "rr_id": 19, "rr_name": "Value for Money", "rr_sequence": 15 } ] ``` ### Adult day care centres Full response, 11 categories. The same as above without Rooms (`rr_id` 13): ``` [ { "rr_id": 37, "rr_name": "Overall Experience", "rr_sequence": 1 }, { "rr_id": 14, "rr_name": "Facilities", "rr_sequence": 3 }, { "rr_id": 10, "rr_name": "Care / Support", "rr_sequence": 5 }, { "rr_id": 15, "rr_name": "Cleanliness", "rr_sequence": 6 }, { "rr_id": 38, "rr_name": "Treated with Dignity", "rr_sequence": 7 }, { "rr_id": 16, "rr_name": "Food & Drink", "rr_sequence": 8 }, { "rr_id": 11, "rr_name": "Staff", "rr_sequence": 9 }, { "rr_id": 17, "rr_name": "Activities", "rr_sequence": 10 }, { "rr_id": 12, "rr_name": "Management", "rr_sequence": 11 }, { "rr_id": 18, "rr_name": "Safety / Security", "rr_sequence": 13 }, { "rr_id": 19, "rr_name": "Value for Money", "rr_sequence": 15 } ] ``` ## List star values ``` GET /index.cfm/reviews/stars ``` Returns the possible answers for each rating category. The list is the same for every setting type and for group keys. Full response, 6 values: | Field | Type | Description | | --- | --- | --- | | `rrs_id` | integer | Star value ID, as used in `ratings`. | | `rrs_name` | string | Label shown to the reviewer. | | `rrs_sequence` | integer | Display order. | | `rrs_value` | integer | Number of stars, 1 to 5. Not present for "Don't Know". | ``` [ { "rrs_id": 14, "rrs_name": "Very Poor", "rrs_sequence": 1, "rrs_value": 1 }, { "rrs_id": 13, "rrs_name": "Poor", "rrs_sequence": 2, "rrs_value": 2 }, { "rrs_id": 10, "rrs_name": "Fair", "rrs_sequence": 3, "rrs_value": 3 }, { "rrs_id": 11, "rrs_name": "Good", "rrs_sequence": 4, "rrs_value": 4 }, { "rrs_id": 12, "rrs_name": "Excellent", "rrs_sequence": 5, "rrs_value": 5 }, { "rrs_id": 15, "rrs_name": "Don't Know", "rrs_sequence": 6 } ] ``` ## List reviewer connections ``` GET /index.cfm/reviews/connections ``` Returns every reviewer connection used on carehome.co.uk, in display order. The list is the same for every setting type on the site, and for group keys. | Field | Type | Description | | --- | --- | --- | | `rc_id` | integer | Connection ID. Reviews return it as a string in `rc_id`. | | `rc_name` | string | How the reviewer is connected to the setting. | | `rc_sequence` | integer | Display order. | Full response, 56 connections: ``` [ { "rc_id": 1, "rc_name": "Resident / Service User", "rc_sequence": 1000 }, { "rc_id": 171, "rc_name": "Respite Resident/Service User", "rc_sequence": 1005 }, { "rc_id": 173, "rc_name": "Day Care Service User", "rc_sequence": 1007 }, { "rc_id": 23, "rc_name": "Friend of Resident/Service User", "rc_sequence": 1010 }, { "rc_id": 3, "rc_name": "Brother of Resident/Service User", "rc_sequence": 1040 }, { "rc_id": 4, "rc_name": "Sister of Resident/Service User", "rc_sequence": 1060 }, { "rc_id": 5, "rc_name": "Wife of Resident/Service User", "rc_sequence": 1080 }, { "rc_id": 6, "rc_name": "Husband of Resident/Service User", "rc_sequence": 1100 }, { "rc_id": 114, "rc_name": "Partner of Resident/Service User", "rc_sequence": 1101 }, { "rc_id": 115, "rc_name": "Civil Partner of Resident/Service User", "rc_sequence": 1101 }, { "rc_id": 8, "rc_name": "Son of Resident/Service User", "rc_sequence": 1140 }, { "rc_id": 9, "rc_name": "Daughter of Resident/Service User", "rc_sequence": 1160 }, { "rc_id": 10, "rc_name": "Grandson of Resident/Service User", "rc_sequence": 1180 }, { "rc_id": 11, "rc_name": "Granddaughter of Resident/Service User", "rc_sequence": 1200 }, { "rc_id": 12, "rc_name": "Great-grandson of Resident/Service User", "rc_sequence": 1220 }, { "rc_id": 13, "rc_name": "Great-granddaughter of Resident/Service User", "rc_sequence": 1240 }, { "rc_id": 14, "rc_name": "Nephew of Resident/Service User", "rc_sequence": 1260 }, { "rc_id": 15, "rc_name": "Niece of Resident/Service User", "rc_sequence": 1280 }, { "rc_id": 16, "rc_name": "Great-Nephew of Resident/Service User", "rc_sequence": 1300 }, { "rc_id": 17, "rc_name": "Great-Niece of Resident/Service User", "rc_sequence": 1320 }, { "rc_id": 112, "rc_name": "Great Great-Nephew of Resident/Service User", "rc_sequence": 1321 }, { "rc_id": 113, "rc_name": "Great Great-Niece of Resident/Service User", "rc_sequence": 1322 }, { "rc_id": 18, "rc_name": "Father of Resident/Service User", "rc_sequence": 1340 }, { "rc_id": 19, "rc_name": "Mother of Resident/Service User", "rc_sequence": 1360 }, { "rc_id": 135, "rc_name": "Grandfather of Resident/Service User", "rc_sequence": 1362 }, { "rc_id": 136, "rc_name": "Grandmother of Resident/Service User", "rc_sequence": 1364 }, { "rc_id": 20, "rc_name": "Aunt of Resident/Service User", "rc_sequence": 1380 }, { "rc_id": 21, "rc_name": "Uncle of Resident/Service User", "rc_sequence": 1400 }, { "rc_id": 88, "rc_name": "Son-in-law of Resident/Service User", "rc_sequence": 1410 }, { "rc_id": 90, "rc_name": "Daughter-in-law of Resident/Service User", "rc_sequence": 1411 }, { "rc_id": 91, "rc_name": "Father-in-law of Resident/Service User", "rc_sequence": 1412 }, { "rc_id": 89, "rc_name": "Mother-in-law of Resident/Service User", "rc_sequence": 1413 }, { "rc_id": 98, "rc_name": "Brother-in-law of Resident/Service User", "rc_sequence": 1414 }, { "rc_id": 99, "rc_name": "Sister-in-law of Resident/Service User", "rc_sequence": 1415 }, { "rc_id": 103, "rc_name": "Stepson of Resident/Service User", "rc_sequence": 1416 }, { "rc_id": 104, "rc_name": "Stepdaughter of Resident/Service User", "rc_sequence": 1417 }, { "rc_id": 119, "rc_name": "Stepbrother of Resident/Service User", "rc_sequence": 1418 }, { "rc_id": 120, "rc_name": "Stepsister of Resident/Service User", "rc_sequence": 1419 }, { "rc_id": 131, "rc_name": "Stepfather of Resident/Service User", "rc_sequence": 1420 }, { "rc_id": 132, "rc_name": "Stepmother of Resident/Service User", "rc_sequence": 1421 }, { "rc_id": 7, "rc_name": "Cousin of Resident/Service User", "rc_sequence": 1425 }, { "rc_id": 123, "rc_name": "Widow / Widower", "rc_sequence": 1430 }, { "rc_id": 22, "rc_name": "Relative of Resident/Service User", "rc_sequence": 1435 }, { "rc_id": 129, "rc_name": "Guardian of Resident/Service User", "rc_sequence": 1440 }, { "rc_id": 155, "rc_name": "Godfather of Resident/Service User", "rc_sequence": 1442 }, { "rc_id": 156, "rc_name": "Godmother of Resident/Service User", "rc_sequence": 1444 }, { "rc_id": 157, "rc_name": "Godson of Resident/Service User", "rc_sequence": 1446 }, { "rc_id": 158, "rc_name": "Goddaughter of Resident/Service User", "rc_sequence": 1448 }, { "rc_id": 2, "rc_name": "Power of Attorney of Resident/Service User", "rc_sequence": 1450 }, { "rc_id": 176, "rc_name": "Ex Family Member", "rc_sequence": 1451 }, { "rc_id": 167, "rc_name": "Independent Advocate/Deputyship", "rc_sequence": 1453 }, { "rc_id": 178, "rc_name": "Solicitor of Resident/Service User", "rc_sequence": 1456 }, { "rc_id": 185, "rc_name": "Case Manager", "rc_sequence": 1458 }, { "rc_id": 101, "rc_name": "Regular Volunteer", "rc_sequence": 1460 }, { "rc_id": 174, "rc_name": "Next of Kin", "rc_sequence": 1461 }, { "rc_id": 189, "rc_name": "Care home staff", "rc_sequence": 1651 } ] ``` ## Caching Responses include an `ETag` header. Send it back in an `If-None-Match` header; if your reviews have not changed you get `304 Not Modified` with no body, and you can keep using your stored copy. Reviews are added through moderation, not in real time. Polling once an hour or less often is enough.