# Create Form

## Create Form

<mark class="gb-c-blue">POST</mark> `/v1/forms`

#### Headers
| Header         | Type     | Required | Description                                       |
| -------------- | -------- | -------- | ------------------------------------------------- |
| `accept`       | `string` | ✅        | Expected response format. Use `application/json`. |
| `content-type` | `string` | ✅        | Request body format. Use `application/json`.      |
| `X-API-Key`    | `string` | ✅        | API key for authentication.                       |
| `X-API-Token`  | `string` | ✅        | Token identifying the current user or session.    |

#### Body

| Field             | Type            | Required | Description                                                        |
| ----------------- | --------------- | -------- | ------------------------------------------------------------------ |
| `name`            | `string`        | ✅        | The title or name of the form.                                     |
| `subject`         | `string`        | ✅        | Subject line or short summary.                                     |
| `dueDate`         | `string (date)` | ❌        | Due date in `YYYY-MM-DD` format.                                   |
| `senderUserId`    | `string`        | ✅        | User ID (username) of the form sender.                             |
| `receiverUserIds` | `array[string]` | ✅        | List of recipient user IDs (usernames).                            |
| `data`            | `array[object]` | ✅        | Array describing the input fields within the form.                 |
| `status`          | `string`        | ✅        | Status of the form — e.g., `drafted`, `published`, or `completed`. |
| `responseType`    | `string`        | ❌        | type of stage: hierarchy                                           |
| `responseTiers`   | `array[object]` | ❌        | object of response tiers payload                                   |

#### ResponseTiers Object
| Field         | Type                                                                                               | Required | Description                                       |
| ------------- | -------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------- |
| title         | <p>text<br>allow: '' and null</p>                                                                  | ❌        | Stage title                                       |
| description   | <p>text<br>allow: '' and null</p>                                                                  | ❌        | Stage Description                                 |
| tier          | <p>number<br>min: 1<br>max: 100</p>                                                                | ❌        | <p> Order of stage<br>1 = first stage</p>         |
| responders    | array objects                                                                                      | ❌        | <p>{<br>userId: username<br>}</p>                 |
| status        | <p>text<br>\[<code>'submitted', 'drafted', 'approved', 'rejected', 'mixed', 'canceled'</code>]</p> | ❌        |                                                   |
| dueDate       | timestamp                                                                                          | ❌        |                                                   |
| duration      | <p>number<br>min: 0<br>max: timstamp</p>                                                           | ❌        |                                                   |
| minimumWeight | <p>number<br>min: 0</p>                                                                            | ❌        | minimum of approve weight before go to next stage |

### Create Form by single stage

```json wrap showLineNumbers
curl --location '{{domain}}/v1/forms' \
--header 'accept: application/json' \
--header 'X-API-Key: x-api-key' \
--header 'X-API-Token: x-api-token' \
--header 'content-type: application/json' \
--data-raw '{
  "name": "Example Form",
  "subject": "Example",
  "dueDate": "2025-09-30",
  "senderUserId": "senderUserId",
  "receiverUserIds": ["receiverUserIds"],
  "data": [
    {
      "type": "textinput",
      "name": "Field 1 (text)",
      "value": "this is the best form",
      "meta": {},
      "editable": true
    },
    {
      "type": "radio",
      "name": "Field 2 (radio)",
      "meta": {
        "options": [{
          "label": "Yes",
          "value": "a1"
        }, {
          "label": "No",
          "value": "a2"
        }]
      },
      "editable": true
    },
    {
      "type": "action",
      "name": "Action Buttons",
      "meta": {
        "options": [{
          "label": "APPROVE no val",
          "type": "approved"
        },{
          "label": "REJECT",
          "type": "rejected",
          "value": "1"
          },{
          "label": "OTHER Action",
          "type": "other",
          "value": "2",
          "color": "#000000"
        }]
      }
    }
  ],
  "status": "submitted"
}'
```

### Create Form by sequence stage & Parallel

```json wrap showLineNumbers
curl --location '{{domain}}/v1/forms' \
--header 'accept: application/json' \
--header 'X-API-Key: x-api-key' \
--header 'X-API-Token: x-api-token' \
--header 'content-type: application/json' \
--data-raw '{
    "name": "Example Form",
    "subject": "Example",
    "dueDate": "2025-09-30",
    "senderUserId": "senderUsername",
    "receiverUserIds": [
        "receiverUsername"
    ],
    "data": [
        {
            "type": "textinput",
            "name": "Field 1 (text)",
            "value": "this is the best form",
            "meta": {},
            "editable": true
        },
        {
            "type": "radio",
            "name": "Field 2 (radio)",
            "meta": {
                "options": [
                    {
                        "label": "Yes",
                        "value": "a1"
                    },
                    {
                        "label": "No",
                        "value": "a2"
                    }
                ]
            },
            "editable": true
        },
        {
            "type": "action",
            "name": "Action Buttons",
            "meta": {
                "options": [
                    {
                        "label": "APPROVE no val",
                        "type": "approved"
                    },
                    {
                        "label": "REJECT",
                        "type": "rejected",
                        "value": "1"
                    },
                    {
                        "label": "OTHER Action",
                        "type": "other",
                        "value": "2",
                        "color": "#000000"
                    }
                ]
            }
        }
    ],
    "status": "submitted",
    "responseType": "hierarchy",
    "responseTiers": [
        {
            "description": "tier1 description",
            "title": "tier1 title",
            "tier": 1,
            "allowedResponders": [
                {
                    "type": "user",
                    "entityId": "receiverUsername1",
                    "weight": 1
                },
                {
                    "type": "user",
                    "entityId": "receiverUsername2",
                    "weight": 1
                }
            ],
            "responders": [
                {
                    "userId": "receiverUsername1"
                },
                                {
                    "userId": "receiverUsername2"
                }
            ],
            "minimumWeight": 2
        },
        {
            "description": "tier2 description",
            "title": "tier2 title",
            "tier": 2,
            "allowedResponders": [
                {
                    "type": "user",
                    "entityId": "receiverUsername3",
                    "weight": 1
                }
            ],
            "responders": [
                {
                    "userId": "receiverUsername3"
                }
            ],
            "minimumWeight": 1
        }
    ]
}'
```