--- title: "Creating a new Form" method: POST path: "/v1/projects/{projectId}/forms" tags: ["Forms"] --- # Creating a new Form `POST /v1/projects/{projectId}/forms` 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](/central-api-form-management/#publishing-a-draft-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](https://getodk.org/use/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](https://docs.getodk.org/central-forms/#central-forms-updates) - Deleted Form: Returned when there is a form with the same ID in the Trash. [Learn more](https://docs.getodk.org/central-forms/#deleting-a-form) **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](/central-api-dataset-management), however the [Related Datasets](/central-api-form-management/#draft-form-dataset-diff) 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](/central-api-dataset-management/#download-dataset) of the Dataset. ## Path parameters - `projectId` number, required ## Query parameters - `ignoreWarnings` boolean - `publish` boolean ## Headers - `X-XlsForm-FormId-Fallback` string ## Response `200` OK - object - `projectId` number, required — The `id` of the project this form belongs to. - `xmlFormId` string, required — The `id` of this form as given in its XForms XML definition - `name` string — The friendly name of this form. It is given by the `` in the XForms XML definition. - `version` string, 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. - `enketoId` string — 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. - `hash` string, required — An MD5 sum automatically computed based on the XForms XML definition. This is required for OpenRosa compliance. - `keyId` number — 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. - `publishedAt` string — 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. - `createdAt` string, required — ISO date format - `updatedAt` string — ISO date format ## Other responses - `400` — Bad Request - `409` — Conflict ## Changes - **2025-12-20** `022694254f0d` — 1 info - api operation id `Creating a new Form` removed and replaced with `createForm` - **2025-10-27** `b11b54eea487` — 1 info - removed the non-success response with the status `403` - **2025-03-13** `e8c2858fd4eb` — 2 info - api operation id `createForm` removed and replaced with `Creating a new Form` - added the non-success response with the status `403` [Change history](https://skmtc.dev/getodk/apis/odk-central-api/changes/v1/projects/:projectId/forms/post.md) --- [API](https://skmtc.dev/getodk/apis/odk-central-api.md) · [All operations](https://skmtc.dev/getodk/apis/odk-central-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getodk/odk-central-api/revisions/d4f5ba77f644/schema)