---
title: "OpenRosa Form Submission API"
method: POST
path: "/v1/projects/{projectId}/submission"
tags: ["OpenRosa Endpoints"]
---

# OpenRosa Form Submission API

`POST /v1/projects/{projectId}/submission`

This is the fully standards-compliant implementation of the [OpenRosa Form Submission API](https://bitbucket.org/javarosa/javarosa/wiki/FormSubmissionAPI). We will not attempt to redocument the submission part of the standard here, but please read further for information about _updating_ submissions with new data.

Some things to understand when using this API for any reason:

* ODK Central will always provide an `X-OpenRosa-Accept-Content-Length` of 100 megabytes. In reality, this number depends on how the server has been deployed. The default Docker-based installation, for example, is limited to 100MB at the nginx layer.

* The `xml_submission_file` may have a Content Type of either `text/xml` _or_ `application/xml`.

* Central supports the `HEAD` request preflighting recommended by the specification, but does not require it. Because our supported authentication methods do not follow the try/retry pattern, only preflight your request if you want to read the `X-OpenRosa-Accept-Content-Length` header or are concerned about the other issues listed in the standards document, like proxies.

* As stated in the standards document, it is possible to submit multimedia attachments with the `Submission` across multiple `POST` requests to this API. _However_, we impose the additional restriction that the Submission XML (`xml_submission_file`) _may not change_ between requests. If Central sees a Submission with an `instanceId` it already knows about but the XML has changed in any way, it will respond with a `409 Conflict` error and reject the submission. Additionally, a `409 Conflict` error is returned if the Submission has been deleted in Central while attempting to send further POST requests.

* Central will never return a `202` in any response from this API.

* If you haven't already, please take a look at the **HTTP Request API** notes above on the required OpenRosa headers.

You can use this endpoint to submit _updates_ to an existing submission. To do so, provide additionally a [`deprecatedID` metadata XML node](https://getodk.github.io/xforms-spec/#metadata) with the `instanceID` of the submission you are replacing. Some things to understand when submitting updates:

* The new XML entirely replaces the old XML. No merging will be performed. So your new submission must contain exactly the current data.

* If the `deprecatedID` you provide has already been deprecated, your request will be rejected with a `409 Conflict` and a useful error message.

* If the submission you are deprecating had media files uploaded for it, any of those that are still relevant will be carried over to the new version by filename reference. Any files you provide will overwrite these carryovers.

* Just as with initial submission, you can send multiple requests to this endpoint to submit additional media files if they do not comfortably fit in a single request. Also the same as initial submission, you'll need to provide exactly the same XML to make this happen. For updates, this will need to include the `deprecatedID`.

## Path parameters

- `projectId` number, required

## Headers

- `X-OpenRosa-Version` string

## Response `201`

Created

## Other responses

- `400` — This is one of several possible `400` failures the API might return:
- `409` — Conflict

## Changes

- **2025-12-20** `022694254f0d` — 1 info
  - api operation id `OpenRosa Form Submission API` removed and replaced with `openrosaSubmitForm`
- **2025-10-27** `b11b54eea487` — 1 info
  - removed the non-success response with the status `403`
- **2025-03-13** `e8c2858fd4eb` — 2 info
  - api operation id `openrosaSubmitForm` removed and replaced with `OpenRosa Form Submission API`
  - added the non-success response with the status `403`

[Change history](https://skmtc.dev/getodk/apis/odk-central-api/changes/v1/projects/:projectId/submission/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)