Create Form

Create Form

POST /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	text allow: '' and null	❌	Stage title
description	text allow: '' and null	❌	Stage Description
tier	number min: 1 max: 100	❌	Order of stage 1 = first stage
responders	array objects	❌	{ userId: username }
status	text ['submitted', 'drafted', 'approved', 'rejected', 'mixed', 'canceled']	❌
dueDate	timestamp	❌
duration	number min: 0 max: timstamp	❌
minimumWeight	number min: 0	❌	minimum of approve weight before go to next stage

Create Form by single stage

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

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
        }
    ]
}'