Import Application API

Overview

Purpose

Import an application from a JSON source file, and optionally upload multimedia assets for the imported application.

This API provides three endpoints:

Import App — Upload an application source JSON file to create a new application.
Upload Multimedia — Upload a ZIP archive of multimedia files for an imported application (processed asynchronously).
Poll Multimedia Status — Check the progress of an asynchronous multimedia upload.

Authorization

API Key, Basic, Digest, or OAuth authentication. See API Authentication.

Permission Required

Edit Apps

Import App

Base URL

https://www.commcarehq.org/a/[domain]/apps/api/import_app/

Method: POST
Body: Multipart Form Submission with File

Request & Response Details

Input Parameters

Name	Description	Required
app_file	The application source JSON file	yes
app_name	Name for the imported application	yes

Sample cURL Request

curl -X POST https://www.commcarehq.org/a/[domain]/apps/api/import_app/ \
     -u user@domain.com:password \
     -F "app_file=@app_source.json" \
     -F "app_name=My Imported App"

Response (201 Created)

{
  "success": true,
  "app_id": "abc123def456..."
}

If the import succeeds but encounters non-fatal issues (e.g., missing multimedia references or UCR configuration), the response includes a warnings field:

{
  "success": true,
  "app_id": "abc123def456...",
  "warnings": [
    "Copying the application succeeded, but the application is missing multimedia file(s)."
  ]
}

Error Responses

Status	Condition
400	Missing `app_file` or `app_name`, or the uploaded file is not valid JSON
403	Insufficient permissions
405	Request method is not POST

Upload Multimedia

Base URL

https://www.commcarehq.org/a/[domain]/apps/api/[app_id]/multimedia/

Method: POST
Body: Multipart Form Submission with File

Request & Response Details

Input Parameters

Name	Description	Required
bulk_upload_file	A ZIP archive containing multimedia files (images, audio, video)	yes

Sample cURL Request

curl -X POST https://www.commcarehq.org/a/[domain]/apps/api/[app_id]/multimedia/ \
     -u user@domain.com:password \
     -F "bulk_upload_file=@multimedia.zip"

Response (200 OK)

The multimedia upload is processed asynchronously. The response includes a processing_id that can be used to poll for status.

{
  "success": true,
  "processing_id": "dl-abc123def456..."
}

Error Responses

Status	Condition
400	Missing `bulk_upload_file`, file is not a valid ZIP, or ZIP is corrupt
403	Insufficient permissions
404	Application not found in the specified domain
405	Request method is not POST

Poll Multimedia Status

Base URL

https://www.commcarehq.org/a/[domain]/apps/api/[app_id]/multimedia/status/[processing_id]/

Method: GET

Request & Response Details

Sample cURL Request

curl https://www.commcarehq.org/a/[domain]/apps/api/[app_id]/multimedia/status/[processing_id]/ \
     -u user@domain.com:password

Response (200 OK) — In Progress

{
  "success": true,
  "complete": false,
  "in_celery": true,
  "progress": {
    "percent": 50,
    "current": 5,
    "total": 10
  },
  "errors": [],
  "processing_id": "dl-abc123def456..."
}

Response (200 OK) — Complete

When processing is complete, the response includes details about matched and unmatched files:

{
  "success": true,
  "complete": true,
  "in_celery": false,
  "progress": {
    "percent": 100,
    "current": 10,
    "total": 10
  },
  "errors": [],
  "processing_id": "dl-abc123def456...",
  "matched_count": 8,
  "unmatched_count": 2,
  "total_files": 10,
  "processed_files": 10,
  "image_count": 6,
  "audio_count": 2,
  "video_count": 0,
  "matched_files": {
    "CommCareImage": ["..."],
    "CommCareAudio": ["..."],
    "CommCareVideo": []
  },
  "unmatched_files": [
    {"path": "images/extra.png", "reason": "..."}
  ],
  "skipped_files": []
}

Error Responses

Status	Condition
403	Insufficient permissions
404	Application not found, or processing ID not found / expired
500	The multimedia processing task failed