Bulk Upload Case Data API

Overview

Purpose: Performs bulk imports of case data through the Excel Case Data Importer to either create or update cases.

Base 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

Request & Response Details

Input Parameters

Name	Description	Example	Required	Default (if optional)
file	Path to the excel file containing Table Data	/home/username/household_case_upload.xlsx	yes
case_type	The case type to be assigned to created cases	household	yes
search_field	Whether to check for matches with existing cases against CommCareHQ’s internal case id or an external named id	external_id	optional	case_id
search_column	The column in the spreadsheet which will be matched against either the case_id or external_id	household_id	optional	case_id or external_id depending on search_field
create_new_cases	Whether to create new cases when no existing case matches the search_field	on	optional
name_column	The column in the spreadsheet which should be interpreted as the case name	household_name	optional

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.

Name

Description

Example

code

200: Success, 402: Warning, 500: Fail

500

message

Warning or Failure message

“Error processing your file. Submit a valid (.xlsx) file”

status_url

If an upload is successful, a URL to poll for the status of the processing (State: 2 - Complete, 3 - Error)

JSON result from hitting status url:
{
   "state": 2,
   "progress": {"percent": 0},
   "result": {
      "match_count": 0,
      "created_count": 15
      "num_chunks": 0,
      "errors": []
   }
}

JSON result where upload succeeded but encountered business errors:
{
   "state": 2,
   "progress": {"percent": 0},
   "result": {
      "match_count": 0,
      "created_count": 0,
      "num_chunks": 0,
      "errors": [{
         "title": "Invalid Owner Name",
         "description": "Owner name was used in the mapping but there were errors when uploading because of these values.",
         "column": "owner_name",
         "rows": [2, 3, 4]
      }]
   }
}