Sign in
Forms

List all Forms

Currently, there are no paging or filtering options, so listing Forms will get you every Form you are allowed to access, every time.

As of version 1.2, Forms that are unpublished (that only carry a draft and have never been published) will appear with full metadata detail. Previously, certain details like name were omitted. You can determine that a Form is unpublished by checking the publishedAt value: it will be null for unpublished forms.

This endpoint supports retrieving extended metadata; provide a header X-Extended-Metadata: true to additionally retrieve the submissions count of the number of Submissions that each Form has, the reviewStates object of counts of Submissions with specific review states, the lastSubmission most recent submission timestamp, the Actor the Form was createdBy, as well as other metadata.

The query ?deleted=true can be added to list deleted Forms with their numeric form IDs, which can be used to restore a deleted Form.

get/v1/projects/{projectId}/forms

Path parameters

projectIdnumber required

The numeric ID of the Project

Query parameters

deletedboolean

If set to true, will return only deleted Forms and their IDs

Response

OK

projectIdnumber required

The id of the project this form belongs to.

xmlFormIdstring required

The id of this form as given in its XForms XML definition

namestring

The friendly name of this form. It is given by the <title> in the XForms XML definition.

versionstring required

The version of this form as given in its XForms XML definition. If no version was specified in the Form, a blank string will be given.

enketoIdstring

If it exists, this is the survey ID of this Form on Enketo at /-. This will be the ID of the published version if it exists, otherwise it will be the draft ID. Only a cookie-authenticated user may access the preview through Enketo.

hashstring required

An MD5 sum automatically computed based on the XForms XML definition. This is required for OpenRosa compliance.

keyIdnumber

If a public encryption key is present on the form, its numeric ID as tracked by Central is given here.

state'open' | 'closing' | 'closed' required
publishedAtstring

Indicates when a draft has most recently been published for this Form. If this value is null, this Form has never been published yet, and contains only a draft.

createdAtstring required

ISO date format

updatedAtstring

ISO date format

webformsEnabledboolean

Enables use of ODK Web Forms instead of Enketo for filling Forms via web browsers.

Example response

[
  {
    "projectId": 1,
    "xmlFormId": "simple",
    "name": "Simple",
    "version": "2.1",
    "enketoId": "abcdef",
    "hash": "51a93eab3a1974dbffc4c7913fa5a16a",
    "keyId": 3,
    "publishedAt": "2018-01-21T00:04:11.153Z",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "updatedAt": "2018-03-21T12:45:02.312Z"
  }
]

Changes

Changed in 3 of the 54 revisions of this API.4

  • 022694254f0d1See the full diff
    • ○

      api operation id List all Forms removed and replaced with listAllForms

      api-operation-id-removed

  • b11b54eea4871See the full diff
    • ○

      removed the non-success response with the status 403

      response-non-success-status-removed

  • e8c2858fd4eb2See the full diff
    • ○

      api operation id listAllForms removed and replaced with List all Forms

      api-operation-id-removed

    • ○

      added the non-success response with the status 403

      response-non-success-status-added

    This revision also has 11 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog