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.

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.

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: virtualretail  •  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 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