Page Comparison

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, 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:

Code Block

language	bash

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"

...

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

ⁱⁿ

^the

^mapping

^but

^there

^were

^errors

^when

^uploading

^because

^of

^these

^values.",

^{"column":"owner_name",}

^"rows":

^[2,3,4]

^}]

^}

Versions Compared

Old Version 11

New Version Current

Key