Retrieving C-CDA via API

Software Requirements #

Software requirements for retrieving C-CDA via API calls can be found here

Authentication #

If you have a Canvas Production instance, you will need to request a token and refresh it periodically. You can refer to our Authentication Documentation to get you set up.

Request and Parameters #

In order to generate a CCDA for a known patient key, you’ll need to do a GET request to the endpoint {YOUR_EHR_INSTANCE}/api/data-export/ccda/{patient_key}?document={document_type}, where document_type can be either continuity or referral. You can check all parameters in the table below.

Parameter NameDescriptionRequirement
documentDocument type to be generated.
Should be either `continuity` or `referral`
start_dateFilter for the start date of the sections within the document.
Format should be `YYYY-MM-DD`
end_dateFilter for the end date of the sections within the document.
Format should be `YYYY-MM-DD`
generation_dateOverrides the generation date of the document.
Format should be `YYYY-MM-DDTHH:mm:ss`, in UTC timezone

Filtering #

start_date and end_date filter can be used to:

  • filter by a range of dates by inputing both parameters;
  • filter by a single date in the past by making start_date and end_date the same;
  • filter starting at a date in the past up until present time by only setting start_date;
  • filter from the beginning of time up to any date by only setting end_date;

Example and Response #

Here’s a cURL example of a request for a continuity of care document, filtered for 2020-01-01 to 2020-12-31, and with a generation date of 2022-01-01, at 16:30 UTC:

  "codes": [
      "code": "curl --request GET \\n     --header \"Authorization: Bearer YOUR_AUTHORIZATION_TOKEN\"\n     {YOUR_EHR_INSTANCE}/api/data-export/ccda/{PATIENT_KEY}?document=continuity\\n     &start_date=2020-01-01\\n     &end_date=2020-12-31\\n     &generation_date=2022-01-01T16:30:00",
      "language": "curl"

A valid request will always return a XML with the requested document as the response. If the document param is omitted, an empty XML will be returned.

Errors #

Canvas uses conventional HTTP response codes to indicate success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a request wasn’t found, etc.). Codes in the 5xx range indicate an error with Canvas’ server.

200 - OKEverything worked as expected.
403 - ForbiddenNo valid Bearer token provided.
404 - Not FoundThe requested resource doesn't exist.
500 - Server ErrorSomething went wrong on Canvas's end.