1. REST API for COVID-19 Data ClearinghouseREST APIs for COVID-19 Data Clearinghouse
  2. Quick Start

Quick Start

Complete these tasks to set up your environment and use the COVID-19 Data Clearinghouse REST API to make your first upload and export.

Prerequisites

Prerequisite More Information
Install cURL Use cURL
Set up authentication Authenticate

Task 1: Send a test request

After you set up your REST client, you can attempt to generate an authorization token to test that your system is correctly set up.

This sample request, in JSON format, assumes you have been provisioned with the UPLOAD and EXPORT_NON_REDACTED scopes. Specify your actual scopes:

{  
  "clientID": "<your Client ID>",  
  "clientSecret": "<your Secret>",  
  "scopes": [    
    "UPLOAD",    
    "EXPORT_NON_REDACTED"        
  ]
}
The production server for the COVID-19 Data Clearinghouse is https://covdch-api.cdc.gov.

Note:

If you need to use the test server (UAT), contact your Data Clearinghouse administrator.
Make the request using cURL: 
curl -X POST -s "https://covdch-api.cdc.gov/v0/token/gen" 
-H "accept: application/json" 
-H "Content-Type: application/json" 
-d "{"clientID":"<your client ID>","clientSecret":"<your client secret>","scopes":["UPLOAD","EXPORT_NON_REDACTED"]}"

If the request is successful, then you receive a 200 response with a body that includes the token string and the expiration time code:

{    
  "token": "<token string>",    
  "expiration": 1634291135
}

Congratulations!

Task 2: Upload immunization records

The following snippet represents a text file of test immunization records.

VAX_EVENT_ID  EXT_TYPE  PPRL_ID  RECIP_ID  RECIP_FIRST_NAME  RECIP_MIDDLE_NAME  RECIP_LAST_NAME  ...
1458619	D         636954   Redacted  Redacted	   Redacted	    Redacted	  ...
2458618	D         636954   Redacted  Redacted	   Redacted	    Redacted	  ...
9458617	D	  636953   Redacted  Redacted	   Redacted	    Redacted	  ...
8458616	D         636953   Redacted  Redacted	   Redacted	    Redacted         ...

This cURL command assumes you have saved your authorization token in a variable called TOKEN and saved your text batch records filename in a variable called FILE. 

curl -X POST "https://covdch-api.cdc.gov/v0/upload/crvs/batch" -H "accept: application/json" 
-H "Authorization: $TOKEN" -H "Content-Type: text/plain" --data-binary @$FILE

The response demonstrates a particular use case that new users may encounter: This batch of records have already been uploaded. There are no validation errors because the data is in the correct form. There are four processing errors that indicate the records already exist and therefore cannot be accepted. If you attempt to re-upload a large batch, the response cannot display all the processing error messages. The ProcessingErrorsCount, however, will be accurate. 

{    
  "id": "<upload identifier>",    
    "totalRecords": 4,    
    "validationErrors": [],    
    "validationErrorsCount": 0,    
    "storageResult": {        
      "REDACTED_DB": {            
        "status": "SUCCESS",            
        "processingErrors": [                
          "storage=REDACTED_DB vaxEventID=1458619 recipId=636954 message=Record already exists",                
          "storage=REDACTED_DB vaxEventID=2458618 recipId=636954 message=Record already exists",                
          "storage=REDACTED_DB vaxEventID=9458617 recipId=636953 message=Record already exists",                
          "storage=REDACTED_DB vaxEventID=8458616 recipId=636953 message=Record already exists"            
        ],            
        "processedCount": 0,               
        "processingErrorsCount": 4        
      }    
  }
}

Task 3: Upload immunization records asynchronously

Uploading records to the Data Clearinghouse is a synchronous operation unless you use the asynchronous (Async) API. With Async, you can asynchronously upload new CVRS records in a zip file to the Data Clearinghouse. The asynchronous process is a more efficient and robust method for large file uploads.

This cURL command assumes you saved your authorization token in a variable called TOKEN and saved your CVRS batch records in a zip file (required) with the filename stored in a variable called FILE. 

curl -X POST "https://covdch-api.cdc.gov/v0/async/crvs/jobs" -H "accept: application/json" 
-H "Authorization: $TOKEN" -H "Content-Type: application/zip" --data-binary @$FILE

The quick QUEUED response indicates the call was successfully placed in the queue and, in this example, processing has not started:

{
    "id": "<job-id>",
    "status": "QUEUED",
    "totalRecords": -1,
    "validationErrors": [],
    "validationErrorsCount": -1,
    "storageResult": null
}

To get the status of the asynchronous job later, copy the job ID from the id field in the initial response and append it to the URL:

curl -X POST "https://covdch-api.cdc.gov/v0/async/crvs/<job-id>" -H "accept: application/json" 
-H "Authorization: $TOKEN"

In this small example, the returned status indicates the job is complete without errors.

{
    "id": "31979333-3f91-483b-8d3c-dcf098468598",
    "status": "COMPLETED",
    "totalRecords": 5,
    "validationErrors": [],
    "validationErrorsCount": 0,
    "storageResult": {
        "NON_REDACTED_DB": {
            "status": "SUCCESS",
            "processingErrors": [],
            "processedCount": 5,
            "processingErrorsCount": 0
        },
        "REDACTED_DB": {
            "status": "SUCCESS",
            "processingErrors": [],
            "processedCount": 5,
            "processingErrorsCount": 0
        }
    }
}
The API return statuses include:
  • QUEUED: The job is in the Async request job queue but not yet processed.
  • DE-QUEUED: The job has moved to processing.
  • VALIDATING: The job is currently in the validation processing phase.
  • PROCESSING: The job is in the data processing phase, which takes the most time.
  • COMPLETED: The upload job is done.

Task 4: Export immunization records

You can export immunization records from the Data Clearinghouse.

This cURL command assumes you have saved your authorization token in a variable called TOKEN. 

curl -X POST "https://covdch-api.cdc.gov/v0/export" -H "Accept: application/json" -H  "Authorization: $TOKEN" 
-H "Content-Type: application/json" -d "{"startDate": "2021/10/31", "endDate": "2021/10/31", "format": "HL7"}"

The response is a JSON document containing a single record in CVRS_RAW format. (The data below is strictly test data,):

{    "data": 
          "VAX_EVENT_ID\tEXT_TYPE\tPPRL_ID\tRECIP_ID\tRECIP_FIRST_NAME\tRECIP_MIDDLE_NAME\tRECIP_LAST_NAME\
           tRECIP_DOB\tRECIP_SEX\tRECIP_ADDRESS_STREET\tRECIP_ADDRESS_STREET_2\tRECIP_ADDRESS_CITY\
           tRECIP_ADDRESS_COUNTY\tRECIP_ADDRESS_STATE\tRECIP_ADDRESS_ZIP\tRECIP_RACE_1\tRECIP_RACE_2\
           tRECIP_RACE_3\tRECIP_RACE_4\tRECIP_RACE_5\tRECIP_RACE_6\tRECIP_ETHNICITY\tADMIN_DATE\tCVX\tNDC\
           tMVX\tLOT_NUMBER\tVAX_EXPIRATION\tVAX_ADMIN_SITE\tVAX_ROUTE\tDOSE_NUM\tVAX_SERIES_COMPLETE\
           .
           .
           .
           t21520\tNO\tUNK\tUNK\n"
}

Task 5: Browse the APIs

The main left-side navigation of the API documentation is organized around tasks. If you prefer to browse the API endpoints in a different order:
  1. Click All REST Endpoints under Introduction.
  2. Choose one of the Sort by options at the top of the page.