Zottle

Submissions

How responses arrive from the field, and how to read, review, export and restore them.

OpenRosa collection channel

Responses collected on mobile arrive through the OpenRosa channel — the same protocol KoboCollect and ODK Collect use to sync forms. Devices authenticate with HTTP Basic Auth (email and password); the first probe, sent without credentials and answered with 401 and a WWW-Authenticate: Basic challenge, is the normal handshake, not an error.

Method Endpoint Purpose
GET /mobile-collect/formList OpenRosa form list for the workspace — what the device downloads.
GET /mobile-collect/forms/{id}.xml The XForm definition the device fills in.
POST /mobile-collect/submission Submit one filled form as multipart: the xml_submission_file part carries the XML, and photos or other media ride along as additional parts.
HEAD /mobile-collect/submission Availability probe; it advertises the accepted upload size in X-OpenRosa-Accept-Content-Length (100 MB).
POST /mobile-collect/telemetry Device telemetry reported by the mobile client.

Anonymous collection links carry their token in the URL and never ask for credentials; what they can submit depends on the form's anonymous-collection setting.

List submissions

GET /data-entries returns the entries of a workspace, most recent first. For non-administrator accounts, workspaceId is required and the results are limited to your region scope.

Parameter Meaning
status A status (uploaded, submitted, reviewing, validated, rejected) or a display group (pending, draft, all).
search Case-insensitive substring search on the submission XML.
page / perPage Pagination; 20 per page by default, up to 10000.
sortBy / sortDir createdAt (default), syncedAt, status or score; desc (default) or asc.
regionCodes Comma-separated region codes, intersected with the regions you are allowed to see.

The status groups expand as follows: pending covers uploaded, submitted and reviewing; draft covers uploaded; all removes the filter.

curl "https://<votre-serveur>/api/data-entries?workspaceId=<workspace-id>&status=pending" \
  -H "Authorization: Bearer $TOKEN"

One submission

Method Endpoint Purpose
GET /data-entries/{id} Read one entry: answers, source, status, region and quality score.
PATCH /data-entries/{id} Update an entry: dataXml, source, status or syncedAt.
POST /data-entries/{id}/review Record a review decision: status is reviewing, requested_edit, validated or rejected, with optional comments. Rejecting or requesting an edit requires a comment; a finalized entry must be reopened through an edit request before it can be reviewed again.
POST /data-entries/{id}/transition Apply a status transition: action plus an optional comment.

The transition actions are:

Action Moves
approve reviewing → validated.
reject reviewing → rejected; the comment is required and must be at least 10 characters.
request_correction rejected → uploaded, so the correction can be collected again.
finalize validated → validated; records the final decision without changing the status. 
curl -X POST https://<votre-serveur>/api/data-entries/<entry-id>/transition \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"approve","comment":"Checked against the source document"}'

Review queue and batch actions

Method Endpoint Purpose
GET /data-entries/review-queue The review queue, filterable by datasetId, source, reviewedBy, minAgeHours, priorityDatasetId and regionCodes.
POST /data-entries/reviews/batch Apply review decisions to several entries in one call: entries with id, status and comments.
POST /data-entries/batch Apply one transition action to several entries: ids, action and comment.
POST /data-entries/bulk Create several entries at once (datasetId, workspaceId, entries with dataXml).

Validation queue

GET /validation/queue lists the entries of a workspace with their validation results (workspaceId is required; page and perPage, 100 maximum; regionCodes narrows to regions you can see). POST /validation/queue/{id}/rerun re-runs validation for one entry — the id is the data entry id.

Export as CSV

GET /data-entries/export writes the entries as a CSV file (id, dataset_id, workspace_id, source, data_xml, created_by, status, created_at, synced_at, quality_score). It accepts the same workspaceId and status filters; non-administrator accounts export only their region scope.

curl -L "https://<votre-serveur>/api/data-entries/export?workspaceId=<workspace-id>&status=validated" \
  -H "Authorization: Bearer $TOKEN" \
  -o data-entries-export.csv

Trash and restore

DELETE /data-entries/{id} is a soft delete: the entry disappears from listings but stays restorable. POST /data-entries/{id}/restore brings it back.