> ## Documentation Index > Fetch the complete documentation index at: https://docs.opnform.com/llms.txt > Use this file to discover all available pages before exploring further. # Update Form > Update an existing form. Requires `forms-write`. # 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 theme={null} PUT /open/forms/{id} HTTP/1.1 Host: api.opnform.com Content-Type: application/json Authorization: Bearer ``` ### 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.) | **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. ### 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. **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. ### 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 theme={null} { "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. 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. ### Body Example Example request updating title and visibility (note: all required fields must be included): ```json theme={null} { "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. ## OpenAPI ````yaml put /open/forms/{id} openapi: 3.0.1 info: title: OpnForm API description: API for interacting with OpnForm, primarily used for Zapier integration version: 1.0.0 servers: - url: https://api.opnform.com security: - bearerAuth: [] tags: - name: Workspaces description: Create and manage workspaces. - name: Workspace Users description: Manage users within a workspace. - name: Forms description: Manage and retrieve forms. - name: Submissions description: Access and manage form submissions. - name: Integrations description: Manage form integrations (webhooks) via API. - name: Zapier description: Legacy endpoints for the Zapier integration. paths: /open/forms/{id}: put: tags: - Forms summary: Update Form description: Update an existing form. Requires `forms-write`. parameters: - name: id in: path required: true schema: type: number requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Form' responses: '200': description: Updated content: application/json: schema: $ref: '#/components/schemas/Form' '403': description: Forbidden – token lacks forms-write ability security: - bearerAuth: [] components: schemas: Form: type: object properties: id: type: number description: The unique identifier for the form. readOnly: true slug: type: string description: The URL-friendly slug for the form. readOnly: true workspace_id: type: number description: ID of the workspace that owns the form. writeOnly: true title: type: string description: The title of the form. visibility: type: string enum: - public - draft - closed description: The current visibility state of the form. tags: type: array items: type: string nullable: true language: type: string description: Two-letter ISO language code. custom_domain: type: string nullable: true theme: type: string enum: - default - simple - notion font_family: type: string nullable: true color: type: string dark_mode: type: string enum: - light - dark - auto width: type: string enum: - centered - full size: type: string enum: - sm - md - lg border_radius: type: string enum: - none - small - full layout_rtl: type: boolean uppercase_labels: type: boolean cover_picture: type: string format: uri nullable: true logo_picture: type: string format: uri nullable: true no_branding: type: boolean description: Whether to hide the OpnForm branding. transparent_background: type: boolean description: Transparent background when form is embedded. submit_button_text: type: string maxLength: 50 submitted_text: type: string maxLength: 2000 redirect_url: type: string format: uri nullable: true re_fillable: type: boolean re_fill_button_text: type: string maxLength: 50 confetti_on_submission: type: boolean show_progress_bar: type: boolean submission_retention_value: type: integer minimum: 1 maximum: 3650 nullable: true description: >- Number of retention units before a submission is permanently deleted. Set this and submission_retention_unit to null to disable automatic deletion. submission_retention_unit: type: string enum: - day - week - month - year nullable: true description: >- Calendar unit used by submission_retention_value. Both retention fields must be provided together. closes_at: type: string format: date-time nullable: true closed_text: type: string nullable: true max_submissions_count: type: integer minimum: 1 nullable: true max_submissions_reached_text: type: string nullable: true auto_save: type: boolean auto_focus: type: boolean enable_partial_submissions: type: boolean editable_submissions: type: boolean editable_submissions_button_text: type: string maxLength: 50 password: type: string nullable: true use_captcha: type: boolean captcha_provider: type: string enum: - recaptcha - hcaptcha can_be_indexed: type: boolean seo_meta: type: object nullable: true custom_code: type: string nullable: true database_fields_update: type: array items: {} nullable: true properties: type: array description: An array of field and layout blocks that make up the form. items: $ref: '#/components/schemas/FormProperty' FormProperty: type: object description: A single field or layout block within a form. properties: id: type: string description: A unique identifier for the block. format: uuid type: type: string description: The type of block. name: type: string description: The label or name of the field. help: type: string description: Help text displayed with the field. hidden: type: boolean description: Whether the field is hidden from view. required: type: boolean description: Whether the field is required. placeholder: type: string description: Placeholder text for the input. width: type: string enum: - full - 1/2 - 1/3 - 2/3 - 1/4 - 3/4 description: The width of the block in the form layout. additionalProperties: true securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Personal Access Token x-bearer-scopemap: workspaces-read: Read access to workspaces workspaces-write: Write access to workspaces workspace-users-read: Read access to workspace users workspace-users-write: Write access to workspace users forms-read: Read access to forms forms-write: Write access to forms manage-integrations: Manage form integrations (webhooks) ````