---
title: "Create a draft step"
method: POST
path: "/forms/{form_id}/steps"
---

# Create a draft step

`POST /forms/{form_id}/steps`

## Request

- Base URL: `https://app.formasty.com/api/v1`
- URL: `https://app.formasty.com/api/v1/forms/{form_id}/steps`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://app.formasty.com/oauth/authorize/api/v1`, token URL `https://app.formasty.com/oauth/token`)
  - HTTP bearer

Appends a step or inserts it at the requested position.

## Path parameters

- `form_id` string, required

## Request body

- object
  - `title` string
  - `fields` object[]
  - `position` integer
  - `index` integer
  - `draft_revision` integer, required

## Response `201`

Created step and updated draft revision.

- DraftMutationResponse: Updated draft fragment with draft_revision and draft_updated_at.
  - `ok` boolean
  - `step` object
  - `steps` OrderedItem[]
    - `id` string, required
    - `position` integer, required
  - `field` object
  - `fields` OrderedItem[]
    - `id` string, required
    - `position` integer, required
  - `logic` object
  - `rule` WorkflowRule: Builder-compatible workflow rule. Supports step routes, thank-you routes, and workflow variable actions.
    - `id` string, required
    - `source` object, required
      - `stepId` string, required
    - `conditions` object[]
    - `thenAction` object
    - `enabled` boolean
    - `priority` integer
  - `quiz` QuizConfig: Builder-compatible quiz config. Supports match/personality quizzes and score quizzes.
    - `type` 'match' | 'score', required
    - `mode` 'match' | 'personality'
    - `enabled` boolean, required
    - `endings` object[]
    - `mappings` object[]
    - `qualification` object
  - `screen` ThankYouScreen: Builder-compatible additional ending screen presentation payload.
    - `id` string
    - `title` string
    - `description` string
    - `message` string
    - `buttonLabel` string
    - `buttonUrl` string
    - `mediaUrl` string
    - `backgroundImageUrl` string
  - `theme` object
  - `asset` GeneratedImageAsset
    - `id` string, required
    - `url` string, required
    - `name` string
    - `contentType` string
    - `size` integer
  - `attached` boolean
  - `deleted_step_id` string
  - `deleted_field_id` string
  - `deleted_screen_id` string
  - `draft_revision` integer, required
  - `draft_updated_at` integer, required

## Other responses

- `default`: A machine-readable error with a stable code and a recovery hint. The legacy error value is retained for existing clients.

---

[API](https://skmtc.dev/formasty/apis/formasty-forms-api.md) · [All operations](https://skmtc.dev/formasty/apis/formasty-forms-api/llms.txt) · [OpenAPI document](https://skmtc.dev/formasty/apis/formasty-forms-api/revisions/09ad7f50c693?raw)