NAV

Introduction

This document serves as a guide to provide the technical understanding to implement Loyal/Transparently provider ratings and comments on a health system website.

We will review the rating and comment components and all implementation options. We will also include example code for each that can be used in your test environment.

At the end of the document, we will include both a dictionary of potentially unfamiliar terms, as well as contact information for our technical support team. Feel free to reach out to us at any point in the process. We’d love to hear from you.

REST API

The Loyal/Transparently HTTP API allows health systems to access their patient review data. It is the best way to develop, design and publish your data within your health system website.

Our API is built on REST principles. Authenticated users can interact with any of our URIs by using the specified HTTP request method.

Endpoint

The API is hosted on the assets or assetsdev subdomain. Please use the following base endpoint for all of your API requests:

Development

https://assetsdev.transparently.com/

Production

Please do not use the production endpoint for testing!

https://assets.transparently.com/

Please note the https protocol used in the URL. All API users are required to use secure HTTP connections. All plain HTTP requests will be forwarded to the corresponding secure endpoints.

Making requests

The API accepts standard HTTP requests. You can pass values to the API via the URL query string or the request body, when required by an endpoint. The request body, if present, is always assumed to be a JSON document. The Content-Type and Acceptheaders are ignored.

Only GET requests are currently allowed. The API will respond with status 403 Forbidden when trying to use a POST or PUT request.

Handling responses

The API relies on HTTP status codes to communicate the status of your request.

The server always encloses a JSON document in the response body. The document format for all successful requests is specific to an endpoint.

Dealing with errors

Whenever an error occurs, the server responds with a non-successful HTTP status code and a JSON document is enclosed in the response body. The document has the following format:

{"message" : "Error description."}

The message field of the returned object contains a human-readable description of the error.

Dealing with Inactive Providers or Providers < 30 surveys

Providers who are either set inactive in the Loyal/Transparently platform or who do not have the adequate amount of surveys will be dealt as available resources but who have no content. We will send back JSON, but you’ll receive a 204 HTTP status code along with a response like this:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "statusCode": 204,
  "statusMessage" : "This provider has no content."
}

You may need to handle 204’s differently based on how your ratings and reviews will be handled.

Provider Totals

Overall ratings for Providers

Get a total by Provider ID

Returns a single JSON object of the Provider, designated from the client’s unique provider ID

GET

/:clientName/totals/:providerId

URL Params (Required):

Example request with cURL:

curl "https://assetsdev.transparently.com/example/totals/4617" -X GET

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  Rating: 4.8,
  RatingCount: 42,
  CommentCount: 117
}

Usage and Examples:

  $.ajax({
    url: "https://assetsdev.transparently.com/example/totals/4617",
    dataType: "json",
    type : "GET",
    success : function(r) {
      console.log(r);
    }
  });

Get a total by NPI

Returns a single JSON object of the Provider, using the Provider’s designated NPI

GET

/:clientName/totals-by-npi/:npi

URL Params (Required):

Example request with cURL:

curl "https://assetsdev.transparently.com/example/totals-by-npi/1558418400" -X GET

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  Rating: 4.8,
  RatingCount: 42,
  CommentCount: 117
}

Usage and Examples:

List of totals by NPI

Post an array of NPIs to the request body. Returns JSON list of Totals based on the providerIds given. Recommend using Postman to send data requests here for testing.

POST

/:clientName/provider-totals-by-npi

URL Params (Required):

Request Body (Required):

Example request with cURL:

curl "https://assetsdev.transparently.com/example/provider-totals-by-npi" \
-H "Content-Type: application/json" \
-X POST -d '{ "npis": [1477584142,1336179589] }'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "Rating": 4.7,
    "RatingCount": 8,
    "CommentCount": 0
  },
  {
    "Rating": 4.8,
    "RatingCount": 68,
    "CommentCount": 110
  }
]

Usage and Examples:

Usage

var postbackObj = {
  "npis": [1477584142,1336179589]
}
$.ajax({
  url: "https://assetsdev.transparently.com/example/provider-totals-by-npi",
  dataType: "json",
  data: postbackObj,
  type : "POST",
  success : function(r) {
    console.log(r);
  }
});

List of totals by Provider Ids

Sometimes health systems use unique client provider id’s instead of NPIs. Post an array of client providerIds to the request body. Returns JSON list of Totals based on the providerIds given. Recommend using Postman to send data requests here for testing.

POST

/:clientName/provider-totals-by-ids

URL Params (Required):

Request Body (Required):

Example request with cURL:

curl "https://assetsdev.transparently.com/example/provider-totals-by-ids" \
-H "Content-Type: application/json" \
-X POST -d '{ "ids": [4617,5879] }'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "Rating": 4.7,
    "RatingCount": 8,
    "CommentCount": 0
  },
  {
    "Rating": 4.8,
    "RatingCount": 68,
    "CommentCount": 110
  }
]

Usage and Examples:

Usage

Provider Subtotals

Subtotals for Providers

Get a subtotal

Returns a JSON array of all the Provider Subtotals

GET

/:clientName/subtotals/:providerId

URL Params (Required):

Example request with cURL:

curl "https://assetsdev.transparently.com/example/subtotals/4617" -X GET

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    RatedSection: "CP1",
    Description: "Friendliness/courtesy",
    Rating: 4.9
  },
  {
    RatedSection: "CP10",
    Description: "Likelihood of recommending to others",
    Rating: 4.9
  },
  {
    RatedSection: "CP2",
    Description: "Explanations about your problem/condition",
    Rating: 4.9
  },
  {
    RatedSection: "CP3",
    Description: "Concern shown for your questions/worries",
    Rating: 4.8
  }
]

Usage and Examples:

Usage

$.ajax({
  url: "https://assetsdev.transparently.com/example/subtotals/4617",
  dataType: "json",
  type : "GET",
  success : function(r) {
    console.log(r);
  }
});

Provider Comments

Comments for Providers

Get a comment

Returns a JSON array of all the Provider Comments plus the overall Totals object

GET

/:clientName/comments/:providerId/:pageNo

URL Params (Required):

Example request with cURL:

curl "https://assetsdev.transparently.com/example/comments/4617/1" -X GET

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  Comments: [
    {
      Rating: 5,
      CommentText: "I was very impressed with the fact that when my situation stumped him, he had the courage to admit it was something he had not experienced before; thus he was still learning new things everyday.",
      SurveyDate: "6/10/2016",
      Tag: ""
    },
    {
      Rating: 5,
      CommentText: "Dr. was very easy to talk to and made me feel at ease.",
      SurveyDate: "6/8/2016",
      Tag: ""
    },
    {
      Rating: 4.1,
      CommentText: "I LIKE THE FACT HE SAT DOWN AND TALKED WITH ME WITHOUT SEEMING RUSHED.",
      SurveyDate: "6/8/2016",
      Tag: ""
    },
    {
      Rating: 5,
      CommentText: "Great dr",
      SurveyDate: "6/3/2016",
      Tag: ""
    },
    {
      Rating: 5,
      CommentText: "Dr was very helpful and kind",
      SurveyDate: "6/3/2016",
      Tag: ""
    }
  ],
  ProviderTotals: {
    Rating: 4.6,
    RatingCount: 377,
    CommentCount: 63
    }
}

Usage and Examples:

Usage

$.ajax({
  url: "https://assetsdev.transparently.com/example/comments/1/4617",
  dataType: "json",
  type : "GET",
  success : function(r) {
    console.log(r);
  }
});

SOAP API

Use our SOAP API to retrieve SEO critical information regarding your Loyal/Transparently data. Currently we support only the Provider Totals subset. Use SOAP API in any language that supports Web Services.

Provider Totals

A SOAP web service endpoint will provide the necessary HTML and CSS for server side rendering of the provider total rating.

Get a total

GET

Web Service Endpoint:

http://clientapi.transparently.com/webservices/providerratings.asmx

Method:

GetProviderRatingHTML

Usage and Examples:

Usage

string key = [provided via platform]

Int64 ClientID = [provided via platform];
Int32 ClientProviderID = //will vary by physician & website architecture, a unique ID assigned to each Provider

ServiceReference1.ProviderRatingsSoapClient sr1 = new ServiceReference1.ProviderRatingsSoapClient();
ServiceReference1.ProviderRatingData prd = sr1.GetProviderRatingData(ClientID, key, ClientProviderID);

Web Components

Client side data is a growing area of tech, and allows devs minimal coding time. Loyal/Transparently can automatically build and drop these “widget” like components into your site. This reduces coding time for your development or agency team, and can get your reviews and comments on your site faster!

We currently only recommend using web components for Provider Subtotals + Comments. This is because vital content like Provider Totals will include Structured Data, which will need to be indexed via a crawler. Although there is advancements by Google and Microsoft to capture JavaScript driven data, it’s still in it’s infancy.

AngularJS 1.x

Using the lastest version of AngularJS 1.x

Provider Subtotals + Comments

The provider’s subtotal rating component will include: N out of 5 rating for each subtotal, star rating graphic for each subtotal, text description for each subtotal, and all supporting HTML/CSS markup.

The provider comments component will include: N out of 5 rating for each comment, star rating graphic, comment text, comment attribution (“Piedmont Patient” in this example), and all supporting HTML/CSS markup.

Usage

<link href='[link to css]'  rel='stylesheet' type='text/css'>
<script src='[link to javascript]'></script>

<div ng-app="transparently" ng-controller="transparentlyController as Loyal/Transparently">  
  <!-- Drop in the Subtotals component -->
  <transparently-subtotals></transparently-subtotals>
  <!-- Drop in the Comments component -->
  <transparently-comments></transparently-comments>
</div>

Example

<head>
  <link href='https://assetsdev.transparently.com/example/transparently.min.css'  rel='stylesheet' type='text/css'>
</head>
<body>
  <!-- Website HTML -->
  <div ng-app="transparently" ng-controller="transparentlyController as Loyal/Transparently">
    <!-- More Website HTML -->
    <transparently-subtotals></transparently-subtotals>       
    <!-- More Website HTML -->
  </div>
  <!-- More Website HTML -->
  <script src='https://assetsdev.transparently.com/example/transparently.min.js' async></script>
</body>

ReactJS

Using the lastest version of ReactJS

Provider Subtotals + Comments

The provider’s subtotal rating component will include: N out of 5 rating for each subtotal, star rating graphic for each subtotal, text description for each subtotal, and all supporting HTML/CSS markup.

The provider comments component will include: N out of 5 rating for each comment, star rating graphic, comment text, comment attribution (“Piedmont Patient” in this example), and all supporting HTML/CSS markup.

Usage

<link href='[link to css]'  rel='stylesheet' type='text/css'>
<script src='[link to javascript]'></script>

<body>  
  <!-- Drop in the Subtotals component -->
  <div id="transparently-subtotals"></div>
  <!-- Drop in the Comments component -->
  <div id="transparently-comments"></div>
</body>

Example

<head>
  <link href='https://assetsdev.transparently.com/example/transparently.min.css'  rel='stylesheet' type='text/css'>
</head>
<body>
  <!-- Website HTML -->
  <div id="transparently-subtotals"></div>
  <!-- More Website HTML -->
  <div id="transparently-comments"></div>
  <!-- More Website HTML -->
  <script src='https://assetsdev.transparently.com/example/transparently.min.js' async></script>
</body>

Dictionary

Word Meaning
Component A piece of code that includes all of the data and design that Transparently publishes to the health system’s website.
Provider In simple terms, another word for doctor.
Structured Data Refers to HTML that is marked up using the schema.org vocabulary used by search engines to power rich web pages.

Technical Support

Questions? You can either send a note to support@transparently.com or reach out to one of us directly. We’d love to hear from you.

Icons