Review Export

Introduction

This is an export API which can be used by organizations to extract the data out from our Reputation platform to their own data warehouses. You can call this API on a scheduled basis to extract the delta data from our platform. We are exposing a set of APIs in this bundle which will help you to stay in sync with our platform.

Major data points you can get from this API bundle:

Location details
Provider Details
Ratings
Reviews
Sentiments/Insights derived from patient feedback.
Closing the loop task details (If subscribed)
Engagement details (responses to patient feedback)

There are 4 APIs which organizations can use to export and maintain the exported data

Export Reviews : API which returns all the reviews that came in or where updated after the stated time.
Export Deleted Reviews : API that returns all the reviews that got deleted after the given time. This happens when the Source site remove reviews/ratings, which can happen under specific circumstances.
Source Lookup API : Lookup API which returns all the Sources that you can expect. For eg: Google, Facebook, Yelp, Patient Satisfaction Survey. etc...
Category Lookup API: Lookup API which returns all the categories in the analyzed data.

You can follow this blog post to see more about how to use all these APIs together.

Export Reviews

API returns all PressGaney Reputation social media and survey reviews. This API is designed to be called on a daily cadence with the modifiedTimeFrom parameter changing each day.

This is developed based on a scrolling approach where you can finish the execution, if the number of returned reviews is less than the limit you have passed, so you will receive all data that are modified from modifiedTimeFrom to now().

We suggest updating your database with current time and use that value as modifiedTimeFrom when you trigger the same API tomorrow.

Endpoint

POSThttps://api1.consumerism.pressganey.com/api/reputation/v1/reviews

Header Parameters

Property	Type	Description	Required/Optional
Content-Type	application/json	Content in JSON format	Required
accessToken	String	Access token for authentication.	Required

Basic Request Payload

{
  "modifiedTimeFrom": "2011-01-03T23:59:59.345Z",
  "offset": 0,
  "limit": 1000
}

Enhanced request with additional filters

{
  "sources": [
    100123
  ],
  "modifiedTimeFrom": "2011-01-03T23:59:59.345Z",
  "mentionTimeAfter": "2012-03-03T23:59:59.000Z",
  "mentionTimeBefore":"2012-03-10T23:59:59.000Z",
  "additionalFields": ["brand", "visitRecordId"],
  "offset": 0,
  "limit": 1
}

Request Parameters

Property	Type	Description	Required/Optional
modifiedTimeFrom	String	Expecting a datetime value in ISO 8601 format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. API will return all the reviews that are newly came in/ modified after the given time.	Required
sources	List	List of source ids. If not passed, this will return data for "All sources". Refer Source Lookup API for more details on the possible values .	Optional
mentionTimeAfter	String	This datetime value refers to this time when the user has submitted the review in source site.Expecting a datetime value in ISO 8601 format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`.	Optional
mentionTimeBefore	String	If we are specifying this date , API will pull in reviews before this mentioned date.Expecting a datetime value in ISO 8601 format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`.	Optional
offset	Integer	OffSet Value with the default value of `0`.	Optional
limit	Integer	Limiting the response of reviews min = 1 max = 1000 default value= 1000	Optional
additionalFields	`List<String>`	List of string which specifies the additional fields needed in the API response. See additional fields section for more details.	Optional

Additional fields

Property	Type	Description	Required/Optional
brand	String	API will return the brand under which the reviews is present along with other review details.	Optional
visitRecordId	String	API will return the campaign visit record id associated with the review.	Optional

JSON Response

A JSON object contains all the reviews along with filter details.

{
  "reviews": [
    {
      "id": 110592023,
      "surveyBarCode": null,
      "location": {
        "id": 151390,
        "name": "General Local Medical Center"
      },
      "provider": {
        "id": 153233,
        "name": "Provider Name",
        "npi": "Provider NPI"
      },
      "source": {
        "id": 100123,
        "name": "Source Name"
      },
      "avatar": {
        "id": 2053413,
        "name": "Memorial Medical Health Hospital",
        "type": "Hospital"
      },
      "mentionTime": "2020-08-07T19:30:11.000Z",
      "modifiedTime": "2022-02-16T15:59:05.000Z",
      "rating": 5.0,
      "reviewScore": 5.0,
      "contents": [
        {
          "id": 743416299,
          "question": "Your comments:",
          "response": "Excellent Doctor, very knowledgeable and an extremely nice person!",
          "questionType": "Free Form (Text Area)",
          "noOfSentiments": 4,
          "overallCommentSentiment": {
            "score": 4.2,
            "label": "Very Positive"
          },
          "sentiments": [
            {
              "id": 452279868,
              "reviewId": 110593223,
              "feature": "Sentiment Created for the Feature",
              "opinion": "pleased",
              "score": 5.0,
              "category": "Providers (Physician)",
              "subCategory": "General Feedback for Providers",
              "tonality": "positive"
            }
          ]
        },
        {
          "id": 743416301,
          "question": "Your Name (optional)",
          "response": "Rick Williams",
          "questionType": "Name (Text Field)",
          "noOfSentiments": 0,
          "overallCommentSentiment": {
            "score": 3.5,
            "label": "Positive"
          },
          "sentiments": [

          ]
        }
      ],
      "taskDetails": {
        "id": 1918457,
        "status": "Completed",
        "ownerEmail": "james.marshell@xyz.in",
        "ownerName": "James Marshell",
        "closureComment": "Thank you for the positive feedback! We love seeing great ratings like this."
      },
      "visitRecordId": "id",
      "textAnalytics": null,
      "brand": [
        {
             "id": 784297,
             "name": "Brand Name"
        }
      ],
      "engagement": [
        {
            "engagement": "Thank you for the positive feedback! We love seeing great ratings like this.",
            "engagementTime": "2020-08-17T20:12:39.000Z"
        }
      ]
    }
  ],
  "filter": {
    "clientId": "clientInstanceName",
    "sources": [
      100123
    ],
    "modifiedTimeFrom": "2022-01-01T23:59:59.000Z",
    "mentionTimeAfter": "2012-03-03T23:59:59.000Z",
    "mentionTimeBefore": "2012-03-10T23:59:59.000Z",
    "dateType": "MODIFIED_TIME",
    "offset": 5,
    "limit": 10,
    "additionalFields": [
      "visitRecordId",
      "brand"
    ]
  }
}

JSON Response Tags

Property	Type	Description
reviews	Object	List of all the feedback reviews & their details which are mapped with review based on the filter
reviews.id	Integer	System generated unique Id for a Review
reviews.surveyBarCode	String	Dynamic code generated. If it is a PX Survey, then the surveyBarCode will be equal to PX Survey bar Code
reviews.location	Object	Location details to which the review is mapped with
reviews.location.id	Integer	Unique Id of the Location which location is mapped with, during review creation.
reviews.location.name	String	Name of the Location that review was posted
reviews.provider	Object	Details of the Provider that links to this review
reviews.provider.id	Integer	System generated unique Id of the Provider
reviews.provider.name	String	Name of the Provider
reviews.provider.npi	String	Provider NPI
reviews.source	Object	Source details to which the review is mapped with.
reviews.source.id	Integer	System generated unique Id
reviews.source.name	String	Name of the Source where review has posted
reviews.avatar	Object	Details of the hierarchy object that mapped with this review
reviews.avatar.id	Integer	System generated unique Id of Avatar
reviews.avatar.name	String	Name of the Avatar
reviews.avatar.type	String	Type of Avatar, Possible values such as Brand, Hospital, Location, Physician etc. Refer Appendix for more details.
reviews.mentionTime	String	Time when user posted the review in source site. For surveys, it is the time when survey is submitted. Format: ISO 8601 `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`
reviews.modifiedTime	String	Last Modified Time for review in format: ISO 8601 `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`
reviews.rating	Double	Rating which is considered from source sites like Google, Vitals.com etc. Possible values being from 0 to 5, where 0 being min & 5 being max. In case if sources doesnt have rating option or user did not provide any rating, then by default considered as 0
reviews.reviewScore	Double	A PFS/CSI score calculated between 0.0 to 5.0, where 0.0 being Negative, 5.0 being Positive, 2.5 being Neutral. This is calculated using the equation = `(sum of sentiment scores)/(no. of sentiments)`
reviews.contents	Object	Contents from Social Sites or Survey reviews which are considered for the review activity, which contains the review comments, response for the question, feature, scoring for the sentiments etc
reviews.contents.id	Integer	System generated unique Id for a content
reviews.contents.question	String	Question, which is present under the Content
reviews.contents.response	String	Response for the Content Question
reviews.contents.questionType	String	Type of the question. Possible values are from Dropdown like "Select box", "Text Field" etc. For more info on the possible question types stored in reputation, refer Question Type details table
reviews.contents.questionCode	String	Unique code to identify a Question. If you are using PX surveys, then this code can be used to correlate the data from PX.
reviews.contents.noOfSentiments	Integer	Total number of sentiments identified for this content.
reviews.contents.sentiments	Object	Sentiments Details which are extracted out of this content
reviews.contents.sentiments.id	Integer	System generated unique Id for a sentiment
reviews.contents.sentiments.feature	String	Feature keyword extracted out from this content
reviews.contents.sentiments.opinion	String	Opinion keyword extracted out from this content
reviews.contents.sentiments.score	Double	Sentiment Score calculated based on the opinion, values ranging between 0.0 to 5.0, where 0.0 being Negative, 5.0 being Positive, 2.5 being Neutral
reviews.contents.sentiments.category	String	Category identified by our NLP for this sentiment. You can get all the possible categories in the platform using the Category Lookup API
reviews.contents.sentiments.subCategory	String	More fine tuned category classification.
reviews.contents.sentiments.tonality	String	Tone of the sentiment. Possible values being negative, positive, neutral
reviews.taskDetails	Object	Details of the Task associated with the review if you have Closing the Loop feature enabled.
reviews.taskDetails.id	Integer	System generated unique Id for a Task
reviews.taskDetails.status	String	Status of the task, possible value being 'pending'/'completed' `pending` - Task is Open `completed` - Task is closed and possibly an engagament is happened with the Customer.
reviews.taskDetails.ownerEmail	String	Email id of the user who have taken an action on this review
reviews.taskDetails.ownerName	String	Name of the user who have taken an action on this review
reviews.taskDetails.closureComment	String	Closure comment for a Task
reviews.engagements	List	Details of Engagements happen over a review. This can be an email communication or an online communication depends on the Source
reviews.engagements.engagement	String	Message that has posted/sent to the customer who posted the review
reviews.engagements.engagementTime	String	Time of Engagement
filter	Object	Filter, which contains Input Details
filter.clientId	String	Client Id of your organization in our platform
filter.sources	Object	source ids you have requested. If you haven't provided anything in request, this will return the default source Id we have selected internally.
filter.modifiedTimeFrom	String	modified time you have provided in the request.
filter.mentionTimeAfter	String	Mention time you have provided.If you haven't provided anything in request, this will return the default mention time
filter.mentionTimeBefore	String	Mention time provided in the request.If we are specifying this date , API will pull in reviews before this mentioned date .If you haven't provided anything in request, this will return the default mention time
filter.offset	Integer	Offset Value you have provided
filter.limit	Integer	Limit you have provided
filter.additionalFields	Array	List of string which specifies the additional fields needed in the API response. See additional fields section for more details.
reviews.visitRecordId	String	Campaign visit record id associated with the review. If there is no visit id associated with the document then this field will be an empty string.
reviews.textAnalytics	Object	Text analytic responds from NarrativeDX.
reviews.brand	Array	Node provided the details of the brand to which the review belongs to.
reviews.brand.id	Integer	Avatar id of the brand to which the review belongs to.
reviews.brand.name	String	Name of the brand to which the review belongs to.
reviews.contents.overallCommentSentiment.score	Double	A comment score calculated between 1 to 5.
reviews.contents.overallCommentSentiment.label	String	A comment label based on the comment score. Values will be Extremely Positive, Positive, Neutral, Negative, Extremely Negative.

Note

Please note that attributes tha have value as null will be dropped from the response. Also, new attributes can be added in the API going forward. Please make sure your code is able to handle both cases.

Export Deleted Reviews

Documents associated with a particular location or provider can be removed from a source and from PressGaney’s Reputation product.

Any documents that have been deleted after the user has exported the data using Export Feedback Details, can be requested using this API.

Use this API to keep data up to date by removing the deleted documents from the data already retrieved (using Export Feedback Details).

This endpoint allows fetching of the review documents that have been deleted, based on the filters passed, including sources & modifiedTimeFrom.

Endpoint

POSThttps://api1.consumerism.pressganey.com/api/reputation/v1/deleted-reviews

Header Parameters

Property	Type	Description	Required/Optional
Content-Type	application/json	Content in JSON format	Required
accessToken	String	Access token for authentication.	Required

Default Request Payload

{
  "modifiedTimeFrom": "2011-01-03T23:59:59.345Z",
  "offset": 0,
  "limit": 1000
}

Extended request Payload

{
  "sources": [
    103181
  ],
  "modifiedTimeFrom": "2011-01-03T23:59:59.345Z",
  "offset": 0,
  "limit": 1000
}

Request Parameters

Property	Type	Description	Required/Optional
sources	List	List of source ids. If not passed, this will return data for "All sources". Refer Source Lookup API for more details on the possible values	Optional
modifiedTimeFrom	String	Expecting a datetime value in ISO 8601 format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. API will return all the reviews that are newly came in/ modified after the given time.	Required
offset	Integer	OffSet Value with the default value of `0`	Optional
limit	Integer	Limiting the response of reviews min = 1 max = 1000 default value= 1000	Optional

JSON Response

A JSON object which contains all the deleted documents along with filter inputs.

{
  "reviews": [
    {
      "id": 119593223,
      "modifiedTime": "2022-02-16T15:59:05.000Z"
    }
  ],
  "filter": {
    "clientId": "clientInstanceName",
    "sources": [
      103181
    ],
    "modifiedTimeFrom": "2022-01-01T23:59:59.000Z",
    "offset": 0,
    "limit": 1
  }
}

JSON Response Tags

Property	Type	Description
reviews	Object	List of all the deleted reviews
reviews.id	Integer	Unique Review Id. This is the same as `reviews.id` in the Export Reviews section. You can use this Id to find the review in your data warehouse and delete it.
reviews.modifiedTime	String	Deleted time of review in ISO 8601 format `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`
filter	Object	Filter Details which contains Input Details
filter.clientId	String	Client Id of your organization in our platform
filter.sources	Object	source ids you have requested. If you haven't provided anything in request, this will return the default source Id we have selected internally.
filter.modifiedTimeFrom	String	modified time you have provided in the request.
filter.offset	Integer	Offset Value you have provided
filter.limit	Integer	Limit you have provided

You can follow this blog post to see more about how to use all these APIs together.

Appendix

Avatar Types

Avatar Types
Hospital
Specialty
Other
location
Location
Practice
Apartment
Market
Division
Region
Medical Group
Department
Brand
Physician
Business Unit
practice

Question Types

Question Types
Multiple Choice (Checkbox)
New Patient (Radio)
Instruction
Source Path (Text Field)
Gender (Radio)
Promoter Question (Radio)
Single Choice (Number Slider)
Author ID (Text Field)
Klout ID (Text Field)
Single Choice (Auto Editable)
Job Discription (Text Field)
Age (Text Field)
Job Hire Date (Text Field)
Follower Count (Text Field)
State (Select)
Free From (Text Field)
Screen name (Text Field)
Single Choice (Slider)
Procedure (Radio)
Free From (Text Area)
Free Form (Rating)
Publishing Site Link
Last Name (Text Field)
Promoter (Radio)
Age Group (Select)
Free Form (Text Area)
Zip Code (Text Field)
Single Choice (Auto Complete)
Gender (Text Field)
Location Info (Radio)
Klout Score (Text Field)
Member Since (Text Field)
Ethnicity (Radio)
Demographic Ethnicity (Select)
AvatarLink (Text Field)
Single Choice (Radio)
First Name (Text Field)
Physician (Radio)
Email (Text Field)
Location (Text Field)
Referring Physician (Radio)
Single Choice (Rating)
Single Choice (Combo)
State (Text Field)
Age (Radio)
Publishing Site Links (Radio)
Last Name (Text Field)
Following Count (Text Field)
Email (Text Area)
Name (Text Area)
County (Text Field)
Instructions
Review Count (Text Field)
Name (Text Field)
Completion Date (Date Field)
Phone (Text Field)
Address3 (Text Field)
Location (Radio)
Demographic Language (Select)
Publish (Checkbox)
First Name (Text Field)
Email (Text Field)
Free Form (Text Field)
Friend Count (Text Field)
City (Text Field)
Address2 (Text Field)
Demographic Gender (Select)
Language (Text Field)
Country (Text Field)
Address1 (Text Field)
Job Title (Text Field)

Introduction​

Export Reviews​

Endpoint​

Header Parameters​

Basic Request Payload​

Enhanced request with additional filters​

Request Parameters​

Additional fields​

JSON Response​

JSON Response Tags​

Note​

Export Deleted Reviews​

Endpoint​

Header Parameters​

Default Request Payload​

Extended request Payload​

Request Parameters​

JSON Response​

JSON Response Tags​

Appendix​

Avatar Types​

Question Types​

Introduction

Export Reviews

Endpoint

Header Parameters

Basic Request Payload

Enhanced request with additional filters

Request Parameters

Additional fields

JSON Response

JSON Response Tags

Note

Export Deleted Reviews

Endpoint

Header Parameters

Default Request Payload

Extended request Payload

Request Parameters

JSON Response

JSON Response Tags

Appendix

Avatar Types

Question Types