Form Submission API

CommCare's Submission API implements the OpenRosa standard Form Submission API for submitting XForms over HTTP/S. You can find details of the Form Submission API standard here.

Submitting forms

There are two ways to submit a form to CommCare HQ:

• As multipart/form-data; CommCare uses this method in J2ME.

• As the body of a post; CommCare does this on Android.

Below are sample commands for submitting an XForm saved in a file called "xform.xml" to the domain called "demo". (You will need to change these two values in the commands below to suit your own purposes.)

...

In a number of places, CommCare reporting relies on tagging form submissions with the application that they belong to. To tag a form submission with its application, submit it to its application's URL. e.g. "https://www.commcarehq.org/a/demo/receiver/[APPLICATION_ID]/"

The application ID can be found in the URL when editing the application. e.g. In the URL "https://www.commcarehq.org/a/demo/apps/view/952a0b480c7c10dde777b2485375d2237/" the application ID is "952a0b480c7c10dde777b2485375d2237".

...

  <n1:meta xmlns:n1="http://openrosa.org/jr/xforms">
    <n1:deviceID>commcare_37478fd5-2730-4a14-a847-84e8848a1ff5</n1:deviceID>
    <n1:timeStart>2020-06-08T18:38:13.855Z</n1:timeStart>
    <n1:timeEnd>2020-06-08T18:41:33.207Z</n1:timeEnd>
    <n1:username>exampleuser</n1:username>
    <n1:userID>de8cc5191f9b4e2a846069f0659fa35e</n1:userID>
    <n1:instanceID>dca03509-4446-41dc-8352-2bb6f8516c7b</n1:instanceID>
    <n2:appVersion xmlns:n2="http://commcarehq.org/xforms">CommCare Version 2.48. Build 461457</n2:appVersion>
  </n1:meta>

• "deviceID": Use the device ID to set an identifier for the source of the submitted data.

• "timeStart": When the user opened the form. If the form is built programmatically, "now" is a reasonable value.

• "timeEnd": When the user completed the form. Like "timeStart", "now" is a reasonable fallback.

• "username": The name of the user / mobile worker who submitted the form.

• "userID": The ID of the user / mobile worker who submitted the form.

• "instanceID" is a unique ID for this form submission. Create a new UUID for every form submission. This ID needs to be universally unique, so you will need to generate a new Version 4 UUID; do not use an auto-incrementing ID. If "instanceID" is not unique, if the ID is owned by your project space then the new form submission will replace the previous form submission, otherwise if it is not owned by your project space, the form submission will be rejected.

• "appVersion": If the form belongs to an app, this can offer useful context for its data. You can submit an empty node if it is not relevant.

Case management

The form above is simply a nested structure of answers to form questions. Case management is a powerful feature of CommCare that it is not using.

...

In addition to the response XML the HTTP response code is also important.

OpenRosa V 2.0

Example Success Response

<OpenRosaResponse xmlns="http://openrosa.org/http/response">
    <message nature="submit_success">   √   </message>
</OpenRosaResponse>

...

<OpenRosaResponse xmlns="http://openrosa.org/http/response">
    <message nature="submit_error">InvalidCaseIndex: Case '349580db10da4a67b7089c541742c88b' references non-existent case '9766f50abda94c26a4569df5ce6dda6d'</message>
</OpenRosaResponse>

OpenRosa V 3.0

Code Example

The submission_api_example repository on GitHub has an example script to illustrate how to use the Submission API to create CommCare cases. It also has a short explanation of what the code does, so that you can use it as a reference for implementing in your own language, or adapt it for your own use case.

...

https://www.commcarehq.org/a/demo/receiver/[APPLICATION ID]/

The application ID can ID can be found in the application edit URL. e.g. https://www.commcarehq.org/a/demo/apps/view/952a0b480c7c10dde777b2485375d2237/ → App ID = 952a0b480c7c10dde777b2485375d2237

...