Expose submission version history via API v2

Suggestion Box New Features
,
1

Problem

There is currently no way in the KoboToolbox API v2 to retrieve historical versions of a submission (the records stored in the InstanceHistory model). This prevents data managers and field teams from:

  • Recovering answers as they were before any edits
  • Producing reports that faithfully reflect the state of the data at a specific point in time

User story

  1. As a data manager, I want to call the API to fetch all prior versions of a specific submission so I can reconstruct the sequence of responses and validate any changes.
  2. As a reporting lead, I need to compare the original and edited versions of submissions to document corrections for donors.
  3. As an internal auditor, I want to retrieve metadata about each edit (editor, timestamp, fields changed) without needing SQL access or deploying custom code.

Proposal

  1. Introduce a new API v2 endpoint, for example:
    GET /api/v2/assets/{FORM_UID}/instances/{INSTANCE_ID}/history/
  2. The endpoint returns a JSON array of version objects, e.g.:
    [
  {
    "version_id": 123,
    "date_created": "2025-07-14T09:23:45Z",
    "edited_by": "user@example.org",
    "xml": "<data>…</data>"
  },
  {
    "version_id": 124,
    "date_created": "2025-07-15T11:02:10Z",
    "edited_by": "editor@example.org",
    "xml": "<data>…</data>"
  }
]
  3. Document the new endpoint in the API reference, including required permissions (e.g. view_instancehistory or change_xform).
  • Expected outcome
    • Programmatic access to any prior state of a submission
    • Simplified auditing and reporting workflows without direct database queries

Thank you very much!! :slight_smile:

2

Welcome back to the community, @bdplazo! Thank you for your suggestions, they’re well noted!

1 Like
3

Voting for this, and offering a minimal first step that would cover the most
common integration need without building full version history.

We replicate ~230k submissions nightly into a data warehouse.

We routinely see edit submissions after entry, and the data API exposes no last-modified timestamp: _submission_time is creation time and never changes (we verified this against the kpi source).

We see no other choice but to re-download every submission every night and hash it to find the
handful that changed.

The minimal fix: a _date_modified key on each record served by /api/v2/assets/{uid}/data/, updated on Enketo edits, validation-status
changes, and attachment changes, and queryable
(?query={"_date_modified":{"$gt":"…"}}). The backend already tracks
date_modified on the instance model. It just isn’t serialized into the
data the API serves.

I’ve made a GitHub issue on this: Data API: no way to detect edited submissions · Issue #7259 · kobotoolbox/kpi

1 Like