Reporting

This page describes the API calls necessary to generate DexCare All Visit Reports and the All Providers Report.

All Visits Reports (AVR)

For details on the contents of the AVR reports, please consult the relevant data dictionary for the appropriate report type(PDF download)

There are three endpoints for generating AVR reports:

startAvrReport
getAvrReportStatus
getAvrResultCsv

Reporting Service Key

Reporting requests to DexCare require a reporting service key. The reporting service key should be handled like a password — it must not be shared or distributed. You will want to store it in a secret manager and use best practices in applications that use it. In the examples used, we will use SECRET_TOKEN but please replace this with the reporting service key.

Service Key Security

You cannot keep the SECRET_TOKEN in a client side application. This include mobile or client side JavaScript. It must be saved securely on a server.

API Endpoint

The API endpoint will look similar to https://ecvapi.care.YOUR_DOMAIN.com. For these examples, we will use REST_ENDPOINT to represent the API hostname.

Requests

The three reporting endpoints are used together, as described.

startAvrReport

The startAvrReport command sends a request to DexCare to start a reporting query.

Because generating a report can take some time, the report data itself is not returned.

Instead this endpoint returns a report id which we can use in the following requests.

info

Note that if no POST body is specified, there will be a 400 response with the message "error:type is required".

Parameters

type

REQUIRED

You can request one of two reports, a virtual report, or a retail report. This can be specified in the POST body with the type as either virtual or retail.

type:	body
values:	`virtual` • `retail` • `provider_booking`

startDate

REQUIRED if endDate is specified, otherwise the past 10 days of data will be returned

date from which report data should start for the visit search

type:	body
values:	ISO Date

endDate

REQUIRED if startDate is specified, otherwise the past 10 days of data will be returned

date from which report data should end for the visit search

type:	body
values:	ISO Date

curl

curl -X POST \
	${REST_ENDPOINT}/api/8/reporting/allvisitsreport\
    -H "Authorization: dc-token SECRET_TOKEN" \
    -H "Content-Type: application/json" \ 
    --data '{"type":"virtual", "startDate": "2022-04-13T15:00:00+0000", "endDate": "2022-04-14T15:00:00+0000"}'

Responses:

200 - success:

{ "id": "3b690e39-4659-40f9-9909-58b27c0a4383" }

400 - bad request:

{ "error": "'type' is required" }
{ "error": "'type' must be one of [retail, virtual]"}

403 - forbidden:

{ "message": "Authorization failed: bad service token"}

500 - internal server error:

{ "error": "Unknown error" }

getAvrReportStatus

Once you have started a report, you can send a request to get the report status.

curl

curl -X GET ${REST_ENDPOINT}/api/8/reporting/allvisitsreport/3b690e39-4659-40f9-9909-58b27c0a4383 \
    -H "Authorization: dc-token SECRET_TOKEN" \
    -H "Content-Type: application/json"

Responses:

200 - success:

{"status":"SUCCEEDED"} (See other statuses below)

400 - bad request:

{ "msg": "getAvrQueryStatus bad request', <reportId>, <err>" }

403 - forbidden:

{ "message": "Authorization failed: bad service token"}

404 - not found:

{ "error": "QueryExecution Not Found" }

500 - internal server error:

{ "error": "Unknown error" }

The status of getAvrReportStatus may be one of:

SUCCEEDED, the report is ready for download
RUNNING, the report is currently running
QUEUED, the report is queued to run
FAILED, the report failed to run. The report may auto-retry, in which case, the status may temporarily be FAILED and then moments later switch into QUEUED again
CANCELLED, cancelled by user. We would not expect this response unless there is an exceptional issue on the DexCare side

getAvrResultCsv

Once the report status is in SUCCEEDED state, you can then send a request to fetch the data.

curl

curl -X GET ${REST_ENDPOINT}/api/8/reporting/allvisitsreport/3b690e39-4659-40f9-9909-58b27c0a4383/data \
    -H "Authorization: dc-token SECRET_TOKEN" \
    -H "Content-Type: application/text"

Responses:

200 - success:

Response will be in CSV format.

400 - bad request:

{ "error": "QueryExecution did not succeed" }
{ "error": "'reportId' must be a valid GUID" }

403 - forbidden:

{ "message": "Authorization failed: bad service token"}

404 - not found:

{ "error": "QueryExecution Not Found" }

500 - internal server error:

{ "error": "Unknown error" }

Sample code for storing AVR data

Here are two examples of how to regularly call the API, deduplicate the data, and import it into either PostgreSQL or Microsoft SQL using Python. Please download the sample code that works for your environment

All Providers Report (APR)

The All Providers Report (APR) is an API that allows users to search provider history records, which are built from events sent to the reporting system.

For a full description of all the fields in the APR report, please consult the Provider Histories Data Definition PDF

You will need an API key in order to call this API. Contact your DexCare account manager to obtain this API Key.

Endpoint

.../v1/reporting/providerhistories

Below is an example CURL invocation of the URL

curl --location '<BASE_URL>/v1/reporting/providerhistories' \
--header 'Authorization: dc-token <REDACTED_API_KEY>' \
--header 'Content-Type: application/json' \
--data '
{
  "startDate": "2023-10-12T07:00:00.000Z",
  "endDate": "2023-10-13T17:00:00.000Z"
}'

APR Search Terms

There are 14 search parameters available plus two fields that may be used for pagination.

startDate and endDate are required.

All other fields are optional. The possible fields and example values are shown below. Consult the PDF guide for complete field definitions.

Field value matches are case-insensitive except for providerCredentials which searches for values that contain the given value (e.g., a search for “MD” will match fields with the values “MD DO”).

Multi field searches will be combined with an AND relationship.

{
  "limit": 5,
  "offset": 200,
  "startDate": "2023-11-06T07:00:00.000Z",
  "endDate": "2023-11-08T23:59:00.000Z",
  "action": "assigned",
  "visitId": "5e99eb90-c2db-48ff-a6d3-aec7e126cec7"
  "providerId": "22606c4c-15c8-4959-ae7f-a8940356b3db",
  "providerEmailAddress": "doctor@dexcarehealth.com",
  "providerName": "Jenny Generic",
  "providerFirstName": "Jenny"
  "providerLastName": "Generic"
  "providerCredentials": "MD"
  "actorId": "4d24c6db-45e7-4a9a-b9cb-3477abb032be",
  "actorEmail": "actor@dexcarehealth.com",
  "actorFirstName": "Simon",
  "actorLastName": "Standard",
}

The responses returned by the API are wrapped in a result set object that contains the fields count and data. The count represents the total number of records that match the query.

{ 
	"count": 6573,
	"data" : [
		{
			"id" : "7b005622-6b71"
			...
		},
		...
	]
		
}

The offset and limit are optional fields that may be submitted with your search query. These fields may be used with the count included with the response that wraps the data for the purposes of pagination through the result set. For each request, increment the offset until the sum of it and the limit together exceed the count.

The default for offset is 0 and the default for limit is 50. The limit default is configurable by Dexcare.