Export API

Deprecated

This API is deprecated. You should use the CommCare Data Export Tool (DET) or the List Forms API instead.

File size limit

Exports we will serve via this API have a file size limitation of 10MB. Files larger than this may not successfully download.

Form Data Export

For export of form data, head on over to (where you will replace [domain] with the name of your project domain):

https://www.commcarehq.org/a/[domain]/data/excel_export_data/

where you'll see all of your possible exports, including custom exports you can configure right there. You can click on any of the Download buttons to download manually, but to do this programmatically you'll want the url, so right click and select "Copy Link Address" (or the equivalent in your browser). That's the url you should start from.

For form exports you can use the following URL parameters:

http://www.commcarehq.org/a/[domain]/reports/export/?export_tag="[form xmlns]"&previous_export=[previous export]&format=[format]

Parameter	Value	Examples

Parameter	Value	Examples
export_tag	The xmlns of the form to download.	%22http://openrosa.org/foo/my/form/xmlns%22 (NOTE the escaped quotes around the form xmlns. It will not work without them.
previous_export	The previous export id (optional)	abc123fda2b3c2gad5125
format	Export format (optional)	csv = csv, xlsx = Excel 2007 (this is the default), xls = Excel (previous version), html = HTML view, json = JSON dump, raw = zipped xml submission files. No other values are allowed.
include_errors	Whether to include errors (duplicates or things the server couldn't parse) (option)	True, False (default)
max_column_size	The maximum length (in characters) that should be used for the column headers. Headers beyond this size will be truncated.	any number, the default is 2000

The "previous_export" parameter is optional, but can be used to download partial data. With each download, CommCareHQ will return this value in the "X-CommCareHQ-Export-Token" header in the response. You can save this token and pass it back and only data since your last download will be returned. This parameter does not work with the raw export format.

If there is no data the response code will be a 302 redirect to the export listing page. Custom Export uses a different URL but the same url params except for export_tag, which is unnecessary.

Cases, Referrals, and Users Export

To export your Cases, Referrals, and Users (as 3 CSV files zipped together) use the following URL:

https://www.commcarehq.org/a/[domain]/reports/download/cases/?format=csv

You can use the following url parameter:

Parameter	Value	Examples

Parameter	Value	Examples
include_closed	true/false (defaults to false)	include_closed=true
format	(same as above)

Using with curl from the linux command line

The export URLs support HTTP-Digest authentication in addition to the normal session-based authentication used on the rest of CommCare HQ. This makes it easy to access these urls programmatically. For example, with curl you can use the --digest flag and specify a username with -u as follows:

Here, you can only use your web login to authenticate, as the individual CHWs do not have permission to see everyone's data. (And their passwords tend to be far less secure.) Make sure to use the correct URL parameters described above in your URL. The file will be saved to the file specified, but the verbose outputs, including headers, will be printed to the screen. If you want to use the checkpointing feature (not available for case export), look for a line something like

near the bottom. Save the token, and pass it as previous_export in the next curl request you make to get only updates.

In order to get this token programmatically, you could redirect stderr to a file (let's say headers.txt) and then use grep and sed as follows to strip the other text on that line, and put that in (say) token.txt:

This will leave you with the a directory with the csv files in the 'data' directory, and the export token (to be used next time) in token.txt.