Submission Management

Submissions are filled-out forms (also called Instances in some other ODK documentation). Each is associated with a particular Form (and in many cases with a particular version of a Form), and is also created out of a standard XML format based on the Form itself. Submissions can be sent with many accompanying multimedia attachments, such as photos taken in the course of the survey. Once created, the Submissions themselves as well as their attachments can be retrieved through this API.

These subsections cover only the modern RESTful API resources involving Submissions. For documentation on the OpenRosa submission endpoint (which can be used to submit Submissions), or the OData endpoint (which can be used to retrieve and query submission data), see those sections below.

Like Forms, Submissions can have versions. Each Form has an overall xmlFormId that represents the Form as a whole, and each version has a version that identifies that particular version. Often, when fetching data by the xmlFormId alone, information from the latest Form version is included in the response.

Similarly with Submissions, the instanceId each Submission is first submitted with will always represent that Submission as a whole. Each version of the Submission, though, has its own instanceId. Sometimes, but not very often, when getting information about the Submission by only its overall instanceId, information from the latest Submission version is included in the response.

Submissions

Submissions are available as a subresource under Forms. So, for instance, /v1/projects/1/forms/myForm/submissions refers only to the Submissions that have been submitted to the Form myForm.

Once created (which, like with Forms, is done by way of their XML data rather than a JSON description), it is possible to retrieve and export Submissions in a number of ways, as well as to access the multimedia Attachments associated with each Submission.

Listing all Submissions on a Form

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions

Currently, there are no paging or filtering options, so listing Submissions will get you every Submission in the system, every time.

This endpoint supports retrieving extended metadata; provide a header X-Extended-Metadata: true to return a submitter data object alongside the submitterId Actor ID reference.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple

Response

HTTP Status: 200

Content Type: application/json

Example

[
  {
    "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "submitterId": 23,
    "deviceId": "imei:123456",
    "userAgent": "Enketo/3.0.4",
    "reviewState": "approved",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "updatedAt": "2018-03-21T12:45:02.312Z",
    "currentVersion": {
      "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
      "instanceName": "village third house",
      "submitterId": 23,
      "deviceId": "imei:123456",
      "userAgent": "Enketo/3.0.4",
      "createdAt": "2018-01-19T23:58:03.395Z",
      "current": true
    }
  }
]

Schema

array instanceId string The instanceId of the Submission, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 submitterId number The ID of the Actor (App User, User, or Public Link) that originally submitted this Submission. Example: 23 deviceId string The self-identified deviceId of the device that collected the data, sent by it upon submission to the server. The initial submission deviceId will be returned here. Example: imei:123456 userAgent string The self-identified userAgent of the device that collected the data, sent by it upon submission to the server. The initial submission userAgent will be returned here. Example: Enketo/3.0.4 reviewState object The current review state of the submission. expand null string edited string hasIssues string rejected string approved string createdAt string ISO date format. The time that the server received the Submission. Example: 2018-01-19T23:58:03.395Z updatedAt string ISO date format. null when the Submission is first created, then updated when the Submission's XML data or metadata is updated. Example: 2018-03-21T12:45:02.312Z currentVersion object expand instanceId string The instanceId of the Submission version, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 instanceName string The instanceName, if any, given by the Submission XML in the metadata section. Example: village third house submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. Example: 23 deviceId string The self-identified deviceId of the device that submitted the Submission version. Example: imei:123456 userAgent string The self-identified userAgent of the device that submitted the Submission version. Example: Enketo/3.0.4 createdAt string ISO date format. The time that the server received the Submission version. Example: 2018-01-19T23:58:03.395Z current boolean Whether the version is current or not. Example: true

HTTP Status: 200

Content Type: application/json; extended

Example

[
  {
    "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "submitterId": 23,
    "deviceId": "imei:123456",
    "userAgent": "Enketo/3.0.4",
    "reviewState": "approved",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "updatedAt": "2018-03-21T12:45:02.312Z",
    "currentVersion": {
      "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
      "instanceName": "village third house",
      "submitterId": 23,
      "deviceId": "imei:123456",
      "userAgent": "Enketo/3.0.4",
      "createdAt": "2018-01-19T23:58:03.395Z",
      "current": true
    },
    "submitter": {
      "createdAt": "2018-04-18T23:19:14.802Z",
      "displayName": "My Display Name",
      "id": 115,
      "type": "user",
      "updatedAt": "2018-04-18T23:42:11.406Z",
      "deletedAt": "2018-04-18T23:42:11.406Z"
    }
  }
]

Schema

array instanceId string The instanceId of the Submission, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 submitterId number The ID of the Actor (App User, User, or Public Link) that originally submitted this Submission. Example: 23 deviceId string The self-identified deviceId of the device that collected the data, sent by it upon submission to the server. The initial submission deviceId will be returned here. Example: imei:123456 userAgent string The self-identified userAgent of the device that collected the data, sent by it upon submission to the server. The initial submission userAgent will be returned here. Example: Enketo/3.0.4 reviewState object The current review state of the submission. expand null string edited string hasIssues string rejected string approved string createdAt string ISO date format. The time that the server received the Submission. Example: 2018-01-19T23:58:03.395Z updatedAt string ISO date format. null when the Submission is first created, then updated when the Submission's XML data or metadata is updated. Example: 2018-03-21T12:45:02.312Z currentVersion object expand instanceId string The instanceId of the Submission version, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 instanceName string The instanceName, if any, given by the Submission XML in the metadata section. Example: village third house submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. Example: 23 deviceId string The self-identified deviceId of the device that submitted the Submission version. Example: imei:123456 userAgent string The self-identified userAgent of the device that submitted the Submission version. Example: Enketo/3.0.4 createdAt string ISO date format. The time that the server received the Submission version. Example: 2018-01-19T23:58:03.395Z current boolean Whether the version is current or not. Example: true submitter object expand createdAt string ISO date format Example: 2018-04-18 23:19:14.802000+00:00 displayName string All Actors, regardless of type, have a display name Example: My Display Name id number Example: 115.0 type enum The type of actor expand user string field_key string public_link string singleUse string updatedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00 deletedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00

HTTP Status: 403

Content Type: application/json; extended

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Creating a Submission

POST /v1/projects/{projectId}/forms/{xmlFormId}/submissions

To create a Submission by REST rather than over the OpenRosa interface, you may POST the Submission XML to this endpoint. The request must have an XML Content-Type (text/xml or application/xml).

Unlike the OpenRosa Form Submission API, this interface does not accept Submission attachments upon Submission creation. Instead, the server will determine which attachments are expected based on the Submission XML, and you may use the endpoints found in the following section to add the appropriate attachments and check the attachment status and content.

If the XML is unparseable or there is some other input problem with your data, you will get a 400 error in response. If a submission already exists with the given instanceId, you will get a 409 error in response.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
deviceID (query)	string Optionally record a particular deviceID associated with this submission. It is recorded along with the data, but Central does nothing more with it. Example: b1628661-65ed-4cab-8e30-19c17fef2de0

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "submitterId": 23,
  "deviceId": "imei:123456",
  "userAgent": "Enketo/3.0.4",
  "reviewState": "approved",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "updatedAt": "2018-03-21T12:45:02.312Z",
  "currentVersion": {
    "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "instanceName": "village third house",
    "submitterId": 23,
    "deviceId": "imei:123456",
    "userAgent": "Enketo/3.0.4",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "current": true
  }
}

Schema

object instanceId string The instanceId of the Submission, given by the Submission XML. submitterId number The ID of the Actor (App User, User, or Public Link) that originally submitted this Submission. deviceId string The self-identified deviceId of the device that collected the data, sent by it upon submission to the server. The initial submission deviceId will be returned here. userAgent string The self-identified userAgent of the device that collected the data, sent by it upon submission to the server. The initial submission userAgent will be returned here. reviewState enum The current review state of the submission. expand None string edited string hasIssues string rejected string approved string createdAt string ISO date format. The time that the server received the Submission. updatedAt string ISO date format. null when the Submission is first created, then updated when the Submission's XML data or metadata is updated. currentVersion object The current version of the Submission. expand instanceId string The instanceId of the Submission version, given by the Submission XML. instanceName string The instanceName, if any, given by the Submission XML in the metadata section. submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. deviceId string The self-identified deviceId of the device that submitted the Submission version. userAgent string The self-identified userAgent of the device that submitted the Submission version. createdAt string ISO date format. The time that the server received the Submission version. current boolean Whether the version is current or not.

HTTP Status: 400

Content Type: application/json

Example

{
  "code": "400",
  "message": "Could not parse the given data (2 chars) as json."
}

Schema

object code string details object a subobject that contains programmatically readable details about this error message string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

HTTP Status: 409

Content Type: application/json

Example

{
  "code": "409.1",
  "message": "A resource already exists with id value(s) of 1."
}

Schema

object code string message string

Getting Submission metadata

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}

Like how Forms are addressed by their XML formId, individual Submissions are addressed in the URL by their instanceId.

As of version 1.4, a deviceId and userAgent will also be returned with each submission. The client device may transmit these extra metadata when the data is submitted. If it does, those fields will be recognized and returned here for reference. Here, only the initial deviceId and userAgent will be reported. If you wish to see these metadata for any submission edits, including the most recent edit, you will need to list the versions.

As of version 2023.2, this API returns currentVersion that contains metadata of the most recent version of the Submission.

This endpoint supports retrieving extended metadata; provide a header X-Extended-Metadata: true to return a submitter data object alongside the submitterId Actor ID reference.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "submitterId": 23,
  "deviceId": "imei:123456",
  "userAgent": "Enketo/3.0.4",
  "reviewState": "approved",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "updatedAt": "2018-03-21T12:45:02.312Z",
  "currentVersion": {
    "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "instanceName": "village third house",
    "submitterId": 23,
    "deviceId": "imei:123456",
    "userAgent": "Enketo/3.0.4",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "current": true
  }
}

Schema

object instanceId string The instanceId of the Submission, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 submitterId number The ID of the Actor (App User, User, or Public Link) that originally submitted this Submission. Example: 23 deviceId string The self-identified deviceId of the device that collected the data, sent by it upon submission to the server. The initial submission deviceId will be returned here. Example: imei:123456 userAgent string The self-identified userAgent of the device that collected the data, sent by it upon submission to the server. The initial submission userAgent will be returned here. Example: Enketo/3.0.4 reviewState object The current review state of the submission. expand null string edited string hasIssues string rejected string approved string createdAt string ISO date format. The time that the server received the Submission. Example: 2018-01-19T23:58:03.395Z updatedAt string ISO date format. null when the Submission is first created, then updated when the Submission's XML data or metadata is updated. Example: 2018-03-21T12:45:02.312Z currentVersion object expand instanceId string The instanceId of the Submission version, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 instanceName string The instanceName, if any, given by the Submission XML in the metadata section. Example: village third house submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. Example: 23 deviceId string The self-identified deviceId of the device that submitted the Submission version. Example: imei:123456 userAgent string The self-identified userAgent of the device that submitted the Submission version. Example: Enketo/3.0.4 createdAt string ISO date format. The time that the server received the Submission version. Example: 2018-01-19T23:58:03.395Z current boolean Whether the version is current or not. Example: true

HTTP Status: 200

Content Type: application/json; extended

Example

{
  "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "submitterId": 23,
  "deviceId": "imei:123456",
  "userAgent": "Enketo/3.0.4",
  "reviewState": "approved",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "updatedAt": "2018-03-21T12:45:02.312Z",
  "currentVersion": {
    "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "instanceName": "village third house",
    "submitterId": 23,
    "deviceId": "imei:123456",
    "userAgent": "Enketo/3.0.4",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "current": true
  },
  "submitter": {
    "createdAt": "2018-04-18T23:19:14.802Z",
    "displayName": "My Display Name",
    "id": 115,
    "type": "user",
    "updatedAt": "2018-04-18T23:42:11.406Z",
    "deletedAt": "2018-04-18T23:42:11.406Z"
  }
}

Schema

object instanceId string The instanceId of the Submission, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 submitterId number The ID of the Actor (App User, User, or Public Link) that originally submitted this Submission. Example: 23 deviceId string The self-identified deviceId of the device that collected the data, sent by it upon submission to the server. The initial submission deviceId will be returned here. Example: imei:123456 userAgent string The self-identified userAgent of the device that collected the data, sent by it upon submission to the server. The initial submission userAgent will be returned here. Example: Enketo/3.0.4 reviewState object The current review state of the submission. expand null string edited string hasIssues string rejected string approved string createdAt string ISO date format. The time that the server received the Submission. Example: 2018-01-19T23:58:03.395Z updatedAt string ISO date format. null when the Submission is first created, then updated when the Submission's XML data or metadata is updated. Example: 2018-03-21T12:45:02.312Z currentVersion object expand instanceId string The instanceId of the Submission version, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 instanceName string The instanceName, if any, given by the Submission XML in the metadata section. Example: village third house submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. Example: 23 deviceId string The self-identified deviceId of the device that submitted the Submission version. Example: imei:123456 userAgent string The self-identified userAgent of the device that submitted the Submission version. Example: Enketo/3.0.4 createdAt string ISO date format. The time that the server received the Submission version. Example: 2018-01-19T23:58:03.395Z current boolean Whether the version is current or not. Example: true submitter object expand createdAt string ISO date format Example: 2018-04-18 23:19:14.802000+00:00 displayName string All Actors, regardless of type, have a display name Example: My Display Name id number Example: 115.0 type enum The type of actor expand user string field_key string public_link string singleUse string updatedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00 deletedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00

HTTP Status: 301

Content Type: text/html

Example

<Redirects to correct Submission URL>

Schema

string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Updating Submission Data

PUT /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}

(introduced: version 1.2)

You can use this endpoint to submit updates to an existing submission.

The instanceId that is submitted with the initial version of the submission is used permanently to reference that submission logically, which is to say the initial submission and all its subsequent versions. Each subsequent version will also provide its own instanceId. This instanceId becomes that particular version's identifier.

To perform an update, you need to provide in the submission XML an additional deprecatedID metadata node with the instanceID of the particular and current submission version you are replacing. If the deprecatedID you give is anything other than the identifier of the current version of the submission at the time the server receives it, you will get a 409 Conflict back. You can get the current version instanceID by getting the current XML of the submission.

The XML data you send will replace the existing data entirely. All of the data must be present in the updated XML.

When you create a new submission version, any uploaded media files attached to the current version that match expected attachment names in the new version will automatically be copied over to the new version. So if you don't make any changes to media files, there is no need to resubmit them. You can get information about all the submission versions from the /versions subresource.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being updated. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "submitterId": 23,
  "deviceId": "imei:123456",
  "userAgent": "Enketo/3.0.4",
  "reviewState": "approved",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "updatedAt": "2018-03-21T12:45:02.312Z",
  "currentVersion": {
    "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "instanceName": "village third house",
    "submitterId": 23,
    "deviceId": "imei:123456",
    "userAgent": "Enketo/3.0.4",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "current": true
  }
}

Schema

object instanceId string The instanceId of the Submission, given by the Submission XML. submitterId number The ID of the Actor (App User, User, or Public Link) that originally submitted this Submission. deviceId string The self-identified deviceId of the device that collected the data, sent by it upon submission to the server. The initial submission deviceId will be returned here. userAgent string The self-identified userAgent of the device that collected the data, sent by it upon submission to the server. The initial submission userAgent will be returned here. reviewState enum The current review state of the submission. expand None string edited string hasIssues string rejected string approved string createdAt string ISO date format. The time that the server received the Submission. updatedAt string ISO date format. null when the Submission is first created, then updated when the Submission's XML data or metadata is updated. currentVersion object The current version of the Submission. expand instanceId string The instanceId of the Submission version, given by the Submission XML. instanceName string The instanceName, if any, given by the Submission XML in the metadata section. submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. deviceId string The self-identified deviceId of the device that submitted the Submission version. userAgent string The self-identified userAgent of the device that submitted the Submission version. createdAt string ISO date format. The time that the server received the Submission version. current boolean Whether the version is current or not.

HTTP Status: 400

Content Type: application/json

Example

{
  "code": "400",
  "message": "Could not parse the given data (2 chars) as json."
}

Schema

object code string details object a subobject that contains programmatically readable details about this error message string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

HTTP Status: 409

Content Type: application/json

Example

{
  "code": "409.1",
  "message": "A resource already exists with id value(s) of 1."
}

Schema

object code string message string

Updating Submission metadata

PATCH /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}

Currently, the only updatable metadata on a Submission is its reviewState. To update the submission data itself, please see Updating Submission data.

Starting with Version 2022.3, changing the reviewState of a Submission to approved can create an Entity in a Dataset if the corresponding Form maps Dataset Properties to Form Fields. If an Entity is created successfully then an entity.create event is logged in Audit logs, else entity.error is logged.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "submitterId": 23,
  "deviceId": "imei:123456",
  "userAgent": "Enketo/3.0.4",
  "reviewState": "approved",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "updatedAt": "2018-03-21T12:45:02.312Z",
  "currentVersion": {
    "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "instanceName": "village third house",
    "submitterId": 23,
    "deviceId": "imei:123456",
    "userAgent": "Enketo/3.0.4",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "current": true
  }
}

Schema

object instanceId string The instanceId of the Submission, given by the Submission XML. submitterId number The ID of the Actor (App User, User, or Public Link) that originally submitted this Submission. deviceId string The self-identified deviceId of the device that collected the data, sent by it upon submission to the server. The initial submission deviceId will be returned here. userAgent string The self-identified userAgent of the device that collected the data, sent by it upon submission to the server. The initial submission userAgent will be returned here. reviewState enum The current review state of the submission. expand None string edited string hasIssues string rejected string approved string createdAt string ISO date format. The time that the server received the Submission. updatedAt string ISO date format. null when the Submission is first created, then updated when the Submission's XML data or metadata is updated. currentVersion object The current version of the Submission. expand instanceId string The instanceId of the Submission version, given by the Submission XML. instanceName string The instanceName, if any, given by the Submission XML in the metadata section. submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. deviceId string The self-identified deviceId of the device that submitted the Submission version. userAgent string The self-identified userAgent of the device that submitted the Submission version. createdAt string ISO date format. The time that the server received the Submission version. current boolean Whether the version is current or not.

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Deleting a Submission

DELETE /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}

When a Submission is deleted, there is a period of time (30 days) during which it can be restored. After this time, all of its resources and attachments are automatically purged. Purging deleted Submissions can also be triggered from the command line.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "success": true
}

Schema

object success boolean

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

HTTP Status: 404

Content Type: application/json

Example

{
  "code": "404.1",
  "message": "Could not find the resource you were looking for."
}

Schema

object code string message string

Restoring a deleted Submission

POST /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/restore

Submissions that have been recently soft-deleted and not yet purged can be restored using this endpoint.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "success": true
}

Schema

object success boolean

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

HTTP Status: 404

Content Type: application/json

Example

{
  "code": "404.1",
  "message": "Could not find the resource you were looking for."
}

Schema

object code string message string

Retrieving Submission XML

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}.xml

To get only the XML of the Submission rather than all of the details with the XML as one of many properties, just add .xml to the end of the request URL.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 200

Content Type: application/xml

Example

<data id="simple">
  <orx:meta><orx:instanceID>uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44</orx:instanceID></orx:meta>
  <name>Alice</name>
  <age>32</age>
</data>

Schema

string

Getting an Enketo Edit URL

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/edit

(introduced: version 1.2)

This endpoint redirects the user to an Enketo-powered page that allows the user to interactively edit the submission. Once the user is satisfied, they can perform the submission update directly through the Enketo interface.

The Enketo instance is already hosted inside of ODK Central. There is no reason to create or use a separate Enketo installation.

This endpoint is intended for use by the Central administration frontend and will not work without it. In particular, the user must be logged into the Central administration site for Enketo editing to work. If there is no Central authentication cookie present when Enketo is loaded, the browser will then be redirected by Enketo to a Central login page.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being updated. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Exporting Form Submissions to CSV

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions.csv.zip

To export all the Submission data associated with a Form, just add .csv.zip to the end of the listing URL. The response will be a ZIP file containing one or more CSV files, as well as all multimedia attachments associated with the included Submissions.

You can exclude the media attachments from the ZIP file by specifying ?attachments=false.

If Project Managed Encryption is being used, additional querystring parameters may be provided in the format {keyId}={passphrase} for any number of keys (eg 1=secret&4=password). This will decrypt any records encrypted under those managed keys. Submissions encrypted under self-supplied keys will not be decrypted. Note: if you are building a browser-based application, please consider the alternative POST endpoint, described in the following section.

If a passphrase is supplied but is incorrect, the entire request will fail. If a passphrase is not supplied but encrypted records exist, only the metadata for those records will be returned, and they will have a status of not decrypted.

If you are running an unsecured (HTTP rather than HTTPS) Central server, it is not a good idea to export data this way as your passphrase and the decrypted data will be sent plaintext over the network.

You can use an OData-style $filter query to filter the submissions that will appear in the ZIP file. This is a bit awkward, since this endpoint has nothing to do with OData, but since we already must recognize the OData syntax, it is less strange overall for now not to invent a whole other one here. Only a subset of the $filter features are available; please see the linked section for more information.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
attachments (query)	boolean Set to false to exclude media attachments from the export. Example: true
$filter (query)	string If provided, will filter responses to those matching the given OData query. Only certain fields are available to reference. The operators lt, le, eq, neq, ge, gt, not, and, and or are supported, and the built-in functions now, year, month, day, hour, minute, second. Example: year(__system/submissionDate) lt year(now())
groupPaths (query)	boolean Set to false to remove group path prefixes from field header names (eg instanceID instead of meta-instanceID). This behavior mimics a similar behavior in ODK Briefcase. Example: true
deletedFields (query)	boolean Set to true to restore all fields previously deleted from this form for this export. All known fields and data for those fields will be merged and exported. Example: false
splitSelectMultiples (query)	boolean Set to true to create a boolean column for every known select multiple option in the export. The option name is in the field header, and a 0 or a 1 will be present in each cell indicating whether that option was checked for that row. This behavior mimics a similar behavior in ODK Briefcase. Example: false

Response

HTTP Status: 400

Content Type: application/json

Example

{
  "code": "400",
  "message": "Could not parse the given data (2 chars) as json."
}

Schema

object code string details object a subobject that contains programmatically readable details about this error message string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Exporting Form Submissions to CSV via POST

POST /v1/projects/{projectId}/forms/{xmlFormId}/submissions.csv.zip

This non-REST-compliant endpoint is provided for use with Project Managed Encryption. In every respect, it behaves identically to the GET endpoint described in the previous section, except that it works over POST. This is necessary because for browser-based applications, it is a dangerous idea to simply link the user to /submissions.csv.zip?2=supersecretpassphrase because the browser will remember this route in its history and thus the passphrase will become exposed. This is especially dangerous as there are techniques for quickly learning browser-visited URLs of any arbitrary domain.

You can exclude the media attachments from the ZIP file by specifying ?attachments=false.

And so, for this POST version of the Submission CSV export endpoint, the passphrases may be provided via POST body rather than querystring. Two formats are supported: form URL encoding (application/x-www-form-urlencoded) and JSON. In either case, the keys should be the keyIds and the values should be the passphrases, as with the GET version above.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
attachments (query)	boolean Set to false to exclude media attachments from the export. Example: true
$filter (query)	string If provided, will filter responses to those matching the given OData query. Only certain fields are available to reference. The operators lt, le, eq, neq, ge, gt, not, and, and or are supported, and the built-in functions now, year, month, day, hour, minute, second. Example: year(__system/submissionDate) lt year(now())
groupPaths (query)	boolean Set to false to remove group path prefixes from field header names (eg instanceID instead of meta-instanceID). This behavior mimics a similar behavior in ODK Briefcase. Example: true
deletedFields (query)	boolean Set to true to restore all fields previously deleted from this form for this export. All known fields and data for those fields will be merged and exported. Example: false
splitSelectMultiples (query)	boolean Set to true to create a boolean column for every known select multiple option in the export. The option name is in the field header, and a 0 or a 1 will be present in each cell indicating whether that option was checked for that row. This behavior mimics a similar behavior in ODK Briefcase. Example: false

Response

HTTP Status: 400

Content Type: application/json

Example

{
  "code": "400",
  "message": "Could not parse the given data (2 chars) as json."
}

Schema

object code string details object a subobject that contains programmatically readable details about this error message string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Exporting Root Data to Plain CSV

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions.csv

(introduced: version 1.1)

The above submission endpoints will give you a ZIP file with the submission data in it. This is necessary to provide all the possible related repeat table files, as well as the media files associated with the submissions. But ZIP files can be difficult to work with, and many Forms have no repeats nor media attachments.

To export just the root table (no repeat data nor media files), you can call this endpoint instead, which will directly give you CSV data.

Please see the above endpoint for notes on dealing with Managed Encryption.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
$filter (query)	string If provided, will filter responses to those matching the given OData query. Only certain fields are available to reference. The operators lt, le, eq, neq, ge, gt, not, and, and or are supported, and the built-in functions now, year, month, day, hour, minute, second. Example: year(__system/submissionDate) lt year(now())

Response

HTTP Status: 400

Content Type: application/json

Example

{
  "code": "400",
  "message": "Could not parse the given data (2 chars) as json."
}

Schema

object code string details object a subobject that contains programmatically readable details about this error message string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Exporting Root Data to Plain CSV via POST

POST /v1/projects/{projectId}/forms/{xmlFormId}/submissions.csv

(introduced: version 1.1)

This endpoint is useful only for Forms under Project Managed Encryption.

As with GET to .csv just above, this endpoint will only return CSV text data, rather than a ZIP file containing ore or more files. Please see that endpoint for further explanation.

As with POST to .csv.zip it allows secure submission of decryption passkeys. Please see that endpoint for more information on how to do this.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
$filter (query)	string If provided, will filter responses to those matching the given OData query. Only certain fields are available to reference. The operators lt, le, eq, neq, ge, gt, not, and, and or are supported, and the built-in functions now, year, month, day, hour, minute, second. Example: year(__system/submissionDate) lt year(now())

Response

HTTP Status: 400

Content Type: application/json

Example

{
  "code": "400",
  "message": "Could not parse the given data (2 chars) as json."
}

Schema

object code string details object a subobject that contains programmatically readable details about this error message string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Retrieving Audit Logs

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/audits

(introduced: version 1.2)

You can retrieve all Server Audit Logs relating to a submission. They will be returned most recent first.

This endpoint supports retrieving extended metadata; provide a header X-Extended-Metadata: true to additionally expand the actorId into full actor details, and acteeId into full actee details. The actor will always be an Actor, and the actee will be the Form this Submission is a part of.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 200

Content Type: application/json

Example

[
  {
    "actorId": 42,
    "action": "form.create",
    "acteeId": "85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "loggedAt": "2018-04-18T23:19:14.802Z"
  }
]

Schema

array actorId number The ID of the actor, if any, that initiated the action. Example: 42 action string The action that was taken. Example: form.create acteeId string The ID of the permissioning object against which the action was taken. Example: 85cb9aff-005e-4edd-9739-dc9c1a829c44 details object Additional details about the action that vary according to the type of action. loggedAt string ISO date format Example: 2018-04-18T23:19:14.802Z

HTTP Status: 200

Content Type: application/json; extended

Example

[
  {
    "actorId": 42,
    "action": "form.create",
    "acteeId": "85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "loggedAt": "2018-04-18T23:19:14.802Z",
    "actor": {
      "createdAt": "2018-04-18T23:19:14.802Z",
      "displayName": "My Display Name",
      "id": 115,
      "type": "user",
      "updatedAt": "2018-04-18T23:42:11.406Z",
      "deletedAt": "2018-04-18T23:42:11.406Z"
    }
  }
]

Schema

array actorId number The ID of the actor, if any, that initiated the action. Example: 42 action string The action that was taken. Example: form.create acteeId string The ID of the permissioning object against which the action was taken. Example: 85cb9aff-005e-4edd-9739-dc9c1a829c44 details object Additional details about the action that vary according to the type of action. loggedAt string ISO date format Example: 2018-04-18T23:19:14.802Z actor object expand createdAt string ISO date format Example: 2018-04-18 23:19:14.802000+00:00 displayName string All Actors, regardless of type, have a display name Example: My Display Name id number Example: 115.0 type enum The type of actor expand user string field_key string public_link string singleUse string updatedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00 deletedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00 actee object The details of the actee given by acteeId. Depending on the action type, this could be a number of object types, including an Actor, a Project, or a Form.

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Listing Encryption Keys

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/keys

This endpoint provides a listing of all known encryption keys needed to decrypt all Submissions for a given Form. It will return at least the base64RsaPublicKey property (as public) of all known versions of the form that have submissions against them. If managed keys are being used and a hint was provided, that will be returned as well.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple

Response

HTTP Status: 200

Content Type: application/json

Example

[
  {
    "id": 1,
    "public": "bcFeKDF3Sg8W91Uf5uxaIlsuhzmjbgUnIyiLzIjrx4CAaf9Y9LG7TAu6wKPqfbH6ZAkJTFSfjLNovbKhpOQcmO5VZGGay6yvXrX1TFW6C6RLITy74erxfUAStdtpP4nraCYqQYqn5zD4/1OmgweJt5vzGXW2ch7lrROEQhXB9lK+bjEeWx8TFW/+6ha/oRLnl6a2RBRL6mhwy3PoByNTKndB2MP4TygCJ/Ini4ivk74iSqVnoeuNJR/xUcU+kaIpZEIjxpAS2VECJU9fZvS5Gt84e5wl/t7bUKu+dlh/cUgHfk6+6bwzqGQYOe5A==",
    "managed": true,
    "hint": "it was a secret"
  }
]

Schema

array id number The numerical ID of the Key. Example: 1 public string The base64-encoded public key, with PEM envelope removed. Example: bcFeKDF3Sg8W91Uf5uxaIlM2uK0cUN9tBSGoASbC4LeIPqx65+6zmjbgUnIyiLzIjrx4CAaf9Y9LG7TAu6wKPqfbH6ZAkJTFSfjLNovbKhpOQcmO5VZGGay6yvXrX1TFW6C6RLITy74erxfUAStdtpP4nraCYqQYqn5zD4/1OmgweJt5vzGXW2ch7lrROEQhXB9lK+bjEeWx8TFW/+6ha/oRLnl6a2RBRL6mhwy3PoByNTKndB2MP4TygCJ/Ini4ivk74iSqVnoeuNJR/xUcU+kaIpZEIjxpAS2VECJU9fZvS5Gt84e5wl/t7bUKu+dlh/cUgHfk6+6bwzqGQYOe5A== managed boolean If true, this is a key generated by Project managed encryption. If not, this key is self-supplied. Example: true hint string The hint, if given, related to a managed encryption key. Example: it was a secret

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Listing Submitters

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/submitters

This endpoint provides a listing of all known submitting actors to a given Form. Each Actor that has submitted to the given Form will be returned once.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple

Response

HTTP Status: 200

Content Type: application/json

Example

[
  {
    "createdAt": "2018-04-18T23:19:14.802Z",
    "displayName": "My Display Name",
    "id": 115,
    "type": "user",
    "updatedAt": "2018-04-18T23:42:11.406Z",
    "deletedAt": "2018-04-18T23:42:11.406Z"
  }
]

Schema

array createdAt string ISO date format Example: 2018-04-18 23:19:14.802000+00:00 displayName string All Actors, regardless of type, have a display name Example: My Display Name id number Example: 115.0 type enum The type of actor expand user string field_key string public_link string singleUse string updatedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00 deletedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Comments

(introduced: version 1.2)

This API is likely to change in the future. In version 1.2 we have added comments to submissions, so changes and problems with the data can be discussed. It's very likely we will want comments in more places in the future, and at that time a more complete comments API will be introduced, and this current one may be changed or deprecated entirely.

Currently, it is not possible to get a specific comment's details, or to edit or delete a comment once it has been made.

Listing Comments

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/comments

Comments have only a body comment text and an actor that made the comment.

This endpoint supports retrieving extended metadata; provide a header X-Extended-Metadata: true to return a actor data object alongside the actorId Actor ID reference.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 200

Content Type: application/json

Example

[
  {
    "body": "this is my comment",
    "actorId": 42
  }
]

Schema

array body string The text of the comment. Example: this is my comment actorId number The ID of the Actor that made the comment. Example: 42

HTTP Status: 200

Content Type: application/json; extended

Example

[
  {
    "body": "this is my comment",
    "actorId": 42,
    "actor": {
      "createdAt": "2018-04-18T23:19:14.802Z",
      "displayName": "My Display Name",
      "id": 115,
      "type": "user",
      "updatedAt": "2018-04-18T23:42:11.406Z",
      "deletedAt": "2018-04-18T23:42:11.406Z"
    }
  }
]

Schema

array body string The text of the comment. Example: this is my comment actorId number The ID of the Actor that made the comment. Example: 42 actor object expand createdAt string ISO date format Example: 2018-04-18 23:19:14.802000+00:00 displayName string All Actors, regardless of type, have a display name Example: My Display Name id number Example: 115.0 type enum The type of actor expand user string field_key string public_link string singleUse string updatedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00 deletedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Posting Comments

POST /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/comments

Currently, the only accepted data is body, which contains the body of the comment to be made.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Request body

Example

{
  "body": "this is the text of my comment"
}

Schema

object body string The text of the comment.

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "body": "this is my comment",
  "actorId": 42
}

Schema

object body string The text of the comment. actorId number The ID of the Actor that made the comment.

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Attachments

When a Submission is created, either over the OpenRosa or the REST interface, its XML data is analyzed to determine which file attachments it references: these may be photos or video taken as part of the survey, or an audit/timing log, among other things. Each reference is an expected attachment, and these expectations are recorded permanently alongside the Submission.

With this subresource, you can list the expected attachments, see whether the server actually has a copy or not, and download, upload, re-upload, or clear binary data for any particular attachment.

Listing expected Submission Attachments

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/attachments

You can retrieve the list of expected Submission attachments at this route, along with a boolean flag indicating whether the server actually has a copy of the expected file or not. If the server has a file, you can then append its filename to the request URL to download only that file (see below).

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 200

Content Type: application/json

Example

[
  {
    "name": "file1.jpg",
    "exists": true
  },
  {
    "name": "file2.jpg",
    "exists": false
  },
  {
    "name": "file3.jpg",
    "exists": true
  }
]

Schema

array name string The name of the file as specified in the Submission XML. Example: myfile.mp3 exists boolean Whether the server has the file or not. Example: true

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Downloading an Attachment

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/attachments/{filename}

The Content-Type and Content-Disposition will be set appropriately based on the file itself when requesting an attachment file download.This endpoint supports ETag, which can be used to avoid downloading the same content more than once. When an API consumer calls this endpoint, it returns a value in ETag header, you can pass this value in the header If-None-Match of subsequent requests. If the file has not been changed since the previous request, you will receive 304 Not Modified response otherwise you'll get the latest file.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44
filename	string The name of the file as given by the Attachments listing resource. Example: file1.jpg

Response

HTTP Status: 200

Content Type: {the MIME type of the attachment file itself}

Example

"(binary data)\n"

Schema

HTTP Status: 403

Content Type: {the MIME type of the attachment file itself}

Example

{
  "code": "pencil",
  "message": "pencil"
}

Schema

object code string message string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Uploading an Attachment

POST /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/attachments/{filename}

(introduced: version 0.4)

To upload a binary to an expected file slot, POST the binary to its endpoint. Supply a Content-Type MIME-type header if you have one.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44
filename	string The name of the file as given by the Attachments listing resource. Example: file1.jpg

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "success": true
}

Schema

object success boolean

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Clearing a Submission Attachment

DELETE /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/attachments/{filename}

(introduced: version 0.4)

Because Submission Attachments are completely determined by the XML data of the submission itself, there is no direct way to entirely remove a Submission Attachment entry from the list, only to clear its uploaded content. Thus, when you issue a DELETE to the attachment's endpoint, that is what happens.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44
filename	string The name of the file as given by the Attachments listing resource. Example: file1.jpg

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "success": true
}

Schema

object success boolean

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Submission Versions

(introduced: version 1.2)

The instanceId that is submitted with the initial version of the submission is used permanently to reference that submission logically, which is to say the initial submission and all its subsequent versions. Each subsequent version will also provide its own instanceId. This instanceId becomes that particular version's identifier.

So if you submit a submission with <orx:instanceID>one</orx:instanceID> and then update it, deprecating one for version two, then the full route for version one is /v1/projects/…/forms/…/submissions/one/versions/one, and for two it is /v1/projects/…/forms/…/submissions/one/versions/two.

As of version 1.4, a deviceId and userAgent will also be returned with each submission. For each submission of a version, the submitting client device may transmit these extra metadata. If it does, those fields will be recognized and returned here for reference.

Listing Versions

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/versions

This will return all submission metadata for every version of this submission, in descending creation order.

This endpoint supports retrieving extended metadata; provide a header X-Extended-Metadata: true to return a submitter data object alongside the submitterId Actor ID reference.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the initially submitted version. Please see the notes at the top of this documentation section for more information. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 200

Content Type: application/json

Example

[
  {
    "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "instanceName": "village third house",
    "submitterId": 23,
    "deviceId": "imei:123456",
    "userAgent": "Enketo/3.0.4",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "current": true,
    "formVersion": "1.0"
  }
]

Schema

array instanceId string The instanceId of the Submission version, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 instanceName string The instanceName, if any, given by the Submission XML in the metadata section. Example: village third house submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. Example: 23 deviceId string The self-identified deviceId of the device that submitted the Submission version. Example: imei:123456 userAgent string The self-identified userAgent of the device that submitted the Submission version. Example: Enketo/3.0.4 createdAt string ISO date format. The time that the server received the Submission version. Example: 2018-01-19T23:58:03.395Z current boolean Whether the version is current or not. Example: true

HTTP Status: 200

Content Type: application/json; extended

Example

[
  {
    "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "instanceName": "village third house",
    "submitterId": 23,
    "deviceId": "imei:123456",
    "userAgent": "Enketo/3.0.4",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "current": true,
    "submitter": {
      "createdAt": "2018-04-18T23:19:14.802Z",
      "displayName": "My Display Name",
      "id": 115,
      "type": "user",
      "updatedAt": "2018-04-18T23:42:11.406Z",
      "deletedAt": "2018-04-18T23:42:11.406Z"
    },
    "formVersion": "1.0"
  }
]

Schema

array instanceId string The instanceId of the Submission version, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 instanceName string The instanceName, if any, given by the Submission XML in the metadata section. Example: village third house submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. Example: 23 deviceId string The self-identified deviceId of the device that submitted the Submission version. Example: imei:123456 userAgent string The self-identified userAgent of the device that submitted the Submission version. Example: Enketo/3.0.4 createdAt string ISO date format. The time that the server received the Submission version. Example: 2018-01-19T23:58:03.395Z current boolean Whether the version is current or not. Example: true submitter object expand createdAt string ISO date format Example: 2018-04-18 23:19:14.802000+00:00 displayName string All Actors, regardless of type, have a display name Example: My Display Name id number Example: 115.0 type enum The type of actor expand user string field_key string public_link string singleUse string updatedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00 deletedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00 formVersion string The version of the form the submission version was created against. Only returned with specific Submission Version requests. Example: 1.0

HTTP Status: 403

Content Type: application/json; extended

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Getting Version Details

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/versions/{versionId}

Returns metadata about a particular version of the submission. As with the normal submission endpoint, you'll only get metadata in JSON out of this route. If you want to retrieve the XML, add .xml.

This endpoint supports retrieving extended metadata; provide a header X-Extended-Metadata: true to return a submitter data object alongside the submitterId Actor ID reference.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44
versionId	string The instanceId of the particular version of this submission in question. Example: uuid:b1628661-65ed-4cab-8e30-19c17fef2de0

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "instanceName": "village third house",
  "submitterId": 23,
  "deviceId": "imei:123456",
  "userAgent": "Enketo/3.0.4",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "current": true,
  "formVersion": "1.0"
}

Schema

object instanceId string The instanceId of the Submission version, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 instanceName string The instanceName, if any, given by the Submission XML in the metadata section. Example: village third house submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. Example: 23 deviceId string The self-identified deviceId of the device that submitted the Submission version. Example: imei:123456 userAgent string The self-identified userAgent of the device that submitted the Submission version. Example: Enketo/3.0.4 createdAt string ISO date format. The time that the server received the Submission version. Example: 2018-01-19T23:58:03.395Z current boolean Whether the version is current or not. Example: true

HTTP Status: 200

Content Type: application/json; extended

Example

{
  "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "instanceName": "village third house",
  "submitterId": 23,
  "deviceId": "imei:123456",
  "userAgent": "Enketo/3.0.4",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "current": true,
  "submitter": {
    "createdAt": "2018-04-18T23:19:14.802Z",
    "displayName": "My Display Name",
    "id": 115,
    "type": "user",
    "updatedAt": "2018-04-18T23:42:11.406Z",
    "deletedAt": "2018-04-18T23:42:11.406Z"
  },
  "formVersion": "1.0"
}

Schema

object instanceId string The instanceId of the Submission version, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 instanceName string The instanceName, if any, given by the Submission XML in the metadata section. Example: village third house submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. Example: 23 deviceId string The self-identified deviceId of the device that submitted the Submission version. Example: imei:123456 userAgent string The self-identified userAgent of the device that submitted the Submission version. Example: Enketo/3.0.4 createdAt string ISO date format. The time that the server received the Submission version. Example: 2018-01-19T23:58:03.395Z current boolean Whether the version is current or not. Example: true submitter object expand createdAt string ISO date format Example: 2018-04-18 23:19:14.802000+00:00 displayName string All Actors, regardless of type, have a display name Example: My Display Name id number Example: 115.0 type enum The type of actor expand user string field_key string public_link string singleUse string updatedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00 deletedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00 formVersion string The version of the form the submission version was created against. Only returned with specific Submission Version requests. Example: 1.0

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Getting Version XML

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/versions/{versionId}.xml

Returns the XML of a particular version of the submission.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44
versionId	string The instanceId of the particular version of this submission in question. Example: uuid:b1628661-65ed-4cab-8e30-19c17fef2de0

Response

HTTP Status: 200

Content Type: application/xml

Example

<data id="simple">
  <orx:meta><orx:instanceID>uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44</orx:instanceID></orx:meta>
  <name>Alice</name>
  <age>32</age>
</data>

Schema

string

HTTP Status: 403

Content Type: application/xml

Example

No Example

Schema

string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Listing Version expected Attachments

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/versions/{versionId}/attachments

You can retrieve the list of expected Submission attachments for the given version at this route, along with a boolean flag indicating whether the server actually has a copy of the expected file or not. If the server has a file, you can then append its filename to the request URL to download only that file (see below).

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44
versionId	string The instanceId of the particular version of this submission in question. Example: uuid:b1628661-65ed-4cab-8e30-19c17fef2de0

Response

HTTP Status: 200

Content Type: application/json

Example

[
  {
    "name": "file1.jpg",
    "exists": true
  },
  {
    "name": "file2.jpg",
    "exists": false
  },
  {
    "name": "file3.jpg",
    "exists": true
  }
]

Schema

array name string The name of the file as specified in the Submission XML. Example: myfile.mp3 exists boolean Whether the server has the file or not. Example: true

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Downloading a Version's Attachment

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/versions/{versionId}/attachments/{filename}

It is important to note that this endpoint returns whatever is currently uploaded against the particular version of the Submission. It will not track overwritten attachments.This endpoint supports ETag, which can be used to avoid downloading the same content more than once. When an API consumer calls this endpoint, it returns a value in ETag header, you can pass this value in the header If-None-Match of subsequent requests. If the file has not been changed since the previous request, you will receive 304 Not Modified response otherwise you'll get the latest file.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44
versionId	string The instanceId of the particular version of this submission in question. Example: uuid:b1628661-65ed-4cab-8e30-19c17fef2de0
filename	string The name of the file as given by the Attachments listing resource. Example: file1.jpg

Response

HTTP Status: 200

Content Type: {the MIME type of the attachment file itself}

Example

"(binary data)\n"

Schema

HTTP Status: 403

Content Type: {the MIME type of the attachment file itself}

Example

{
  "code": "pencil",
  "message": "pencil"
}

Schema

object code string message string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Getting changes between Versions

GET /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/diffs

This returns the changes, or edits, between different versions of a Submission. These changes are returned in an object that is indexed by the instanceId that uniquely identifies that version. Between two submissions, there is an array of objects representing how each field changed. This change object contains the old and new values, as well as the path of that changed node in the Submission XML. These changes reflect the updated instanceID and deprecatedID fields as well as the edited value.

Request

Parameters

projectId	number The numeric ID of the Project Example: 16
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "two": [
    {
      "new": "Donna",
      "old": "Dana",
      "path": [
        "name"
      ]
    },
    {
      "new": "55",
      "old": "44",
      "path": [
        "age"
      ]
    },
    {
      "new": "two",
      "old": "one",
      "path": [
        "meta",
        "instanceID"
      ]
    },
    {
      "new": "one",
      "old": null,
      "path": [
        "meta",
        "deprecatedID"
      ]
    }
  ]
}

Schema

array None object expand new string The new value of this node, which can either be a simple string, or JSON string representing a larger structural change to the Submission XML. It can also be null if this field no longer exists in the Submission. old string The old value of this node, with similar properties to new. It can be null if this field did not exist previously. path array An array representing the path (XPath) in the Submission tree for this node. It does not include the outermost path data. For elements that are part of repeat groups, the path element is the node name and the index (starting at 0), e.g. ['child', 2] is the third child.

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Draft Submissions

All Draft Forms feature a /submissions subresource (/draft/submissions), which is identical to the same subresource on the form itself. These submissions exist only as long as the Draft Form does: they are removed if the Draft Form is published, and they are abandoned if the Draft Form is deleted or overwritten.

Here we list all those resources again just for completeness.

Listing all Submissions on a Draft Form

GET /v1/projects/{projectId}/forms/{xmlFormId}/draft/submissions

Identical to the non-Draft version of this endpoint.

Request

Parameters

projectId	number The id of the project this form belongs to. Example: 1
xmlFormId	string The id of this form as given in its XForms XML definition Example: simple

Response

HTTP Status: 200

Content Type: application/json

Example

[
  {
    "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "submitterId": 23,
    "deviceId": "imei:123456",
    "userAgent": "Enketo/3.0.4",
    "reviewState": "approved",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "updatedAt": "2018-03-21T12:45:02.312Z",
    "currentVersion": {
      "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
      "instanceName": "village third house",
      "submitterId": 23,
      "deviceId": "imei:123456",
      "userAgent": "Enketo/3.0.4",
      "createdAt": "2018-01-19T23:58:03.395Z",
      "current": true
    }
  }
]

Schema

array instanceId string The instanceId of the Submission, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 submitterId number The ID of the Actor (App User, User, or Public Link) that originally submitted this Submission. Example: 23 deviceId string The self-identified deviceId of the device that collected the data, sent by it upon submission to the server. The initial submission deviceId will be returned here. Example: imei:123456 userAgent string The self-identified userAgent of the device that collected the data, sent by it upon submission to the server. The initial submission userAgent will be returned here. Example: Enketo/3.0.4 reviewState object The current review state of the submission. expand null string edited string hasIssues string rejected string approved string createdAt string ISO date format. The time that the server received the Submission. Example: 2018-01-19T23:58:03.395Z updatedAt string ISO date format. null when the Submission is first created, then updated when the Submission's XML data or metadata is updated. Example: 2018-03-21T12:45:02.312Z currentVersion object expand instanceId string The instanceId of the Submission version, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 instanceName string The instanceName, if any, given by the Submission XML in the metadata section. Example: village third house submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. Example: 23 deviceId string The self-identified deviceId of the device that submitted the Submission version. Example: imei:123456 userAgent string The self-identified userAgent of the device that submitted the Submission version. Example: Enketo/3.0.4 createdAt string ISO date format. The time that the server received the Submission version. Example: 2018-01-19T23:58:03.395Z current boolean Whether the version is current or not. Example: true

HTTP Status: 200

Content Type: application/json; extended

Example

[
  {
    "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "submitterId": 23,
    "deviceId": "imei:123456",
    "userAgent": "Enketo/3.0.4",
    "reviewState": "approved",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "updatedAt": "2018-03-21T12:45:02.312Z",
    "currentVersion": {
      "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
      "instanceName": "village third house",
      "submitterId": 23,
      "deviceId": "imei:123456",
      "userAgent": "Enketo/3.0.4",
      "createdAt": "2018-01-19T23:58:03.395Z",
      "current": true
    },
    "submitter": {
      "createdAt": "2018-04-18T23:19:14.802Z",
      "displayName": "My Display Name",
      "id": 115,
      "type": "user",
      "updatedAt": "2018-04-18T23:42:11.406Z",
      "deletedAt": "2018-04-18T23:42:11.406Z"
    }
  }
]

Schema

array instanceId string The instanceId of the Submission, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 submitterId number The ID of the Actor (App User, User, or Public Link) that originally submitted this Submission. Example: 23 deviceId string The self-identified deviceId of the device that collected the data, sent by it upon submission to the server. The initial submission deviceId will be returned here. Example: imei:123456 userAgent string The self-identified userAgent of the device that collected the data, sent by it upon submission to the server. The initial submission userAgent will be returned here. Example: Enketo/3.0.4 reviewState object The current review state of the submission. expand null string edited string hasIssues string rejected string approved string createdAt string ISO date format. The time that the server received the Submission. Example: 2018-01-19T23:58:03.395Z updatedAt string ISO date format. null when the Submission is first created, then updated when the Submission's XML data or metadata is updated. Example: 2018-03-21T12:45:02.312Z currentVersion object expand instanceId string The instanceId of the Submission version, given by the Submission XML. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 instanceName string The instanceName, if any, given by the Submission XML in the metadata section. Example: village third house submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. Example: 23 deviceId string The self-identified deviceId of the device that submitted the Submission version. Example: imei:123456 userAgent string The self-identified userAgent of the device that submitted the Submission version. Example: Enketo/3.0.4 createdAt string ISO date format. The time that the server received the Submission version. Example: 2018-01-19T23:58:03.395Z current boolean Whether the version is current or not. Example: true submitter object expand createdAt string ISO date format Example: 2018-04-18 23:19:14.802000+00:00 displayName string All Actors, regardless of type, have a display name Example: My Display Name id number Example: 115.0 type enum The type of actor expand user string field_key string public_link string singleUse string updatedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00 deletedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Creating a Submission

POST /v1/projects/{projectId}/forms/{xmlFormId}/draft/submissions

Identical to the non-Draft version of this endpoint.

Request

Parameters

projectId	number The id of the project this form belongs to. Example: 1
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "submitterId": 23,
  "deviceId": "imei:123456",
  "userAgent": "Enketo/3.0.4",
  "reviewState": "approved",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "updatedAt": "2018-03-21T12:45:02.312Z",
  "currentVersion": {
    "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "instanceName": "village third house",
    "submitterId": 23,
    "deviceId": "imei:123456",
    "userAgent": "Enketo/3.0.4",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "current": true
  }
}

Schema

object instanceId string The instanceId of the Submission, given by the Submission XML. submitterId number The ID of the Actor (App User, User, or Public Link) that originally submitted this Submission. deviceId string The self-identified deviceId of the device that collected the data, sent by it upon submission to the server. The initial submission deviceId will be returned here. userAgent string The self-identified userAgent of the device that collected the data, sent by it upon submission to the server. The initial submission userAgent will be returned here. reviewState enum The current review state of the submission. expand None string edited string hasIssues string rejected string approved string createdAt string ISO date format. The time that the server received the Submission. updatedAt string ISO date format. null when the Submission is first created, then updated when the Submission's XML data or metadata is updated. currentVersion object The current version of the Submission. expand instanceId string The instanceId of the Submission version, given by the Submission XML. instanceName string The instanceName, if any, given by the Submission XML in the metadata section. submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. deviceId string The self-identified deviceId of the device that submitted the Submission version. userAgent string The self-identified userAgent of the device that submitted the Submission version. createdAt string ISO date format. The time that the server received the Submission version. current boolean Whether the version is current or not.

HTTP Status: 400

Content Type: application/json

Example

{
  "code": "400",
  "message": "Could not parse the given data (2 chars) as json."
}

Schema

object code string details object a subobject that contains programmatically readable details about this error message string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

HTTP Status: 409

Content Type: application/json

Example

{
  "code": "409.1",
  "message": "A resource already exists with id value(s) of 1."
}

Schema

object code string message string

Exporting Form Submissions to CSV

GET /v1/projects/{projectId}/forms/{xmlFormId}/draft/submissions.csv.zip

Identical to the non-Draft version of this endpoint.

Request

Parameters

projectId	number The id of the project this form belongs to. Example: 1
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple

Response

HTTP Status: 400

Content Type: application/json

Example

{
  "code": "400",
  "message": "Could not parse the given data (2 chars) as json."
}

Schema

object code string details object a subobject that contains programmatically readable details about this error message string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Exporting Form Submissions to CSV via POST

POST /v1/projects/{projectId}/forms/{xmlFormId}/draft/submissions.csv.zip

Identical to the non-Draft version of this endpoint.

Request

Parameters

projectId	number The id of the project this form belongs to. Example: 1
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple

Response

HTTP Status: 400

Content Type: application/json

Example

{
  "code": "400",
  "message": "Could not parse the given data (2 chars) as json."
}

Schema

object code string details object a subobject that contains programmatically readable details about this error message string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Listing Encryption Keys

GET /v1/projects/{projectId}/forms/{xmlFormId}/draft/submissions/keys

Identical to the non-Draft version of this endpoint.

Request

Parameters

projectId	number The id of the project this form belongs to. Example: 1
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple

Response

HTTP Status: 200

Content Type: application/json

Example

[
  {
    "id": 1,
    "public": "bcFeKDF3Sg8W91Uf5uxaIlsuhzmjbgUnIyiLzIjrx4CAaf9Y9LG7TAu6wKPqfbH6ZAkJTFSfjLNovbKhpOQcmO5VZGGay6yvXrX1TFW6C6RLITy74erxfUAStdtpP4nraCYqQYqn5zD4/1OmgweJt5vzGXW2ch7lrROEQhXB9lK+bjEeWx8TFW/+6ha/oRLnl6a2RBRL6mhwy3PoByNTKndB2MP4TygCJ/Ini4ivk74iSqVnoeuNJR/xUcU+kaIpZEIjxpAS2VECJU9fZvS5Gt84e5wl/t7bUKu+dlh/cUgHfk6+6bwzqGQYOe5A==",
    "managed": true,
    "hint": "it was a secret"
  }
]

Schema

array id number The numerical ID of the Key. Example: 1 public string The base64-encoded public key, with PEM envelope removed. Example: bcFeKDF3Sg8W91Uf5uxaIlM2uK0cUN9tBSGoASbC4LeIPqx65+6zmjbgUnIyiLzIjrx4CAaf9Y9LG7TAu6wKPqfbH6ZAkJTFSfjLNovbKhpOQcmO5VZGGay6yvXrX1TFW6C6RLITy74erxfUAStdtpP4nraCYqQYqn5zD4/1OmgweJt5vzGXW2ch7lrROEQhXB9lK+bjEeWx8TFW/+6ha/oRLnl6a2RBRL6mhwy3PoByNTKndB2MP4TygCJ/Ini4ivk74iSqVnoeuNJR/xUcU+kaIpZEIjxpAS2VECJU9fZvS5Gt84e5wl/t7bUKu+dlh/cUgHfk6+6bwzqGQYOe5A== managed boolean If true, this is a key generated by Project managed encryption. If not, this key is self-supplied. Example: true hint string The hint, if given, related to a managed encryption key. Example: it was a secret

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Getting Submission details

GET /v1/projects/{projectId}/forms/{xmlFormId}/draft/submissions/{instanceId}

Identical to the non-Draft version of this endpoint.

Request

Parameters

projectId	number The id of the project this form belongs to. Example: 1
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 200

Content Type: application/json; extended

Example

{
  "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "submitterId": 23,
  "deviceId": "imei:123456",
  "userAgent": "Enketo/3.0.4",
  "reviewState": "approved",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "updatedAt": "2018-03-21T12:45:02.312Z",
  "currentVersion": {
    "instanceId": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "instanceName": "village third house",
    "submitterId": 23,
    "deviceId": "imei:123456",
    "userAgent": "Enketo/3.0.4",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "current": true
  },
  "submitter": {
    "createdAt": "2018-04-18T23:19:14.802Z",
    "displayName": "My Display Name",
    "id": 115,
    "type": "user",
    "updatedAt": "2018-04-18T23:42:11.406Z",
    "deletedAt": "2018-04-18T23:42:11.406Z"
  }
}

Schema

object instanceId string The instanceId of the Submission, given by the Submission XML. submitterId number The ID of the Actor (App User, User, or Public Link) that originally submitted this Submission. deviceId string The self-identified deviceId of the device that collected the data, sent by it upon submission to the server. The initial submission deviceId will be returned here. userAgent string The self-identified userAgent of the device that collected the data, sent by it upon submission to the server. The initial submission userAgent will be returned here. reviewState enum The current review state of the submission. expand None string edited string hasIssues string rejected string approved string createdAt string ISO date format. The time that the server received the Submission. updatedAt string ISO date format. null when the Submission is first created, then updated when the Submission's XML data or metadata is updated. currentVersion object The current version of the Submission. expand instanceId string The instanceId of the Submission version, given by the Submission XML. instanceName string The instanceName, if any, given by the Submission XML in the metadata section. submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. deviceId string The self-identified deviceId of the device that submitted the Submission version. userAgent string The self-identified userAgent of the device that submitted the Submission version. createdAt string ISO date format. The time that the server received the Submission version. current boolean Whether the version is current or not. submitter object The full details of the Actor that submitted this Submission. expand createdAt string ISO date format displayName string All Actors, regardless of type, have a display name id number type enum the Type of this Actor; typically this will be user. expand user string field_key string public_link string singleUse string updatedAt string ISO date format deletedAt string ISO date format

HTTP Status: 200

Content Type: application/json

Example

{
  "instanceId": "pencil",
  "submitterId": 1,
  "deviceId": "pencil",
  "userAgent": "pencil",
  "reviewState": "",
  "createdAt": "pencil",
  "updatedAt": "pencil",
  "currentVersion": {
    "instanceId": "pencil",
    "instanceName": "pencil",
    "submitterId": 1,
    "deviceId": "pencil",
    "userAgent": "pencil",
    "createdAt": "pencil",
    "current": ""
  },
  "submitter": {
    "createdAt": "pencil",
    "displayName": "pencil",
    "id": 1,
    "type": "",
    "updatedAt": "pencil",
    "deletedAt": "pencil"
  }
}

Schema

object instanceId string The instanceId of the Submission, given by the Submission XML. submitterId number The ID of the Actor (App User, User, or Public Link) that originally submitted this Submission. deviceId string The self-identified deviceId of the device that collected the data, sent by it upon submission to the server. The initial submission deviceId will be returned here. userAgent string The self-identified userAgent of the device that collected the data, sent by it upon submission to the server. The initial submission userAgent will be returned here. reviewState enum The current review state of the submission. expand None string edited string hasIssues string rejected string approved string createdAt string ISO date format. The time that the server received the Submission. updatedAt string ISO date format. null when the Submission is first created, then updated when the Submission's XML data or metadata is updated. currentVersion object The current version of the Submission. expand instanceId string The instanceId of the Submission version, given by the Submission XML. instanceName string The instanceName, if any, given by the Submission XML in the metadata section. submitterId number The ID of the Actor (App User, User, or Public Link) that submitted this Submission version. deviceId string The self-identified deviceId of the device that submitted the Submission version. userAgent string The self-identified userAgent of the device that submitted the Submission version. createdAt string ISO date format. The time that the server received the Submission version. current boolean Whether the version is current or not. submitter object The full details of the Actor that submitted this Submission. expand createdAt string ISO date format displayName string All Actors, regardless of type, have a display name id number type enum the Type of this Actor; typically this will be user. expand user string field_key string public_link string singleUse string updatedAt string ISO date format deletedAt string ISO date format

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Retrieving Submission XML

GET /v1/projects/{projectId}/forms/{xmlFormId}/draft/submissions/{instanceId}.xml

Identical to the non-Draft version of this endpoint.

Request

Parameters

projectId	number The id of the project this form belongs to. Example: 1
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 200

Content Type: application/xml

Example

<data id="simple">
  <orx:meta><orx:instanceID>uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44</orx:instanceID></orx:meta>
  <name>Alice</name>
  <age>32</age>
</data>

Schema

string

Listing expected Submission Attachments

GET /v1/projects/{projectId}/forms/{xmlFormId}/draft/submissions/{instanceId}/attachments

Identical to the non-Draft version of this endpoint.

Request

Parameters

projectId	number The id of the project this form belongs to. Example: 1
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

Response

HTTP Status: 200

Content Type: application/json

Example

[
  {
    "name": "file1.jpg",
    "exists": true
  },
  {
    "name": "file2.jpg",
    "exists": false
  },
  {
    "name": "file3.jpg",
    "exists": true
  }
]

Schema

array name string The name of the file as specified in the Submission XML. Example: myfile.mp3 exists boolean Whether the server has the file or not. Example: true

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Downloading an Attachment

GET /v1/projects/{projectId}/forms/{xmlFormId}/draft/submissions/{instanceId}/attachments/{filename}

Identical to the non-Draft version of this endpoint.

Request

Parameters

projectId	number The id of the project this form belongs to. Example: 1
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44
filename	string The name of the file as given by the Attachments listing resource. Example: file1.jpg

Response

HTTP Status: 200

Content Type: {the MIME type of the attachment file itself}

Example

"(binary data)\n"

Schema

HTTP Status: 403

Content Type: {the MIME type of the attachment file itself}

Example

{
  "code": "pencil",
  "message": "pencil"
}

Schema

object code string message string

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Uploading an Attachment

POST /v1/projects/{projectId}/forms/{xmlFormId}/draft/submissions/{instanceId}/attachments/{filename}

Identical to the non-Draft version of this endpoint.

Request

Parameters

projectId	number The id of the project this form belongs to. Example: 1
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44
filename	string The name of the file as given by the Attachments listing resource. Example: file1.jpg

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "success": true
}

Schema

object success boolean

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Clearing a Submission Attachment

DELETE /v1/projects/{projectId}/forms/{xmlFormId}/draft/submissions/{instanceId}/attachments/{filename}

Identical to the non-Draft version of this endpoint.

Request

Parameters

projectId	number The id of the project this form belongs to. Example: 1
xmlFormId	string The xmlFormId of the Form being referenced. Example: simple
instanceId	string The instanceId of the Submission being referenced. Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44
filename	string The name of the file as given by the Attachments listing resource. Example: file1.jpg

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "success": true
}

Schema

object success boolean

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object code number Example: 403.1 message string Example: The authenticated actor does not have rights to perform that action.

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No