Skip to content
Amity SolutionsAmity SolutionsAmity Solutions Docs

Create Form

Create Form

Section titled “Create Form”

POST /v1/forms

Headers

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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
        }
    ]
}'