Access Token API

Create new Access Token

This API call returns a new access token.

Endpoint

POST https://api1.consumerism.pressganey.com/api/service/v1/token/create

Request Parameters

Parameter	Default	Description	Required/Optional
appId	String	Application ID of the Application that was created to access the API	Required
appSecret	String	Application Secret. Keep this info secret because it acts as the password	Required

Response

The call returns a JSON object which contains an access token and its expiry time. This access token is required to retrieve data using the REST API.

{
  "accessToken": "Wz78OmgKtowHppizWjxO7mqms7+8q1QfjaQfb9WUBooVI6IZmp5V/w==",
  "status": {
    "message": "Success",
    "code": 200,
  },
  "expiresIn": "2014-08-22 09:11:20"
}

Response Parameters

Property	Type	Description
status	JSON Object	Indicates the status of the response
code	Number	Status code for the response. Possible codes are: 200 – Success 400 – Bad Request 500 – Internal Server Error
message	String	Detailed message from the server about the status
accessToken	String	Access token for authentication. This access token is valid until the expiry time indicated in the response
expiresIn	String	Date time when the access token will expire

Provider/Location Avatar List API

Introduction

The API provides the Avatar information like location/person name, code, parentid, avatarHierarchy starting with parent to child hierarchy names for the Brand , Business Unit , Hospital as Type. To access avatar we have to get token (Refer Access Token API Guide).Get the token and pass as query param for the access avatar service.

Endpoint

GET https://api1.consumerism.pressganey.com/api/service/v1/access/avatars

Header Parameters

Property	Type	Description	Required/Optional
Content-Type	application/json	Content in JSON format	Required

Query Parameters

Property	Type	Description	Required/Optional
appId	String	Application ID of the Application that was created to access the API	Required
accessToken	String	Access token for authentication. This access token is valid until the expiry time indicated in the response.	Required
type	String	Type for which avatar details needed like Hospital , Brand	Required

JSON Response

A JSON object containing the latest comments.

{
    "avatars": [
        {
            "person": {
                "code": "",
                "name": ""
            },
            "name": "Advanced Imaging Centers at Tealbrooke",
            "location": {
                "code": "520820",
                "name": "Advanced Imaging Centers at Tealbrooke",
                "avatarHierarchy": "HCA Healthcare ; Hospital ; National - Hospital ; North Florida - Hospital ; North Central Florida Market - North Florida - Hospital"
            },
            "parentNodeId": 270702,
            "type": "Hospital",
            "nodeId": 866817
        },
        {
            "person": {
                "code": "",
                "name": ""
            },
            "name": "Alaska Regional Hospital",
            "location": {
                "code": "48784",
                "name": "Alaska Regional Hospital",
                "avatarHierarchy": "HCA Healthcare ; Hospital ; National - Hospital ; Mountain - Hospital ; Northwest - Mountain-Hospital"
            },
            "parentNodeId": 1982687,
            "type": "Hospital",
            "nodeId": 72728
        }
    ]
}

JSON Response Tags

Property	Type	Description
avatar	Object	The Avatar access details
person	Object	Person details
Code	String	Person code
name	String	Person Name
location	Object	Location details
Code	String	Location code
name	String	Location Name
avatarHierarchy	String	This gives avatar hierarchy for the location selected.
parentNodeId	String	parent node ID
type	String	It contains the value for which avatar deatails requested for.

Entities API

Entities

The call returns the list of entities available for the specific user.Entities API is applicable to patient feedback score (PFS).

Endpoints

GET https://api1.consumerism.pressganey.com/api/service/v1/access/entities

Header Parameters

Property	Type	Description	Required/Optional
Content-Type	application/json	Content in JSON format	Required

 {
     "entities": [
     {
     "name":  "John Doe",
     "code":  "18963506"
     "type":  "Person"
     },
     {
     "name": "Jane Doe",
     "code":  "18963506"
     "type":  "Person"
     }
    ]
  }

GET Request Parameters

Property	Type	Description	Required/Optional
accessToken	String	Access token received from the platform	Required
type	String	The type of entity – can be either “Person” or “Location”.	Required

Category Benchmark API

Category Benchmark

The call returns the scores for the different operational categories, along with the number of positive, neutral and negative insights for the specific location/person ID combination.

GET Method

Endpoint:

GET https://api1.consumerism.pressganey.com/api/service/v1/sentiment/categoryBenchmark

Header Parameters

Property	Type	Description	Required/Optional
Content-Type	application/json	Content in JSON format	Required

GET Request Parameters

Property	Type	Description	Required/Optional
accessToken	String	Access token received from the platform	Required
fromDate	String	The start date in the ISO 8601 format.	Required
toDate	String	The end date in the ISO 8601 format.	Required
locationId	String	Unique code identifier of a location in the platform.	Either a locationId or a providerId is required.
providerId	String	Unique code identifier of a person. Can be NPI or a proprietary identifier defined by the platform.	Either a locationId or a providerId is required

POST Method

Endpoint:

POST https://api1.consumerism.pressganey.com/api/service/v1/sentiment/categoryBenchmark

Header Parameters

Property	Type	Description	Required/Optional
Content-Type	application/json	Content in JSON format	Required

POST Request Parameters

Property	Type	Description	Required/Optional
accessToken	String	Access token received from the platform	Required
fromDate	String	The start date in the ISO 8601 format.	Required
toDate	String	The end date in the ISO 8601 format.	Required
locationId	String	Unique code identifier of a location in the platform.	Either a locationId or a providerId is required.
providerId	String	Unique code identifier of a person. Can be NPI or a proprietary identifier defined by the platform.	Either a locationId or a providerId is required

Response

A JSON object which contains the scores for the different operational categories, along with the number of positive, neutral and negative insights for the specific location/person ID combination. This interface will allow the user to retrieve for a specific location, a specific physician, or for a physician within a specific location.

{
"data": [
{
}, {
}],
"percentPositive": "100.00",

"percentNeutral": "0.00",

"percentNegative": "0.00",

"score": "5.0",

"id": "4037",

"color": "#00dc00",

"name": "Diagnosis", "reviewCount": 1,

"insights": "1",

"negative": "0",

"positive": "1",

"neutral": "0"

"percentPositive": "100.00",

"percentNeutral": "0.00",

"percentNegative": "0.00",

"score": "5.0",

"id": "4004",

"color": "#00dc00",

"name": "Outcome", "reviewCount": 1,

"insights": "1",

"negative": "0",

"positive": "1",

"neutral": "0"

 "avatar": {

 “name”: Nicole Canada, M.D", "type": "Physician"

 "person": {

 "name": "Nicole Canada, M.D",

 "code": "21537"},

 “location”: {

 "name": "Cooper Family Medical", "code": "21137"},

 },

 "period": {

 "to": "2015-06-17",
 "from": "2012-06-17",
}

Response Parameters

Property	Type	Description
filter	Object	The filters applied on the testimonials
percentPositive	Decimal
percentNeutral	Decimal
percentNegative	Decimal
score	Decimal
id	Integer
color
name	String
insights	Decimal
negative	Decimal
positive	Decimal
avatar.name	String
avatar.type	String
person.name	String
person.code	Integer
location.name	String
location.code	Integer

Engagement Response Rate API

Engagement Response Rate

Returns percentage of engagements for different sources (Facebook, Twitter, etc), for the given node(s).

GET Method

Endpoint:

GET https://api1.consumerism.pressganey.com/api/service/v1/engagements/statistics

Header Parameters

Property	Type	Description	Required/Optional
Content-Type	application/json	Content in JSON format	Required

GET Request Parameters

Property	Type	Description	Required/Optional
accessToken	String	Access token received from the platform .Unique identifier of a node for which data is requested.	Required
node	String	Unique identifier of a node for which data is requested.Multiple node parameter can be used in a single GET.	Required
fromDate	String	Format using UTC timezone) Date (ISO-8601 )	Optional, default is 1
toDate	String	Format using UTC timezone)	Optional
source	String	Without a source parameter. Multiple sources can be provided as source=Facebook&source=Twitter etc OR for calculating response rate.source=Facebook,Twitter etc	Optional, default all sources will be used.

Example: 2014-01-01T00:00:00Z The date up to which the response rate shall be calculated. Example: 2015-01-01T00:00:00Z

The source for which response rate should be calculated. The sources are named by its name like Facebook, Twitter, etc. You can get a complete list of supported sources by calling the API year back from current date.

POST Method

Endpoint:

POST https://api1.consumerism.pressganey.com/api/service/v1/engagements/statistics

Header Parameters

Property	Type	Description	Required/Optional
Content-Type	application/json	Content in JSON format	Required

POST Request Parameters

Property	Type	Description	Required/Optional
accessToken	String	Access token received from the platform .Unique identifier of a node for which data is requested.	Required
node	String	Unique identifier of a node for which data is requested.Multiple node parameter can be used in a single GET.	Required
fromDate	String	Format using UTC timezone) Date (ISO-8601 )	Optional, default is 1
toDate	String	Format using UTC timezone)	Optional
source	String	Without a source parameter. Multiple sources can be provided as source=Facebook&source=Twitter etc OR for calculating response rate.source=Facebook,Twitter etc	Optional, default all sources will be used.

Response

A JSON object containing overall response rate and individual response rate per source for each node.

{
"releaseDate": "2015-01-13", "nodes": [
{
"overallResponseRate": 2.94,
"node": "883", "engagements": [
{
"engagedReviewCount": 33,
"responseRate": 5.62, "source": "Facebook", "totalReviewCount": 587
},
{
"engagedReviewCount": 2,
"responseRate": 0.33, "source": "Twitter", "totalReviewCount": 605
}
],
"name": "John Doe"
},
{
"overallResponseRate": 3.15,
"node": "884", "engagements": [
{
"engagedReviewCount": 4,
"responseRate": 10.26, "source": "Facebook", "totalReviewCount": 39
},
{
"engagedReviewCount": 0,
"responseRate": 0, "source": "Twitter", "totalReviewCount": 88
}
],
"name": "Jane Doe"
}
],
filter": {
"period": {
"to": "2015-01-23T10:31:29Z",
"from": "2014-01-23T00:00:00Z"
},
"configVersion": "v1", "sources": [
{
"name": "Facebook"
},
{
"name": "Twitter"
}
]
},
"version": "v1.0"
}

Response Parameters

Property	Type	Description
filter	Object	The filters applied on the testimonials.
filter.sources	Array	The sources used for calculating response rate. If no sources are provided you will get a complete list of sources.
nodes	Array	The nodes for which data is being returned.
nodes.node	String	Unique identifier of the node.
nodes.name	String	The name of the node.
nodes.overallResponseRate	Decimal	The overall response rate accross the requested sources .
engagements	Array	A JSON array containing response rate per source.
engagements.source	String	The source for which response rate is calculated.
engagements.responseRate	Decimal	The response rate for this source
engagements.totalReviewCount	Integer	The total reviews for this source
engagements.engagedReviewCount	Integer	The number of reviews which are engaged for this source

Star Ratings API

Introduction

The API will return overall star rating and average star rating, source wise for locations and providers. Before using the API, an Application must be provisioned by Press Ganey Consumer Solutions. The Application credentials will be made available in the API settings page of the Binary Health Analytics platform. The Application ID and Application Secret create a unique combination that will be used for authorization in all the API calls. Use the Application ID and Application Secret to receive an Access Token. The access token is needed to start making server to server API calls and is valid for a limited period of time

Star Ratings for Single Location/Physician :

Use GET request to return data for single node.

Endpoint

GET https://api.binaryfountain.com/api/service/v1/starrating

Header Parameters

Property	Type	Description	Required/Optional
Content-Type	application/json	Content in JSON format	Required
Access-Token	String	Access token received from the platform	Required

Request Parameters

Property	Type	Description	Required/Optional
locationId	String	Unique code of a location for which data is requested.	Required – either location or physician is needed as parameter
personId	String	Unique code of a physician for which data is requested.	Required – either location or physician is needed as parameter
fromDate	String	From date in ISO 8601 format	Required
toDate	String	To date in ISO 8601 format	Required

JSON Response

A JSON object containing the latest comments.

{
  "filter": {
    "period": {
      "from": "2020-01-01T00:00:00Z",
      "to": "2020-05-31T00:00:00Z"
    }
  },
  "nodes": {
    "sources": [
      {
        "hasRating": false,
        "overallRating": "--",
        "allTimeFeedbackCount": "--",
        "feedbackCount": 63,
        "avgRating": "--",
        "sourceName": "Instagram Tagged Posts",
        "id": 101351
      },
      {
        "hasRating": true,
        "overallRating": "0.0",
        "allTimeFeedbackCount": "0",
        "feedbackCount": 4,
        "avgRating": "5.0",
        "sourceName": "Google",
        "id": 100171
      }
    ],
    "reviewCount": 1616,
    "person": null,
    "averageRating": 3.1,
    "name": "HCA Healthcare",
    "id": 1175695,
    "type": "Business Unit",
    "parentId": 41730,
    "Location": "HCA Healthcare"
  },
  "version": "v1.0",
  "status": {
    "code": 200,
    "message": "success"
  }
}

JSON Response Tags

Property	Type	Description
filter	Object	The filters applied on the testimonials
nodes	Object	Json Object
Location	String	Location Name
person	String	Person Name
reviewCount	Integer	No. of reviews (for all sources)
averageRating	Double	Average Star rating (for all sources)
name	String	Avatar Name
id	Integer	Avatar id
type	String	Avatar Type
parentId	Integer	Parent Avatar id
sources	JSON Array	Array of node (Sources available for location/person)
sources.overallRating	String	Rating shown on website at time of query
sources.hasRating	Boolean	Whether source has rating or not
sources.allTimeFeedbackCount	String	Total Feedback per source for all time (displayed on website)
sources.feedbackCount	Integer	Feedback records per source for timeframe defined
sources.avgRating	String	Average Star Rating per source for timeframe defined
sources.sourceName	String	Source Name
sources.id	Integer	Source Id

Star Ratings for Multiple Location/Physician :

Use POST request to return data for more than one location or physician.

Endpoint

POST https://api.binaryfountain.com/api/service/v1/starrating

Header Parameters

Property	Type	Description	Required/Optional
Content-Type	application/json	Content in JSON format	Required
Access-Token	String	Access token received from the platform	Required

Request Parameters

Property	Type	Description	Required/Optional
code	Array	Array of location id or person id for which data is requested.	Required
locationId	String	Unique code of a location for which data is requested.	Required – either location or physician is needed as parameter
personId	String	Unique code of a physician for which data is requested.	Required – either location or physician is needed as parameter
fromDate	String	From date in ISO 8601 format	Required
toDate	String	To date in ISO 8601 format	Required

{"code":[{"locationId":"565732"},{"locationId":"1548355"}],"fromDate":"2017-12-26T05:00:00Z","toDate":"2018-12-26T23:59:59Z"}

JSON Response

A JSON object containing the latest comments.

{
    "filter": {
        "period": {
            "from": "2017-12-18T05:00:00Z",
            "to": "2018-12-17T23:59:59Z"
        }
    },
    "nodes": [
        {
            "sources": [
                {
                    "hasRating": false,
                    "overallRating": "--",
                    "allTimeFeedbackCount": "--",
                    "feedbackCount": 15,
                    "avgRating": "--",
                    "sourceName": "No Question",
                    "id": 101110
                }
            ],
            "reviewCount": 15,
            "person": "--",
            "averageRating": 0,
            "name": "Provider Level TNT",
            "id": 1089824,
            "type": "Brand",
            "parentId": 0,
            "Location": "Provider Level TNT"
        }
    ],
    "version": "v1.0",
    "status": {
        "code": 200,
        "message": "success"
    }
}

JSON Response Tags

Property	Type	Description
filter	Object	The filters applied on the testimonials
nodes	Object	Json Object
Location	String	Location Name
person	String	Person Name
reviewCount	Integer	No. of reviews (for all sources)
averageRating	Double	Average Star rating (for all sources)
name	String	Avatar Name
id	Integer	Avatar id
type	String	Avatar Type
parentId	Integer	Parent Avatar id
sources	JSON Array	Array of node (Sources available for location/person)
sources.overallRating	String	Rating shown on website at time of query
sources.hasRating	Boolean	Whether source has rating or not
sources.allTimeFeedbackCount	String	Total Feedback per source for all time (displayed on website)
sources.feedbackCount	Integer	Feedback records per source for timeframe defined
sources.avgRating	String	Average Star Rating per source for timeframe defined
sources.sourceName	String	Source Name
sources.id	Integer	Source Id

HTTP Status Codes

HTTP Status Codes Details

Either one of the Status codes below may come in the response. These codes are useful in debugging errors if any:

Status Code	Type	Message
200	SUCCESS	Success
400	BAD REQUEST	Bad Request. Invalid parameters
500	INTERNAL SERVER ERROR	An internal error occured. Please try again later
401	INVALID APPLICATION	The application ID you have provided is invalid. App ID : xxxxxxx
401	INVALID TOKEN	The token you have provided is invalid. Token : xxxxxxxxxxxxx
401	MALFORMED TOKEN	The token you have provided was malformed. Token : xxxxxxxxxxxxx
401	TOKEN EXPIRED	The token you have provided has expired. Token : xxxxxxxxxxxxx