cda2sql Application Programming Interface (API) purpose is to help you:

1. Automatically parse C-CDA documents into a tabular format suitable for databases
2. Create a MySQL database and start populate it with your own C-CDA documents in less than 10 minutes (see SQL script and Python code below)
Our API endpoint offers simple REST calls that return information in JSON format.
If you have any questions or ideas for improving the API please contact us at and we will get back to you promptly.

In order to use apiCDA2SQL you have to be registered with us. If you are not registered - please take a moment to sign up with us before using our API.
Signing-up doesn't require a credit card and it offers one month and 100 API hits/day as free trial.


Basic Authentication Your email and password are required for working with cda2sql API.
With each API call you must send the username, which is your email, and the password as Basic Authentication.
For security reasons, always use the https address as the access point to an API endpoint.
The authorization header with your Basic Auth will be automatically generated when you send the request.
Postman details how to send the username and password as Basic Auth.

Basic endpoint for all API calls:
API Endpoint Method You send to API API responds with
apiCDA2SQL POST Valid C-CDA document as XML Tables in JSON format for demographics, meds, labs, vitals, etc., each with uniquely identified rows that can be easily inserted into SQL databases (see code below)

The API detailed requires a POST (not a GET), so it won't work directly from the browser address bar. You need to send the C-CDA as XML in the body of an API POST call

apiCDA2SQL - POST example

Snapshots of the API request and response below are from Postman
Purpose The API parses one C-CDA document at a time into a tabular format suitable for databases


API Response



cda2sql will return an HTTP error when it encounters a problem processing your API call.
A more detailed message is provided in the HTTP error response body.

HTTP Error Error details you may find in the API response
Bad request File is not a valid C-CDA document
The server cannot process the request due to an apparent client error
401 - Unauthorized See Authentication
402 - Payment required Subscription expired.
Please renew your subscription at cda2sql
You have reached the maximum number of API calls for your account. Please wait till 7 pm ET for the daily counter to reset and consider increasing your subscription level and number of daily API hits at cda2sql
405 - Method not allowed You're trying GET instead of POST with your API call
504 - Load Balance error You are running a batch of API calls that takes more than 3 minutes to complete.
Try to shorten the execution time of a long process by breaking it into less-than-3-mins batches
500 - Server error Problem on our side.
Whoops...a slight distortion in our space time continuum...

Consume the cda2sql API while building your database

The following code snippets will:
1. Create an empty MySQL database with tables for meds, labs, vitals, etc.
2. Populate this MySQL database with information coming from cda2sql API responses using Python and SQL languages.

Create an empty MySQL database

Assuming you have access to a hosted MySQL environment, download the SQL script provided.
On your SQL server, create a new database named TESTcda2sql
Executing the SQL script will create a database with the following tables:

Populate the database with your C-CDA documents

Assuming you have a Python app that can access the MySQL database just created, the following Python function (download here) will send one C-CDA document to the API detailed above and will use the API response to populate the MySQL database.

Each time the above function runs, it creates a dynamic SQL INSERT command into a table in the database. This INSERT process is repeated for all the categories in the C-CDA .
This function parses one C-CDA into the database, so you can run it over your documents and automate this process.
One note before you start coding...if you intend to send the C-CDA documents in batches, make sure no batch takes more than 3 minutes, as this will throw an error 504 - Load Balance Error.