Bulk Upload Case Data

This content has been moved.

Please visit ReadTheDocs for the latest version.

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:

Name	Description	Example	Required	Default (if optional)

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. Values: case_id or external_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, whichever is specified by the search_field	household_id	optional	case_id or external_id depending on search_field
create_new_cases	on 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	on	optional
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_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

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

^{(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]}

^}]

^}