Creating a new Form

When creating a Form, the only required data is the actual XForms XML or XLSForm itself. Use it as the POST body with a Content-Type header of application/xml (text/xml works too), and the Form will be created.

As of Version 0.8, Forms will by default be created in Draft state, accessible under /projects/…/forms/…/draft. The Form itself will not have a public XML definition, and will not appear for download onto mobile devices. You will need to publish the form to finalize it for data collection. To disable this behaviour, and force the new Form to be immediately ready, you can pass the querystring option ?publish=true.

For XLSForm upload, either .xls or .xlsx are accepted. You must provide the Content-Type request header corresponding to the file type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for .xlsx files, and application/vnd.ms-excel for .xls files. You must also provide an X-XlsForm-FormId-Fallback request header with the formId you want the resulting form to have, if the spreadsheet does not already specify. This header field accepts percent-encoded values to support Unicode characters and other non-ASCII values.

By default, any XLSForm conversion Warnings will fail this request and return the warnings rather than use the converted XML to create a form. To override this behaviour, provide a querystring flag ?ignoreWarnings=true. Conversion Errors will always fail this request.

The API will currently check the XML's structure in order to extract the information we need about it, but ODK Central does not run comprehensive validation on the full contents of the XML to ensure compliance with the ODK specification. Future versions will likely do this, but in the meantime you will have to use a tool like ODK Validate to be sure your Forms are correct.

You will get following workflow warnings while creating a new form or uploading a new version of an existing form:

• Structural Change: Returned when the uploaded definition of the form removes, renames or moves a field to a different group/repeat. Learn more

• Deleted Form: Returned when there is a form with the same ID in the Trash. Learn more

Creating Datasets with Forms

Starting from Version 2022.3, a Form can also create a Dataset by defining a Dataset schema in the Form definition (XForms XML or XLSForm). When a Form with a Dataset schema is uploaded, a Dataset and its Properties are created. The state of the Dataset is dependent on the state of the Form; you will need to publish the Form to publish the Dataset. Datasets in the Draft state are not returned in Dataset APIs, however the Related Datasets API for the Form can be called to get the Dataset and its Properties.

It is possible to define the schema of a Dataset in multiple Forms. Such Forms can be created and published in any order. Publishing any of the Forms will also publish the Dataset and will generate a dataset.create event; dataset.update events are generated in Audit logs when a Form adds a new property in the Dataset. The state of a Property of a Dataset is also dependent on the state of the Form that FIRST defines that Property, which means if a Form is in the Draft state then the Properties defined by that Form will not appear in the .csv file of the Dataset.