Reporting
This page describes the API calls necessary to generate DexCare reports.
For details on the contents of these reports, please consult the relevant data dictionary for the appropriate report type
(PDF download)
There are three endpoints for generating 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 -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 -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 downloadRUNNING
, the report is currently runningQUEUED
, the report is queued to runFAILED
, the report failed to run. The report may auto-retry, in which case, the status may temporarily beFAILED
and then moments later switch intoQUEUED
againCANCELLED
, 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 -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