{
  "openapi": "3.0.3",
  "info": {
    "title": "Transparency API",
    "version": "0.1.0-preview.1",
    "description": "Preview contract for the three Transparency data operations. The contract\ndocuments the public gateway surface and does not change authentication,\nrouting, caching, rate limits or runtime schema enforcement.\n"
  },
  "servers": [
    {
      "url": "https://api1.consumerism.pressganey.com",
      "description": "Public API"
    }
  ],
  "tags": [
    {
      "name": "Reviews"
    },
    {
      "name": "Comments"
    }
  ],
  "paths": {
    "/api/external/bsr/v2/reviews": {
      "post": {
        "tags": [
          "Reviews"
        ],
        "operationId": "getReviews",
        "summary": "Retrieve reviews for a person, location or roll-up entity",
        "description": "Retrieve the reviewed feedback records matching a person, location, or roll-up entity identifier and the supplied filters. Application errors may be embedded in an HTTP 200 response envelope.",
        "security": [
          {
            "AccessToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReviewsRequest"
              },
              "example": {
                "locationId": "LOC-EXAMPLE-001",
                "perPage": 20,
                "days": 365,
                "showRatings": true,
                "showReviews": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reviews response. Application status is carried in the response body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReviewsResponse"
                },
                "example": {
                  "status": {
                    "code": 200,
                    "message": "SUCCESS"
                  },
                  "data": {
                    "client": "Example Organization",
                    "entities": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/bsr/comments": {
      "get": {
        "tags": [
          "Comments"
        ],
        "operationId": "getComments",
        "summary": "Retrieve comments using query filters",
        "description": "Retrieve comments and ratings for a person, location, or roll-up entity identifier. At least one supported identifier is required; the identifier alternatives are not all required together.",
        "security": [
          {
            "AccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/PersonId"
          },
          {
            "$ref": "#/components/parameters/LocationId"
          },
          {
            "$ref": "#/components/parameters/EntityId"
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PerPage"
          },
          {
            "$ref": "#/components/parameters/MinThreshold"
          },
          {
            "$ref": "#/components/parameters/Days"
          },
          {
            "$ref": "#/components/parameters/FromDate"
          },
          {
            "$ref": "#/components/parameters/ToDate"
          },
          {
            "$ref": "#/components/parameters/MinSurveyCount"
          },
          {
            "$ref": "#/components/parameters/MinRatingCount"
          },
          {
            "$ref": "#/components/parameters/MinWordCount"
          },
          {
            "$ref": "#/components/parameters/ShowRatings"
          },
          {
            "$ref": "#/components/parameters/ShowComments"
          },
          {
            "$ref": "#/components/parameters/AdditionalFields"
          }
        ],
        "responses": {
          "200": {
            "description": "Comments response. Application status is carried in the response body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommentsResponse"
                },
                "example": {
                  "status": {
                    "code": 200,
                    "message": "success"
                  },
                  "data": {
                    "client": "Example Organization",
                    "entities": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Comments"
        ],
        "operationId": "queryComments",
        "summary": "Retrieve comments using a form request",
        "description": "Retrieve comments with the same filters as GET. The request uses application/x-www-form-urlencoded and repeated personId, locationId, or entityId keys for arrays. The gateway also accepts query parameters for this POST and currently converts query values into the equivalent form body before forwarding. Send either query parameters or a form body; do not mix both representations because query conversion can replace the body.",
        "security": [
          {
            "AccessToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/PersonIdArrayQuery"
          },
          {
            "$ref": "#/components/parameters/LocationIdArrayQuery"
          },
          {
            "$ref": "#/components/parameters/EntityIdArrayQuery"
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PerPage"
          },
          {
            "$ref": "#/components/parameters/MinThreshold"
          },
          {
            "$ref": "#/components/parameters/Days"
          },
          {
            "$ref": "#/components/parameters/FromDate"
          },
          {
            "$ref": "#/components/parameters/ToDate"
          },
          {
            "$ref": "#/components/parameters/MinSurveyCount"
          },
          {
            "$ref": "#/components/parameters/MinRatingCount"
          },
          {
            "$ref": "#/components/parameters/MinWordCount"
          },
          {
            "$ref": "#/components/parameters/ShowRatings"
          },
          {
            "$ref": "#/components/parameters/ShowComments"
          },
          {
            "$ref": "#/components/parameters/AdditionalFields"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/CommentsRequest"
              },
              "example": {
                "personId": [
                  "147852369",
                  "147852370"
                ],
                "perPage": 20,
                "showComments": true
              },
              "encoding": {
                "personId": {
                  "style": "form",
                  "explode": true
                },
                "locationId": {
                  "style": "form",
                  "explode": true
                },
                "entityId": {
                  "style": "form",
                  "explode": true
                },
                "additionalFields": {
                  "style": "form",
                  "explode": true
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Comments response. Application status is carried in the response body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommentsResponse"
                },
                "example": {
                  "status": {
                    "code": 200,
                    "message": "success"
                  },
                  "data": {
                    "client": "Example Organization",
                    "entities": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "AccessToken": {
        "type": "apiKey",
        "in": "header",
        "name": "Access-Token",
        "description": "Access token returned by the authentication endpoint."
      }
    },
    "parameters": {
      "PersonId": {
        "name": "personId",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Physician identifier. Use locationId or entityId for another supported case."
      },
      "LocationId": {
        "name": "locationId",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Location identifier. Use personId or entityId for another supported case."
      },
      "EntityId": {
        "name": "entityId",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Roll-up entity identifier. Use personId or locationId for another supported case."
      },
      "PersonIdArrayQuery": {
        "name": "personId",
        "in": "query",
        "required": false,
        "style": "form",
        "explode": true,
        "schema": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "description": "Repeated physician identifiers; for example personId=1001&personId=1002."
      },
      "LocationIdArrayQuery": {
        "name": "locationId",
        "in": "query",
        "required": false,
        "style": "form",
        "explode": true,
        "schema": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "description": "Repeated location identifiers."
      },
      "EntityIdArrayQuery": {
        "name": "entityId",
        "in": "query",
        "required": false,
        "style": "form",
        "explode": true,
        "schema": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "description": "Repeated roll-up entity identifiers."
      },
      "Page": {
        "name": "page",
        "in": "query",
        "schema": {
          "type": "integer",
          "default": 1
        }
      },
      "PerPage": {
        "name": "perPage",
        "in": "query",
        "schema": {
          "type": "integer",
          "default": 20
        }
      },
      "Days": {
        "name": "days",
        "in": "query",
        "schema": {
          "type": "integer",
          "default": 365
        }
      },
      "MinThreshold": {
        "name": "minThreshold",
        "in": "query",
        "schema": {
          "type": "number",
          "format": "double",
          "default": 0
        },
        "description": "Minimum overall rating threshold."
      },
      "FromDate": {
        "name": "fromDate",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "ISO-8601 UTC start timestamp. Use with toDate; the pair takes precedence over days."
      },
      "ToDate": {
        "name": "toDate",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "ISO-8601 UTC end timestamp. Use with fromDate."
      },
      "MinSurveyCount": {
        "name": "minSurveyCount",
        "in": "query",
        "schema": {
          "type": "integer",
          "default": 0
        }
      },
      "MinRatingCount": {
        "name": "minRatingCount",
        "in": "query",
        "schema": {
          "type": "integer",
          "default": -1
        }
      },
      "MinWordCount": {
        "name": "minWordCount",
        "in": "query",
        "schema": {
          "type": "integer",
          "default": 0
        }
      },
      "ShowRatings": {
        "name": "showRatings",
        "in": "query",
        "schema": {
          "type": "boolean",
          "default": true
        }
      },
      "ShowComments": {
        "name": "showComments",
        "in": "query",
        "schema": {
          "type": "boolean",
          "default": true
        }
      },
      "AdditionalFields": {
        "name": "additionalFields",
        "in": "query",
        "style": "form",
        "explode": true,
        "schema": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "schemas": {
      "Status": {
        "type": "object",
        "properties": {
          "code": {
            "oneOf": [
              {
                "type": "integer"
              },
              {
                "type": "string"
              }
            ],
            "example": 200
          },
          "message": {
            "type": "string",
            "nullable": true,
            "example": "SUCCESS"
          },
          "type": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": true
      },
      "Error": {
        "type": "object",
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          }
        }
      },
      "ReviewsRequest": {
        "type": "object",
        "description": "Supply at least one identifier family. Person, location, and roll-up pages are alternatives for the same operation; exact combinations and precedence remain deployment review items.",
        "properties": {
          "personId": {
            "type": "string"
          },
          "locationId": {
            "type": "string"
          },
          "entityId": {
            "type": "string"
          },
          "page": {
            "type": "integer",
            "default": 0
          },
          "perPage": {
            "type": "integer",
            "default": 20
          },
          "minThreshold": {
            "type": "number",
            "format": "double",
            "description": "Minimum overall rating threshold from 0 to 5."
          },
          "days": {
            "type": "integer",
            "default": 365
          },
          "minSurveyCount": {
            "type": "integer",
            "default": 0
          },
          "minRatingCount": {
            "type": "integer",
            "default": -1
          },
          "minWordCount": {
            "type": "integer",
            "default": 0
          },
          "showRatings": {
            "type": "boolean",
            "default": true
          },
          "showReviews": {
            "type": "boolean",
            "default": true
          },
          "fromDate": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "toDate": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "scrollKey": {
            "type": "string"
          },
          "additionalFields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "CommentsRequest": {
        "type": "object",
        "properties": {
          "personId": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "locationId": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "entityId": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "page": {
            "type": "integer",
            "default": 1
          },
          "perPage": {
            "type": "integer",
            "default": 20
          },
          "minThreshold": {
            "type": "number",
            "format": "double",
            "default": 0
          },
          "days": {
            "type": "integer",
            "default": 365
          },
          "fromDate": {
            "type": "string",
            "format": "date-time"
          },
          "toDate": {
            "type": "string",
            "format": "date-time"
          },
          "minSurveyCount": {
            "type": "integer",
            "default": 0
          },
          "minRatingCount": {
            "type": "integer",
            "default": -1
          },
          "minWordCount": {
            "type": "integer",
            "default": 0
          },
          "showRatings": {
            "type": "boolean",
            "default": true
          },
          "showComments": {
            "type": "boolean",
            "default": true
          },
          "additionalFields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Rating": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "value": {
            "type": "number",
            "format": "double"
          },
          "responseCount": {
            "type": "integer"
          }
        }
      },
      "QuestionRating": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "value": {
            "type": "number",
            "format": "double"
          },
          "responseCount": {
            "type": "integer"
          }
        }
      },
      "OverallRating": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "value": {
            "type": "number",
            "format": "double"
          },
          "categoryResponseCount": {
            "type": "integer"
          },
          "questionRatings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuestionRating"
            }
          },
          "ratingDistribution": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RatingDistribution"
            }
          }
        }
      },
      "RatingDistribution": {
        "type": "object",
        "properties": {
          "ratingNum": {
            "type": "integer"
          },
          "ratingSurveyCount": {
            "type": "integer"
          }
        }
      },
      "Comment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "surveyKey": {
            "type": "string",
            "nullable": true
          },
          "source": {
            "type": "string"
          },
          "mentionTime": {
            "type": "string",
            "format": "date-time"
          },
          "wordCount": {
            "type": "integer"
          },
          "comment": {
            "type": "string"
          },
          "overallRating": {
            "$ref": "#/components/schemas/Rating"
          },
          "ratings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Rating"
            }
          },
          "response": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AnnotationResponse"
              }
            ],
            "nullable": true
          },
          "tone": {
            "type": "string",
            "nullable": true
          },
          "category": {
            "type": "string",
            "nullable": true
          },
          "varname": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "AnnotationResponse": {
        "type": "object",
        "properties": {
          "responseText": {
            "type": "string",
            "nullable": true
          },
          "respondedBy": {
            "type": "string",
            "nullable": true
          },
          "respondedTime": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "EntitySummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "reviewSummary": {
            "type": "string",
            "nullable": true
          },
          "lookBackWindow": {
            "type": "integer",
            "nullable": true
          },
          "totalRatingCount": {
            "type": "integer"
          },
          "totalCommentCount": {
            "type": "integer"
          },
          "totalSurveyCount": {
            "type": "integer"
          },
          "overallRating": {
            "$ref": "#/components/schemas/OverallRating"
          },
          "ratings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OverallRating"
            }
          },
          "PGSealOfIntegrity": {
            "nullable": true
          }
        }
      },
      "ReviewsEntity": {
        "allOf": [
          {
            "$ref": "#/components/schemas/EntitySummary"
          },
          {
            "type": "object",
            "properties": {
              "reviews": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Review"
                }
              }
            }
          }
        ]
      },
      "CommentsEntity": {
        "allOf": [
          {
            "$ref": "#/components/schemas/EntitySummary"
          },
          {
            "type": "object",
            "properties": {
              "comments": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Comment"
                }
              },
              "totalPages": {
                "type": "integer"
              }
            }
          }
        ]
      },
      "Review": {
        "type": "object",
        "properties": {
          "documentId": {
            "type": "integer",
            "format": "int64"
          },
          "surveyKey": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "mentionTime": {
            "type": "string",
            "format": "date-time"
          },
          "overallRating": {
            "$ref": "#/components/schemas/Rating"
          },
          "ratings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Rating"
            }
          },
          "comment": {
            "type": "object",
            "properties": {
              "commentId": {
                "type": "integer",
                "format": "int64"
              },
              "wordCount": {
                "type": "integer"
              },
              "comment": {
                "type": "string"
              }
            }
          },
          "response": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AnnotationResponse"
              }
            ],
            "nullable": true
          },
          "tone": {
            "type": "string",
            "nullable": true
          },
          "category": {
            "type": "string",
            "nullable": true
          },
          "varname": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ReviewsData": {
        "type": "object",
        "properties": {
          "client": {
            "type": "string"
          },
          "entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReviewsEntity"
            }
          },
          "filter": {
            "$ref": "#/components/schemas/ReviewsFilter"
          }
        }
      },
      "CommentsData": {
        "type": "object",
        "properties": {
          "client": {
            "type": "string"
          },
          "entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CommentsEntity"
            }
          },
          "filter": {
            "$ref": "#/components/schemas/CommentsFilter"
          }
        }
      },
      "ReviewsFilter": {
        "type": "object",
        "properties": {
          "entityId": {
            "type": "integer"
          },
          "scrollKey": {
            "type": "string",
            "nullable": true
          },
          "person": {
            "type": "boolean"
          },
          "fromDate": {
            "type": "string",
            "nullable": true
          },
          "toDate": {
            "type": "string",
            "nullable": true
          },
          "period": {
            "$ref": "#/components/schemas/Period"
          },
          "days": {
            "type": "integer"
          },
          "minThreshold": {
            "type": "number",
            "format": "double"
          },
          "minRatingCount": {
            "type": "integer"
          },
          "minSurveyCount": {
            "type": "integer"
          },
          "minWordCount": {
            "type": "integer"
          },
          "showReviews": {
            "type": "boolean"
          },
          "showRatings": {
            "type": "boolean"
          },
          "perPage": {
            "type": "integer"
          }
        }
      },
      "CommentsFilter": {
        "type": "object",
        "properties": {
          "minThreshold": {
            "type": "number",
            "format": "double"
          },
          "minRatingCount": {
            "type": "integer"
          },
          "minSurveyCount": {
            "type": "integer"
          },
          "minWordCount": {
            "type": "integer"
          },
          "days": {
            "type": "integer"
          },
          "page": {
            "type": "integer"
          },
          "perPage": {
            "type": "integer"
          },
          "showComments": {
            "type": "boolean"
          },
          "showRatings": {
            "type": "boolean"
          },
          "configVersion": {
            "type": "string",
            "nullable": true
          },
          "period": {
            "$ref": "#/components/schemas/Period"
          }
        }
      },
      "Period": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "nullable": true
          },
          "to": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "CommentsResponse": {
        "type": "object",
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "data": {
            "$ref": "#/components/schemas/CommentsData"
          }
        }
      },
      "ReviewsResponse": {
        "type": "object",
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "data": {
            "$ref": "#/components/schemas/ReviewsData"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid access token.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Token is valid but lacks permission for the requested data.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "The submitted identifier count exceeds the gateway limit.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Request rate limit exceeded.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}