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) |
|---|---|---|---|---|
| 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, | 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 | (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] }] } } |