Purpose: Performs Bulk Imports of Case Data through the Excel Case Data Importer to either create or update cases

URL: https://www.commcarehq.org/a/[domain]/importer/excel/bulk_upload_api/

Method: POST

Body: Multipart Form Submission with File

Authorization: API Token or Basic Authorization

Input Parameters:

NameDescriptionExampleRequiredDefault (if optional)
filePath to the excel file containing Table Data/home/username/household_case_upload.xlsxyes
case_typeThe case type to be assigned to created caseshouseholdyes
search_fieldWhether to check for matches with existing cases against CommCareHQ's
internal case id or an external named id. Values: case_id or external_id
search_columnThe column in the spreadsheet which will be matched against either the
case_id or external_id, whichever is specified by the search_field
household_idoptionalcase_id or external_id depending on search_field
create_new_caseson if the upload should create new cases when no existing case matches the
search_field. off if the upload should only update existing cases, and ignore
rows with no match

The column in the spreadsheet which should be interpreted as the case name,
if none is provided the importer will use any column with the id name.

Note: This field will only be added as the case name, and will not appear
as a property with its original column name


Sample cURL request:

curl -v https://www.commcarehq.org/a/[domain]/importer/excel/bulk_upload_api/ -u user@domain.com:password
     -F "file=@household_case_upload.xlsx"
     -F "case_type=household"
     -F "search_field=external_id"
     -F "search_column=household_id"
     -F "create_new_cases=on"

(You may also omit the ':' and password and curl will request it. This will have the benefit of not showing your password on your screen or storing it in your history.)

Note: Uploads are subject to the same restrictions as the Excel Importer User Interface, but with much more limited feedback. It is a good idea to test uploads there first to debug any issues, then use the Bulk Upload API to automate future imports once they are working as expected.

Response: JSON output with following Parameters. Note that a success code indicates that the upload was processed, but it may have encountered business-level problems with the import's data, such as uploading a case to an invalid location. Also note that these parameters may change to support for better error handling, so do not plan around them.


200: Success

402: Warning

500: Fail



Warning or Failure message"Error processing your file. Submit a valid (.xlsx) file"
status_urlIf an upload is successful, a URL to poll for the status of the processing.

State: 2 - Complete, 3 - Error
(Example of JSON result from hitting status url):
   "state": 2,
   "progress": {"percent": 0},
   "result": {
      "match_count": 0,
      "created_count": 15,
      "num_chunks": 0,
      "errors": []
(Example of JSON result where upload succeeded but encountered business errors):
   "progress": {"percent":0},
   "result": {
      "errors": [{
         "title":"Invalid Owner Name",
         "description":"Owner name was used in the mapping but there were errors when uploading because of these values.",
         "rows": [2,3,4]
  • No labels