Skip to main content

Comments for a Single Physician

Endpoint​

GEThttps://api1.consumerism.pressganey.com/api/bsr/comments

Header Parameters​

PropertyTypeDescriptionRequired/Optional
Content-Typeapplication/x-www-form-urlencodedURL Encoded request bodyRequired
Access-TokenStringAccess token received from the platformRequired

GET Request Parameters​

Required Fields​

PropertyTypeDescriptionRequired/Optional
personIdStringUnique identifier of a Physician. Can be NPI or a proprietary identifier guaranteed to be unique across all providersRequired

Optional Request Parameters​

Following parameters are optional fields you can pass to customize the results. You don't have to pass any of these, and we will use the default/industry standard values here.

PropertyTypeDescriptionDefault Value
pageIntegerThe page to return containing the requested number of testimonials per page1
perPageIntegerThe number of reviews per page20
daysIntegerMaximum age of the reviews in days. For example, days=7 means reviews from the past 1 week365
fromDateStringStart timestamp (use fromDate and toDate together and it has precedence over days). Format - ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss'Z')
toDateStringEnd Timestamp (use fromDate and toDate together and it has precedence over days). Format - ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss'Z')
minSurveyCountIntegerReturns responses only when there are at least as many ratings as specified in minRatingCount.0
minRatingCountIntegerReturns responses only when there are at least as many ratings as specified in minRatingCount.30
minWordCountIntegerReturns only those reviews, which have minimum number of words in it.0- meaning, no restriction on word count
showRatingsBooleanIf you don't need rating, send this parameter as falsetrue
showCommentsDefaultIf you don't need comments, send this parameter as falsetrue
additionalFieldsList<String>List of string which specifies the additional fields needed in the API response. See Additional fields.

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 comment, when the survey collected it and the response is approved. Omitted from the comment when no name is available.Optional
lastInitialStringAPI will return the uppercase first letter of the respondent's last name on each comment, when the survey collected it and the response is approved. Omitted from the comment when no name is available.Optional
Survey_languageStringAPI will return the language the respondent took the survey in (for example, EN) on each comment, from the survey's Language question, when the response is approved. Omitted from the comment when no language 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":{
"entities":[
{
"id":"1324567890",
"name":"John Doe, MD",
"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":3,
"totalRatingCount":6,
"totalSurveyCount":6,
"overallRating":{
"name":"Overall Satisfaction",
"value":3.6,
"questionRatings":[
{
"name":"CP instructions for follow-up care",
"value":3.5,
"responseCount":6
},
{
"name":"CP spoke using clear language",
"value":3.3,
"responseCount":6
},
{
"name":"Time CP spent with patient",
"value":3.5,
"responseCount":6
},
{
"name":"Patients' confidence in CP",
"value":4.6,
"responseCount":6
}
]
},
"comments":[
{
"id":6931217,
"source":"Demo survey-PG",
"mentionTime":"2017-01-09T07:12:55Z",
"wordCount":2,
"comment":"Good caring",
"overAllRating":{
"name":"Overall Satisfaction",
"value":4.75
},

"response": {
"responseText": "Sample Annotation Text",
"client": "BF Healthcare",
"respondedBy": "Test User",
"respondedTime": "2017-04-18T14:08:00Z"
}

"ratings":[
{
"name":"Access",
"value":4.38
},
{
"name":"Personal Issues",
"value":4.58
},
{
"name":"Nurse/Assistant",
"value":4.38
},
{
"name":"Overall Assessment",
"value":5
},
{
"name":"Moving through visit",
"value":4.58
}
]
}
],
"totalPages":1,
"ratings":[
{
"name":"Access",
"value":2.8,
"questionRatings":[
{
"name":"Ease of getting clinic on phone",
"value":2.9,
"responseCount":6
}
]
},
{
"name":"Personal Issues",
"value":4,
"questionRatings":[
{
"name":"Convenience of our office hours",
"value":4.6,
"responseCount":6
}
]
},
{
"name":"Nurse/Assistant",
"value":4.2,
"questionRatings":[
{
"name":"Friendliness/courtesy of nurse/asst",
"value":3.8,
"responseCount":6
}
]
},
{
"name":"Overall Assessment",
"value":4.4,
"questionRatings":[
{
"name":"Staff worked together",
"value":4.7,
"responseCount":4
}
]
},
{
"name":"Moving through visit",
"value":4.1,
"questionRatings":[
{
"name":"Courtesy of registration staff",
"value":4.5,
"responseCount":5
}
]
}
]
}
],
"filter":{
"minThreshold":0,
"minRatingCount":30,
"minSurveyCount":0,
"minWordCount":0,
"days":20,
"page":1,
"perPage":20,
"showComments":true,
"showRatings":true,
"configVersion":"v2",
"period":{
"to":"2017-01-10T07:52:08Z",
"from":"2016-12-21T00:00:00Z"
}
}
}
}

JSON Response Parameters​

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