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

[
  {
    "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
    }
  }
]

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

[
  {
    "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"
    }
  }
]

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

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

object

code

string

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

{
  "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
  }
}

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

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

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

object

code

string

details

object

a subobject that contains programmatically readable details about this error

message

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

HTTP Status: 409

Content Type: application/json

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

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

{
  "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
  }
}

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

{
  "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"
  }
}

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

<Redirects to correct Submission URL>

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

{
  "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
  }
}

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

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

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

object

code

string

details

object

a subobject that contains programmatically readable details about this error

message

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

HTTP Status: 409

Content Type: application/json

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

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

{
  "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
  }
}

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

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

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

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

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

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

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

object

code

string

message

string

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

%24filter

(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

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

object

code

string

details

object

a subobject that contains programmatically readable details about this error

message

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

%24filter

(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

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

object

code

string

details

object

a subobject that contains programmatically readable details about this error

message

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

%24filter

(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

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

object

code

string

details

object

a subobject that contains programmatically readable details about this error

message

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

%24filter

(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

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

object

code

string

details

object

a subobject that contains programmatically readable details about this error

message

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

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

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

[
  {
    "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"
    }
  }
]

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

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

object

code

string

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

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

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

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

object

code

string

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

[
  {
    "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"
  }
]

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

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

object

code

string

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

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

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

[
  {
    "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"
    }
  }
]

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

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

object

code

string

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

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

object

body

string

The text of the comment.

Response

HTTP Status: 200

Content Type: application/json

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

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

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

object

code

string

message

string

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

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

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

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

object

code

string

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.

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}

"(binary data)\n"

HTTP Status: 403

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

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

object

code

string

message

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

{
  "success": true
}

object

success

boolean

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

{
  "success": true
}

object

success

boolean

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

[
  {
    "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"
  }
]

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

[
  {
    "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"
  }
]

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

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

object

code

string

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

{
  "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"
}

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

{
  "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"
}

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; extended

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

object

code

string

message

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

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

string

HTTP Status: 403

Content Type: application/xml

No Example

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

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

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

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

object

code

string

message

string

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.

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}

"(binary data)\n"

HTTP Status: 403

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

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

object

code

string

message

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

{
  "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"
      ]
    }
  ]
}

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

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

object

code

string

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

[
  {
    "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
    }
  }
]

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

[
  {
    "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"
    }
  }
]

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

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

object

code

string

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

{
  "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
  }
}

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

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

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

object

code

string

details

object

a subobject that contains programmatically readable details about this error

message

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

HTTP Status: 409

Content Type: application/json

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

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

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

object

code

string

details

object

a subobject that contains programmatically readable details about this error

message

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

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

object

code

string

details

object

a subobject that contains programmatically readable details about this error

message

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

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

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

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

object

code

string

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

{
  "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"
  }
}

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

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

{
  "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"
  }
}

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

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; extended

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

object

code

string

message

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

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

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

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

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

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

object

code

string

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}

"(binary data)\n"

HTTP Status: 403

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

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

object

code

string

message

string

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

{
  "success": true
}

object

success

boolean

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

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

{
  "success": true
}

object

success

boolean

HTTP Status: 403

Content Type: application/json

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

object

code

string

message

string

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No