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
external_idoptionalcase_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
onoptional
name_column

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

household_nameoptional

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.

NameDescriptionExample
code

200: Success

402: Warning

500: Fail

500

message

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):
{
   "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]
      }]
   }
}
  • No labels