Reporting

This page describes the API calls necessary to generate DexCare reports.

For details on the contents of these reports, please consult this PDF

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.

Important Note: 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, we don’t get the data right away, we just get a report id which we can use in the following requests.

We 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. If no POST body is specified, there will be a 400 response with the message error:type is required.

  • curl -X POST ${REST_ENDPOINT}/api/8/reporting/allvisitsreport \
        -H "Authorization: dc-token SECRET_TOKEN" \
        -H "Content-Type: application/json" \ 
        --data '{"type":"virtual"}'
    

    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 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 -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