Beautiful Open-Source Form Builder
---
openapi: put /open/forms/{id}
---
# Update Form
Update an existing form. You can modify any attribute that can be set when creating a form.
## Authentication & Scope
Requires a token with the `forms-write` ability.
## Request
```http
PUT /open/forms/{id} HTTP/1.1
Host: api.opnform.com
Content-Type: application/json
Authorization: Bearer <token>
```
### Path Parameters
| Parameter | Type | Description |
| --------- | ------ | ------------------------------ |
| id | number | Numeric ID of the form to edit |
### Body Parameters
All fields from the [Create Form](./create-form) endpoint may be supplied. However, **the API validation requires you to include specific fields** in every update request, even if you only want to change one optional field.
#### Required Fields in Updates
These fields must always be included:
| Field | Type | Description |
| ---------------------- | ------- | -------------------------------------------------------------------- |
| title | string | Form title (max 60 characters) |
| visibility | string | Form visibility state (`"public"`, `"closed"`, `"draft"`) |
| language | string | Two-letter ISO language code (e.g. `en`) |
| theme | string | Form theme |
| presentation_style | string | How the form is presented |
| width | string | Form container width |
| size | string | Form text size |
| border_radius | string | Form border radius |
| dark_mode | string | Dark mode setting |
| color | string | Primary color (hex format) |
| uppercase_labels | boolean | Whether labels should be uppercase |
| no_branding | boolean | Hide OpnForm branding |
| transparent_background | boolean | Use transparent background |
| properties | array | Array of form fields/blocks — **must never be empty**, or existing properties will be lost |
| …other fields | mixed | All other fields from Create Form (description, logo_picture, etc.) |
<Warning>
**Important:** Omitting any of the required fields will result in a validation error. You must include all these fields in your update request, even if you're only changing one optional field. Additionally, the `properties` array cannot be empty — always send your complete form fields.
</Warning>
### Recommended Update Pattern
To safely update a form without accidentally losing properties:
1. **Fetch** the current form state using the [Get Form](./get-form) endpoint
2. **Modify** only the fields you want to change in the fetched response
3. **Send** the complete updated form (including all required fields and properties) back to this endpoint
This ensures you retain all existing form fields and don't accidentally overwrite them with empty arrays.
<Tip>
**Best Practice Example:** If you only want to change form visibility, fetch the form first, update only the `visibility` field locally, then send the complete form back with all its properties intact.
</Tip>
### Custom SEO and link previews
On OpnForm Cloud, Pro and higher plans can publish a custom page title, description, link preview image, and favicon on both OpnForm URLs and custom domains. Supply these settings in `seo_meta`:
```json
{
"seo_meta": {
"page_title": "Contact our team",
"page_description": "Send us your questions and we will get back to you.",
"page_thumbnail": "https://example.com/form-preview.png",
"page_favicon": "https://example.com/favicon.png"
}
}
```
Include the required form fields described above alongside `seo_meta`. Free workspaces can save these settings for preview, but they are omitted from the public form until the workspace upgrades.
### Automatically delete old submissions
Set `submission_retention_value` and `submission_retention_unit` together to permanently delete submissions after a retention period. The period is measured from each submission's last update, and the cleanup runs hourly.
```json
{
"submission_retention_value": 3,
"submission_retention_unit": "day"
}
```
The unit accepts `day`, `week`, `month`, or `year`. Set both fields to `null` to disable automatic deletion.
<Warning>
Expired submissions, uploaded files, and submission versions are permanently deleted and cannot be restored. Shortening an existing retention period can make older submissions eligible during the next hourly cleanup.
</Warning>
### Body Example
Example request updating title and visibility (note: all required fields must be included):
```json
{
"title": "Customer Feedback (v2)",
"visibility": "closed",
"language": "en",
"theme": "light",
"presentation_style": "default",
"width": "normal",
"size": "medium",
"border_radius": "medium",
"dark_mode": "off",
"color": "#3b82f6",
"uppercase_labels": false,
"no_branding": false,
"transparent_background": false,
"properties": [
{
"id": "field-1",
"type": "short_text",
"name": "First name",
"required": true
}
],
"closed_text": "Form is currently closed"
}
```
## Response
`200 OK` – Returns the updated `Form` object.
`403 Forbidden` – The token lacks `forms-write` or you don't have permission.