CareDash REST API Documentation (1.3.0)

CareDash Technical Support: support@caredash.com

Introduction

Welcome to the reference documentation for the CareDash REST API!

REST is a web-service protocol that lends itself to rapid development by using everyday HTTP and JSON technology.

You should find what you need in order to access the listings database for Providers, Facilities and Reviews using the CareDash API.

If you should have any questions along the way please don't hesitate to contact your CareDash Account Representative or a member of our Technical Support Team at support@caredash.com.

The Basics

The CareDash REST API provides access to the CareDash listing database and a broad set of operations and resources that allow you to:

  • Synchronize Provider or Facility information from your database to CareDash in real time

  • Search for providers or facilities in the CareDash database by filtering on a variety of fields including

    • Name
    • Address
    • NPI number
  • Claim a Provider or Facility directly from the REST interface

  • Update fields for a Provider or Facility you have claimed

  • Submit a reply to a CareDash user's review of a Provider.

For the API developer, CareDash is a publisher of healthcare provider listing information. Listings are essentially the business information associated with each provider or facility. Through the use of the CareDash API, you are able to programmatically claim providers or facilities that your organization is responsible for and make sure information regarding them is accurate and properly shown on the CareDash site.

A typical workflow for interacting with a Provider may involve the following steps:

  1. Use the /providers/search method to find providers of interest

  2. Use a GET request to /providers/{npi} to pull detailed information on any individual provider using their NPI and determine which fields/attributes require updates.

  3. Use a POST request to /providers/{npi} to claim the provider and convert to your "owned" listing

  4. Use a PATCH request to/providers/{npi} to subsequently update the provider with new data including headshots, summary text, address, phone, etc. As long as you remain the "owner" of the listing data, you may update that provider's data at any time.

  5. Use the reply /providers/reviews/{review-id}/reply method to submit a response to reviews on any of your claimed providers.

  6. Use a DELETE request to /providers/{npi} to unclaim a provider at any time if you no longer wish to manage their data.

Base Url

The production CareDash API can be found at 'https://api.caredash.com/v1/'.

The sandbox version can be found at 'https://api-sandbox.caredash.com/v1/'.

The production URL is used in the sample code snippets below and you will need to modify that accordingly if you are using those snippets on the sandbox server.

Authentication

The API validates every request with a bearer token passed in to the Authorization header. An invalid or missing token in the header will result in a 401 Forbidden error.

  curl -X GET -H 'Authorization: Bearer 1234' https://api.caredash.com/v1/admin/ping

Authorization Tokens are issued by CareDash and are unique for each Partner using the API. A token is associated with various allowed methods (e.g. read, write, claim) on various resources (e.g. providers, facilities, reviews). Your Account Representative will coordinate which set of permissions will be associated with your token.

accessKey

Authorization Tokens are issued with access keys and permissions as described in the following table:

Access Key Description
reference:read Allow read access to reference data
provider:read Allow read access to providers
provider:write Allow write access to providers
provider:claim Allow access to claim and unclaim providers
facility:read Allow read access to facilities
facility:write Allow write access to facilities
facility:claim Allow access to claim and unclaim facilities
review:read Allow read access to reviews
review:reply Allow access to reply to review
reply:revoke Allow access to revoke a submitted reply
webhook:subscribe Allow access to subscribe to webhook events

Required and nullable fields

Throughout this documentation, the keywords required and nullable are used to more fully describe fields in both requests and responses.

Requests must include all fields marked as required. Fields in the request may be null as indicated by the nullable tag in this documentation.

Responses will include all fields marked as required. If the response field is not marked as nullable, the field is guaranteed to be populated.

Releases

v1.3.0

  • Adds the ability to configure Telehealth on Providers and Facilities.

v1.2.0

  • Adds a Webhook system with support for notifying users about changes to Reviews and review Replies. See the documentation for details.

  • Adds a /providers/reviews/{id} endpoint for pulling data on a single Review.

v1.1.0

  • Removes the requirement that a Provider must be claimed in order to read any review Replies associated with them

  • Adds aggregate statistics about a provider's reviews to the /providers/{npi}/reviews endpoint

    • This includes, for example, the number of reviews and the overall rating across all reviews for the provider.
    • See the documentation of that endpoint for details.
  • Adds the ability to search for providers or facilities by slug

  • Adds a timestamp field in the response for /providers/reply/{reply-id}

    • This fields reflect the most recent time among when the Reply was created, processed or had its content changed. The timestamp will align with the date shown on CareDash.com for the Reply.
  • Significantly speeds up search requests for Providers and Facilities

    • Note that when a change is made to our internal database (e.g. via Provider or Facility patch requests) it could take up to 5 minute for that change to propagate and be reflected in the search behavior. Any data changed by patch requests is still immediately reflected in GET requests to /providers/{npi} and /facilities/{id}
  • Patch and post requests with unsupported parameters in the request body now return a 400 error.

    • Previously these requests could return a successful response which is potentially misleading and can obfuscate typos in request parameters.
  • Adds an active field to the images returned in a Provider or Facility details request (/providers/{npi} and /facilities/{id}).

    • This provides more visibility on the status of images submitted via a patch request.
    • When you submit an image through a patch request, the image will be inactive to begin with but will become active shortly after it is processed on our end (typically this is a matter of seconds). The active field reflects this.
  • Allow appropriate fields to be set to null in Provider and Facility patch requests

    • Previously, no fields could be set to null and now non-essential fields can be set to null.
    • A null value, an empty string or an empty list in the request may be used depending on the type of the field.

Admin

Admin endpoints.

Method Endpoint Description
GET /admin/ping Return CareDash API meta data including version number
GET /admin/docs Return CareDash API documentation in HTML form

Documentation

get /admin/docs
http://localhost:5001/v1/admin/docs
https://localhost:5001/v1/admin/docs

Returns HTML documentation on the CareDash API.

Responses

200

Successfully loaded html page.

Ping

get /admin/ping
http://localhost:5001/v1/admin/ping
https://localhost:5001/v1/admin/ping

Return meta data about the CareDash API including version number.

Authorizations:
accessKey (admin:read)
header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Responses

200

Successful response

Request samples

Copy
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer 1234'
'https://api.caredash.com/v1/admin/ping'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "version": "string"
}

Reference

These endpoints provide general reference data that can be used to inform Provider or Facility updates.

Method Endpoint Description
GET /reference/conditions Return a list of CareDash-supported conditions
GET /reference/insurances Return a list of CareDash-supported insurance carriers
GET /reference/languages Return a list of CareDash-supported languages
GET /reference/specialties Return a list of CareDash-supported medical specialties

Conditions

get /reference/conditions
http://localhost:5001/v1/reference/conditions
https://localhost:5001/v1/reference/conditions

CareDash maintains a list of conditions that are supported. This endpoint returns a list of those conditions. Ths 'slug' field is used for submitting a list of conditions when updating a Provider.

Authorizations:
accessKey (reference:read)
header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Responses

200

Successful response

Request samples

Copy
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer 1234'
'https://api.caredash.com/v1/reference/conditions'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "conditions":
    [
    ]
}

Insurance carriers

get /reference/insurances
http://localhost:5001/v1/reference/insurances
https://localhost:5001/v1/reference/insurances

CareDash maintains a list of insurance carriers that are supported. This endpoint returns a list of those insurance carriers. Ths 'slug' field is used for submitting a list of insurance carriers when updating a Provider.

Authorizations:
accessKey (reference:read)
header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Responses

200

Successful response

Request samples

Copy
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer 1234'
'https://api.caredash.com/v1/reference/insurances'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "insurance_carriers":
    [
    ]
}

Languages

get /reference/languages
http://localhost:5001/v1/reference/languages
https://localhost:5001/v1/reference/languages

CareDash maintains a list of languages that are supported when updating a Provider or Facility. This endpoint returns a list of those languages.

Authorizations:
accessKey (reference:read)
header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Responses

200

Successful response

Request samples

Copy
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer 1234'
'https://api.caredash.com/v1/reference/languages'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "languages":
    [
    ]
}

Specialties

get /reference/specialties
http://localhost:5001/v1/reference/specialties
https://localhost:5001/v1/reference/specialties

CareDash maintains a list of specialties that are supported. This endpoint returns a list of those specialties. Ths 'slug' field is used for submitting a list of specialties when updating a provider.

Authorizations:
accessKey (reference:read)
header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Responses

200

Successful response

Request samples

Copy
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer 1234'
'https://api.caredash.com/v1/reference/specialties'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "specialties":
    [
    ]
}

Facilities

A Facility in the CareDash model represents an organization at a specific address that gives medical services to the community. We track and manage many attributes for a Facility. For example address, images, summary text, and social medial links.

Method Endpoint Description
GET /facilities/search Find Facilities based on search criteria and return a summary set of attributes
GET /facilities/{id} Returns a detailed set of attributes for a Facility
POST /facilities/{id} Claim a Facility which is required to perform subsequent actions for that Facility (e.g. edit Facility fields)
PATCH /facilities/{id} Edit fields associated with a Facility (e.g. address, images etc.)
DELETE /facilities/{id} Remove an existing claim on a Facility. Appropriate if you are no longer managing data for the Facility.

Facility details by ID

get /facilities/{id}
http://localhost:5001/v1/facilities/{id}
https://localhost:5001/v1/facilities/{id}

Detailed information about a Facility.

Authorizations:
accessKey (facility:read)
path Parameters
id
required
string

Resource ID

header Parameters
Authorization
required
string

Bearer {token} for a valid OAuth token.

Responses

200

Successful response

404

Facility not found

Request samples

Copy
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer 1234'
'https://api.caredash.com/v1/facilities/5w0gkn9v9r7y72mo'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "accepting_new_patients": true,
  • "address":
    {
    },
  • "bike_parking": true,
  • "ccns":
    [
    ],
  • "emergency_services": true,
  • "fax": 1234567890,
  • "history": "Established in 2002, Cambridge Health Alliance started as a ...",
  • "hours_of_operation":
    [
    ],
  • "how_to_find": "The practice is located at the corner of Hampshire St and King Rd just off exit 30.",
  • "id": "m1ol9p0n9jyde5n8",
  • "images":
    [],
  • "imaging": true,
  • "insurance_url": "