Individual Form

Modifying a Form

Changed on

It is currently possible to modify only one thing about a Form: its state, which governs whether it is available for download onto survey clients and whether it accepts new Submissions. See the state Attribute in the Request documentation to the right to see the possible values and their meanings.

We use PATCH rather than PUT to represent the update operation, so that you only have to supply the properties you wish to change. Anything you do not supply will remain untouched.

patch/v1/projects/{projectId}/forms/{xmlFormId}

Request

  • Base URL
    / (relative, and the document was published on a file host, not at the API’s origin)
  • URL
    /v1/projects/{projectId}/forms/{xmlFormId}
  • Auth
    none declared

Path parameters

projectIdnumber required

The numeric ID of the Project

xmlFormIdstring required

The xmlFormId of the Form being referenced.

Request body */*

state'open' | 'closing' | 'closed'

If supplied, the Form lifecycle state will move to this value.

Example request

{
  "state": "open"
}

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

The present lifecycle status of this form. Controls whether it is available for download on survey clients or accepts new submissions.

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

Changes

  • dcd5409827e1Revision changes
    • warning

      removed the request property

    • warning

      removed the optional property from the response with the status

  • 28f47a477c02Revision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status