---
title: "Create a form"
method: POST
path: "/api/v2/forms"
tags: ["Forms"]
---

# Create a form

`POST /api/v2/forms`

Create a new form. The form is created in draft mode and must be published before it can be used. This also creates a new datastore for form responses and links it to the form.

## Request body

- CreateFormRequest — A request to create a form.
  - `data` CreateFormData, required — The data for creating a form.
    - `attributes` CreateFormDataAttributes, required — The attributes for creating a form.
      - `anonymous` boolean — Whether the form accepts anonymous submissions.
      - `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.
      - `description` string — The description of the form.
      - `idp_survey` boolean — Whether the form is an IDP survey.
      - `name` string, required — The name of the form.
      - `single_response` boolean — Whether each user can only submit one response.
      - `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.
    - `type` 'forms', required — The resource type for a form.

## Response `200`

OK

- FormResponse — A response containing a single form.
  - `data` FormData, required — A form resource object.
    - `attributes` FormDataAttributes, required — The attributes of a form.
      - `active` boolean, required — Whether the form is currently active.
      - `anonymous` boolean, required — Whether the form accepts anonymous submissions.
      - `created_at` string, date-time, required — The time at which the form was created.
      - `datastore_config` FormDatastoreConfigAttributes, required — The datastore configuration for a form.
        - `datastore_id` string, uuid, required — The ID of the datastore.
        - `primary_column_name` string, required — The name of the primary column in the datastore.
        - `primary_key_generation_strategy` string, required — The strategy used to generate primary keys in the datastore.
      - `description` string, required — The description of the form.
      - `end_date` string, date-time, nullable — The date and time at which the form stops accepting responses.
      - `has_submitted` boolean, nullable — Whether the current user has already submitted this form. Only present for forms with `single_response` set to `true`.
      - `idp_survey` boolean, required — Whether the form is an IDP survey.
      - `modified_at` string, date-time, required — The time at which the form was last modified.
      - `name` string, required — The name of the form.
      - `org_id` integer, required — The ID of the organization that owns this form.
      - `publication` FormPublicationAttributes — The attributes of a form publication.
        - `created_at` string, date-time, required — The time at which the publication was created.
        - `form_id` string, uuid, required — The ID of the form.
        - `form_version` integer, required — The version number that was published.
        - `id` string — The ID of the form publication.
        - `modified_at` string, date-time, required — The time at which the publication was last modified.
        - `org_id` integer, required — The ID of the organization that owns this publication.
        - `publish_seq` integer, required — The sequential publication number for this form.
        - `user_id` integer, required — The ID of the user who created this publication.
        - `user_uuid` string, uuid, required — The UUID of the user who created this publication.
      - `self_service` boolean, required — Whether the form is available in the self-service catalog.
      - `single_response` boolean, required — Whether each user can only submit one response.
      - `user_id` integer, required — The ID of the user who created this form.
      - `user_uuid` string, uuid, required — The UUID of the user who created this form.
      - `version` FormVersionAttributes — 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, uuid, required — The ID of the form.
    - `type` 'forms', required — The resource type for a form.

## Other responses

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

---

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