---
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`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/forms/{form_id}/versions`
- Auth: API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`

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/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/da68bf029e4c?raw)