Skip to main content

Reviews for a Single Location

Endpoint​

POSThttps://api1.consumerism.pressganey.com/api/external/bsr/v2/reviews

Header Parameters​

PropertyTypeDescriptionRequired/Optional
Content-Typeapplication/jsonContent in JSON formatRequired
Access-TokenStringAccess token received from the platformRequired

POST Request Parameters​

PropertyTypeDescriptionRequired/Optional
locationIdStringUnique identifier of a Location. You can get this identifier in mapping fileRequired
perPageIntegerThe number of reviews per pageOptional, default is up to 20
minThresholdStringMinimum threshold for the comments Values between 0 and 5 Note: Minimum threshold is compared to the overall rating value associated with the commentsOptional, by default threshold is not considered
daysIntegerMaximum age of the reviews in days. For example, days=7 means reviews from the past 1 weekOptional, default is 365 days
minSurveyCountIntegerReturns responses only when there are at least as many survey responses as specified in minSurveyCountOptional, default is 0
minRatingCountIntegerReturns responses only when there are at least as many ratings as specified in minRatingCount.Optional, default is 0
minWordCountIntegerReturns only those reviews, which have minimum number of words in it.Default is 0, meaning, no restriction on word count
showRatingsBooleanIf you don't need rating, send this parameter as falseDefault is true
showReviewsBooleanIf you don't need comments, send this parameter as falseDefault is true
scrollKeyStringThe encrypted key to scroll to the next page, call the API with scroll key to get next pageDefault is empty
additionalFieldsList<String>List of string which specifies the additional fields needed in the API response. See Additional fields.Optional

Additional fields​

Following are the additional fields we support. Pass one or more of them in additionalFields (for example, ["reviewSummary", "firstName"]) and the corresponding fields will be returned in the response.

PropertyTypeDescriptionRequired/Optional
reviewSummaryStringAPI will return an AI generated summary of comments for a provider or location. These summaries reference the last 90 days of published comments. The minimum comment limit is 5. See Review summary format.Optional
firstNameStringAPI will return the respondent's first name on each review, when the survey collected it and the response is approved. Omitted from the review when no name is available.Optional
lastInitialStringAPI will return the uppercase first letter of the respondent's last name on each review, when the survey collected it and the response is approved. Omitted from the review when no name is available.Optional
Review summary format​

To receive the AI summary, include "reviewSummary" in the additionalFields array of the request:

"additionalFields": ["reviewSummary"]

The summary is returned as a single string in entities[].reviewSummary. It contains exactly three paragraphs separated by a blank line (\n\n), and no headings or labels:

ParagraphIndex (0-based)Content
10Key positive points and strengths patients mentioned, focused on the most commonly praised aspects.
21Main opportunities for improvement raised in the reviews.
32Overall summary of the patient experience and a high-level takeaway of how patients feel about their care.

The API always returns the full three-paragraph text. To use an individual paragraph, split the string on \n\n:

const parts = entity.reviewSummary ? entity.reviewSummary.split('\n\n') : [];
const [positives, improvements, overall] = parts;
note
  • If reviewSummary is not requested, the field is null.
  • If it is requested but no summary is available for the entity (for example, too few recent comments), the field is an empty string (""). Check for this before splitting.
  • Paragraph order is stable, but guard against fewer than three paragraphs (for example, parts.length >= 3) rather than assuming they are all present.

JSON Response​

A JSON object containing the latest comments.

{
"status": {
"message": "SUCCESS",
"code": 200
},
"data": {
"client": "Demo",
"entities": [
{
"id": "Demo Location",
"name": "Demo Location Name",
"reviewSummary":"The reviews highlighted several positive points about the healthcare provider. Patients felt the doctor was professional, caring, a good listener, and took time to understand their concerns. Multiple patients were very happy with their treatment and grateful for the care they received. However, one patient had an unsatisfactory experience feeling the doctor seemed annoyed, rushed, and uncaring about their condition. This highlights an opportunity for the provider to improve patient interactions by showing more empathy, fully listening to patient concerns, and taking whatever time is needed, regardless of schedule constraints. Additionally, the cost of prescriptions should be considered to provide affordable treatment options. Overall most patients reported very positive experiences feeling heard, understood, and effectively treated. But the one negative review shows room for improving patient interactions and affordability of care. Addressing those factors could help create consistently positive experiences for all patients.",
"totalCommentCount": 5,
"totalRatingCount": 11,
"totalSurveyCount": 11,
"overallRating": {
"name": "Overall Satisfaction",
"value": 4.7,
"categoryResponseCount": 4,
"questionRatings": [
{
"name": "The doctor's interest in, and attention to, my problem?",
"value": 4.4,
"responseCount": 4
},
{
"name": "The thoroughness of the doctor's examination?",
"value": 4.6,
"responseCount": 3
},
{
"name": "Overall satisfaction with my doctor this visit?",
"value": 5.0,
"responseCount": 3
},
{
"name": "The doctor's explanation of my problems(s) and the need for additional tests and treatment?",
"value": 5.0,
"responseCount": 3
}
]
},
"reviews": [
{
"documentId": 3840508,
"surveyKey": "42c59691-adfd-44f2-aeff-e91fcb3d040c",
"source": "Demo Source",
"mentionTime": "2020-11-29T06:13:01Z",
"comment": {
"commentId": 12552895,
"wordCount": 4,
"comment": "Great doctor and staff"
},
"ratings": [
{
"name": "Scheduling",
"value": 3.75
}
],
"overallRating": {
"name": "Overall Satisfaction",
"value": 3.75
}
},
{
"documentId": 3840516,
"surveyKey": "04b47591-db9a-4349-8070-3aa2d0e01a7e",
"source": "Demo Source",
"mentionTime": "2020-11-18T12:20:08Z",
"comment": {
"commentId": 12552985,
"wordCount": 1,
"comment": "excellent"
},
"ratings": [
{
"name": "Scheduling",
"value": 3.75
},
{
"name": "staff",
"value": 3.75
},
{
"name": "Clean",
"value": 5.0
}
],
"overallRating": {
"name": "Overall Satisfaction",
"value": 4.38
}
},
{
"documentId": 3840514,
"surveyKey": "3d4c3921-4bb6-4fca-829d-7f9b77082f0d",
"source": "Demo Source",
"mentionTime": "2020-11-10T12:20:08Z",
"comment": {
"commentId": 12552921,
"wordCount": 1,
"comment": "great"
},
"ratings": [
{
"name": "Scheduling",
"value": 5.0
},
{
"name": "staff",
"value": 5.0
},
{
"name": "Clean",
"value": 5.0
}
],
"overallRating": {
"name": "Overall Satisfaction",
"value": 5.0
}
},
{
"documentId": 3807834,
"surveyKey": "7c1eceed-398a-4d9f-8455-0e3da1cba124",
"source": "Demo Source",
"mentionTime": "2020-09-24T13:11:12Z",
"comment": {
"commentId": 12552785,
"wordCount": 7,
"comment": "Test web survey on 24th Sep 2020"
},
"ratings": [
{
"name": "Scheduling",
"value": 5.0
},
{
"name": "staff",
"value": 5.0
},
{
"name": "Clean",
"value": 5.0
}
],
"overallRating": {
"name": "Overall Satisfaction",
"value": 5.0
}
},
{
"documentId": 3807834,
"surveyKey": "7c1eceed-398a-4d9f-8455-0e3da1cba124",
"source": "Demo Source",
"mentionTime": "2020-09-24T13:11:12Z",
"comment": {
"commentId": 12552786,
"wordCount": 7,
"comment": "Test Web Survey on 24th 09 2020"
},
"ratings": [
{
"name": "Scheduling",
"value": 5.0
},
{
"name": "staff",
"value": 5.0
},
{
"name": "Clean",
"value": 5.0
}
],
"overallRating": {
"name": "Overall Satisfaction",
"value": 5.0
}
}
],
"ratings": [
{
"name": "Scheduling",
"value": 4.4,
"categoryResponseCount": 4,
"questionRatings": [
{
"name": "The doctor's interest in, and attention to, my problem?",
"value": 4.4,
"responseCount": 4
}
]
},
{
"name": "staff",
"value": 4.6,
"categoryResponseCount": 3,
"questionRatings": [
{
"name": "The thoroughness of the doctor's examination?",
"value": 4.6,
"responseCount": 3
}
]
},
{
"name": "Clean",
"value": 5.0,
"categoryResponseCount": 3,
"questionRatings": [
{
"name": "The doctor's explanation of my problems(s) and the need for additional tests and treatment?",
"value": 5.0,
"responseCount": 3
}
]
}
]
}
],
"filter": {
"clientId": "Demo",
"entityId": 580714,
"scrollKey": "6bd9041e37b675273ff3da2de6cb2c10c4e7703a30f084b78d07d9bc0b6720a0",
"person": true,
"reqFromDate": null,
"reqToDate": null,
"days": 365,
"minThreshold": 0.0,
"minRatingCount": 0,
"minSurveyCount": 0,
"minWordCount": 0,
"showComments": true,
"showRatings": true,
"showToneCategory": false,
"showVarName": false,
"pgVendor": false,
"page": 0,
"perPage": 20,
"startPageIndex": -1,
"configVersion": "v2",
"sourceProductId": 1
}
}
}

JSON Response Tags​

PropertyTypeDescription
filterObjectThe filters applied on the testimonials
entitiesArrayThe physician entities for which data is being returned
entities.idStringUnique identifier of the entity
entities.NameStringThe name of the entity
entities.reviewSummaryStringFull AI summary: three paragraphs separated by \n\n. See Review summary format.
entities.totalRatingCountIntegerTotal number of survey responses available for primary rating.
entities.totalCommentCountIntegerNumber of actual comments available for the entity
entities.totalSurveyCountIntegerTotal number of surveys available for the entity
overallRating.nameStringOverall Rating name
overallRating.valueDecimalOverall rating of the Provider
overallRating.questionRatingsArrayIndividual question level rating which contributed for the overall rating
overallRating.questionRatings.nameStringQuestion name contributed for overall rating
overallRating.questionRatings.valueDecimalStar rating of the question
overallRating.questionRatings.responseCountIntegerNo. of responses received for this questiong
ratingsArrayThe ratings for this entity
ratings.nameStringThe name of the rating
ratings.valueDecimalThe score
ratings.questionRatingsArrayList of questions used for calculating this rating
ratings.questionRatings.nameStringQuestion text
ratings.questionRatings.valueDecimalQuestion rating
ratings.questionRatings.responseCountIntegerTotal number of responses for this question
reviewsArrayThe reviews for this entity
reviews.documentIdIntegerUnique identifier of the review
reviews.surveyKeyStringThe sessionkey for the review
reviews.sourceStringThe source for the review
reviews.mentionTimeDatetime (ISO-8601)The date & time at which this review was mentioned
reviews.overallRatingObjectOverall rating of the comment
reviews.overallRating.nameStringOverall rating name
reviews.overallRating.valueDecimalOverall rating of the comment
reviews.ratingsArrayIndividual ratings
reviews.ratings.nameStringThe name of the rating
reviews.ratings.valueDecimalIndividual question rating
reviews.commentObjectComment of the review
reviews.comment.commentIdIntegerUnique identified for the comment
reviews.comment.wordCountIntegerNumber of words in the comment
reviews.comment.commentStringThe comment content
reviews.firstNameStringRespondent's first name. Present only when requested in additionalFields and a name is available
reviews.lastInitialStringFirst letter of the respondent's last name. Present only when requested in additionalFields and a name is available