---
title: "Create or update a form version"
method: POST
path: "/api/v2/forms/{form_id}/versions"
tags: ["Forms"]
---

# Create or update a form version

`POST /api/v2/forms/{form_id}/versions`

Create or update the latest draft version of a form. The `upsert_params` field controls
optimistic concurrency behavior.

## Path parameters

- `form_id` string, uuid, required

## Request body

- UpsertFormVersionRequest — A request to create or update a form version.
  - `data` UpsertFormVersionData, required — The data for creating or updating a form version.
    - `attributes` UpsertFormVersionDataAttributes, required — The attributes for creating or updating a form version.
      - `data_definition` FormDataDefinition, required — A JSON Schema definition that describes the form's data fields.
        - `description` string — A description shown to form respondents.
        - `properties` object — A map of field names to their JSON Schema definitions.
        - `required` string[] — List of field names that must be answered.
        - `title` string — The title of the form schema.
        - `type` 'object' — The root schema type.
      - `state` 'draft' | 'frozen', required — The state of a form version.
      - `ui_definition` FormUiDefinition, required — UI configuration for rendering form fields, including widget overrides, field ordering, and themes.
        - `ui:order` string[] — The order in which form fields are displayed.
        - `ui:theme` FormUiDefinitionUiTheme — The visual theme applied to the form.
          - `primaryColor` 'gray' | 'red' | 'orange' | 'yellow' | 'green' | 'light-blue' | 'dark-blue' | 'magenta' | 'indigo' — The primary color of the form theme.
      - `upsert_params` UpsertFormVersionUpsertParams, required — Concurrency control parameters for the form version upsert operation.
        - `etag` string, nullable — The ETag of the latest version. Required when `match_policy` is `if_etag_match`.
        - `insert_only` boolean — If true, only a new version may be inserted; updating the current draft is not allowed.
        - `match_policy` 'none' | 'if_etag_match', required — The policy for matching the latest form version during an upsert operation.
    - `type` 'form_versions', required — The resource type for a form version.

## Response `200`

OK

- FormVersionResponse — A response containing a single form version.
  - `data` FormVersionData, required — A form version resource object.
    - `attributes` FormVersionAttributes, required — The attributes of a form version.
      - `created_at` string, date-time, required — The time at which the version was created.
      - `data_definition` FormDataDefinition, required — A JSON Schema definition that describes the form's data fields.
        - `description` string — A description shown to form respondents.
        - `properties` object — A map of field names to their JSON Schema definitions.
        - `required` string[] — List of field names that must be answered.
        - `title` string — The title of the form schema.
        - `type` 'object' — The root schema type.
      - `definition_signature` string, required — The signature of the version definition.
      - `etag` string, nullable, required — The ETag for optimistic concurrency control.
      - `id` string — The ID of the form version.
      - `modified_at` string, date-time, required — The time at which the version was last modified.
      - `state` 'draft' | 'frozen', required — The state of a form version.
      - `ui_definition` FormUiDefinition, required — UI configuration for rendering form fields, including widget overrides, field ordering, and themes.
        - `ui:order` string[] — The order in which form fields are displayed.
        - `ui:theme` FormUiDefinitionUiTheme — The visual theme applied to the form.
          - `primaryColor` 'gray' | 'red' | 'orange' | 'yellow' | 'green' | 'light-blue' | 'dark-blue' | 'magenta' | 'indigo' — The primary color of the form theme.
      - `user_id` integer, required — The ID of the user who created this version.
      - `user_uuid` string, uuid, required — The UUID of the user who created this version.
      - `version` integer, required — The sequential version number.
    - `id` string, required — The ID of the form version.
    - `type` 'form_versions', required — The resource type for a form version.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `429` — Too many requests

---

[API](https://skmtc.dev/datadog/apis/api-v2.md) · [All operations](https://skmtc.dev/datadog/apis/api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/datadog/api-v2/revisions/da68bf029e4c/schema)