Survey Data Export

Introduction

A new API need to be designed to extract survey data processed by BHA for a client. The API will return the data based on filter criteria. The filters are locations, providers, sources, from date, to date and page number. Total number of records per API call will be 20 which is in the XML format.

If the client needs historical data, then we will drop the XML file with large data onto an SFTP location.

Before using the API, an application must be provisioned by PressGaney. 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.

Endpoint

POSThttps://api.binaryfountain.com/api/service/v1/xmlsurveydata

Header Parameters

Property	Type	Description	Required/Optional
Accept	application/json, application/xml	You can retrieve the data in either JSON or XML formats	Required
Access-Token	String	Access token received from the platform	Required

Request Parameters

Property	Type	Description	Required/Optional
locations	Array	List of unique entity code of a location for which data is requested.	Optional – will consider all entities if not passed
providers	Array	List of unique entity code of a provider for which data is requested.	Optional - will consider all entities if not passed
sources	Array	List of source names. If not specified, all sources will be returned. Examples of source names are given in appendix below.	Optional – will consider all sources if not passed
from	String	from date in ISO 8601 format	Optional – will consider last one day as date range if not passed.
to	String	To date in ISO 8601 format	Optional – will consider last one day as date range if not passed.
page	Integer	Requesting page number	Optional – Will consider as 1 if not passed.
structured_question	String	Pass “true” to include structured questions in the response. Default is only unstructured questions.	Optional – Will consider “false” if not passed.
historical_data	String	Pass “true” to get xml survey data as a xml file from AWS S3 location	Optional - Will consider “false” if not passed.

{
    "from": "2019-01-01T00:00:00Z",
    "historical_data": false,
    "locations": [
        "5_12062",
        "5_54"
    ],
    "page": 1,
    "sources": [
        "Emergency Department Survey",
        "Oncology Survey"
    ],
    "structured_question": false,
    "to": "2019-03-20T23:59:59Z"
}

Response

Response Parameters

A XML object containing the API response for provider or location

XML
JSON

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<data>
<filter>
    <period>
        <from></from>
        <to></to>
    </period>
    <source/>
    <location/>
    <provider/>
    <page>1</page>
    <structured_question>false</structured_question>
</filter>
<documents>
    <document>
        <document_id>239860593</document_id>
        <source_id>Google</source_id>
        <location_name>Springs at Venacava</location_name>
        <location_id>596873</location_id>
        <received_date>01/08/2024</received_date>
        <sentiments>
            <sentiment>
                <question>Your comments:</question>
                <comment>Access to social comment data not supported</comment>
                <opinion>made us feel welcomed</opinion>
                <feature>Jocelyn</feature>
                <category>Staff/Team / Leasing Staff</category>
                <sentiment>Positive</sentiment>
                <csi_score>5</csi_score>
                <locationFeatureWord>false</locationFeatureWord>
            </sentiment>
            <sentiment>
                <question>Your comments:</question>
                <comment>Access to social comment data not supported</comment>
                <opinion>explained</opinion>
                <feature>Jocelyn</feature>
                <category>Staff/Team / Leasing Staff</category>
                <sentiment>Positive</sentiment>
                <csi_score>5</csi_score>
                <locationFeatureWord>false</locationFeatureWord>
            </sentiment>
            <sentiment>
                <question>Your comments:</question>
                <comment>Access to social comment data not supported</comment>
                <opinion>made us feel welcomed</opinion>
                <feature>Jocelyn</feature>
                <category>Staff/Team / Leasing Staff</category>
                <sentiment>Positive</sentiment>
                <csi_score>5</csi_score>
                <locationFeatureWord>false</locationFeatureWord>
            </sentiment>
            <sentiment>
                <question>Your comments:</question>
                <comment>Access to social comment data not supported</comment>
                <opinion>explained</opinion>
                <feature>Jocelyn</feature>
                <category>Staff/Team / Leasing Staff</category>
                <sentiment>Positive</sentiment>
                <csi_score>5</csi_score>
                <locationFeatureWord>false</locationFeatureWord>
            </sentiment>
            <sentiment>
                <question>Your comments:</question>
                <comment>Access to social comment data not supported</comment>
                <opinion>amazing</opinion>
                <feature>amenities</feature>
                <category>Amenities / Amenities - General Amenities</category>
                <sentiment>Positive</sentiment>
                <csi_score>5</csi_score>
                <locationFeatureWord>false</locationFeatureWord>
            </sentiment>
            <sentiment>
                <question>Your comments:</question>
                <comment>Access to social comment data not supported</comment>
                <opinion>Huge</opinion>
                <feature>complex</feature>
                <category>Community / Overall Community Quality</category>
                <sentiment>Positive</sentiment>
                <csi_score>5</csi_score>
                <locationFeatureWord>false</locationFeatureWord>
            </sentiment>
        </sentiments>
    </document>
</documents>
<page_number>1</page_number>
<total_pages>1</total_pages>
<total_records>12</total_records>
<status>
    <message>success</message>
    <code>200</code>
</status>
<version>v1.0</version>
</data>

{
    "documents": {
        "document": [
            {
                "document_id": "239860593",
                "location_id": "596873",
                "location_name": "Springs at Tapestry",
                "pg_survey_id": null,
                "provider_id": null,
                "provider_name": null,
                "received_date": "01/08/2024",
                "sentiments": {
                    "sentiment": [
                        {
                            "category": "Staff/Team / Leasing Staff",
                            "comment": "Access to social comment data not supported",
                            "csi_score": "5",
                            "feature": "Jocelyn",
                            "locationFeatureWord": false,
                            "opinion": "made us feel welcomed",
                            "pfs_score": null,
                            "question": "Your comments:",
                            "response": null,
                            "sentiment": "Positive"
                        },
                        {
                            "category": "Staff/Team / Leasing Staff",
                            "comment": "Access to social comment data not supported",
                            "csi_score": "5",
                            "feature": "Jocelyn",
                            "locationFeatureWord": false,
                            "opinion": "explained",
                            "pfs_score": null,
                            "question": "Your comments:",
                            "response": null,
                            "sentiment": "Positive"
                        }
                    ]
                },
                "service_line": null,
                "source_id": "Google"
            }
        ]
    },
    "file": null,
    "filter": {
        "location": {
            "id": [
            ]
        },
        "page": 1,
        "period": {
            "from": "",
            "to": ""
        },
        "provider": {
            "id": [
            ]
        },
        "source": {
            "id": [
            ]
        },
        "structured_question": false
    },
    "page_number": 1,
    "status": {
        "code": 200,
        "message": "success"
    },
    "total_pages": 1,
    "total_records": 12,
    "version": "v1.0"
}

Property	Type	Description
documents	XMLObject	XML Object
document.source_id	String	Source name
document.pg_survey_id	Integer	PG Survey id
document.document_id	Integer	Document id
document.location_name	String	Location name
document.location_id	Integer	Location id
document.provider_name	String	Provider name
document.provider_id	Integer	Provider id
document.service_line	String	Service line
document.received_date	Date	Document received date (format - DD/MM/YYYY)
document.sentiments	XMLObject	XML Object
sentiment.question	String	Survey question
sentiment.comment	String	Response of unstructured question
sentiment.response	String	Response of structured question
sentiment.opinion	String	Opinion
sentiment.feature	String	Feature
sentiment.category	String	Category or Theme
sentiment.sentiment	String	Sentiment
sentiment.pfs_score	Double	Document PFS score for all healthcare clients
sentiment.csi_score	Double	Document CSI score for all non-healthcare clients
sentiment.locationFeatureWord	boolean	True when entityname matches with feature
page_number	Integer	Page number – each page contains 20 records
total_pages	Integer	Total number of pages
total_records	Integer	Total number of records
status.message	String	API status message
status.code	Integer	API status code

Introduction​

Endpoint​

Header Parameters​

Request Parameters​

Response​

Response Parameters​