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:

  1. Import App — Upload an application source JSON file to create a new application, or update an existing application in place when an app_id is supplied.

  2. Upload Multimedia — Upload a ZIP archive of multimedia files for an imported application (processed asynchronously).

  3. 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 application. On update, renames the app if given; otherwise the existing name is kept.

yes on create, optional on update

app_id

ID of an existing application to update in place. When omitted, a new application is created.

no

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)."
  ]
}

Sample cURL Request — Update

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_id=abc123def456..."

Response (200 OK) — Update

When app_id is supplied, the existing application is updated in place and its version is bumped. The response returns the new version:

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

As with the create response, if the update succeeds but encounters non-fatal issues, the response also includes a warnings field.

Error Responses

Status

Condition

400

Missing app_file; missing app_name when creating; the uploaded file is not valid JSON; or (on update) the uploaded source’s app type is incompatible with the existing app

403

Insufficient permissions

404

app_id was supplied but no matching application exists in the domain

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