Skip to content

Create a form field

POST
/v1/forms/{form}/fields
curl --request POST \
  --url https://api.submeto.com/v1/forms/example/fields \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "label": "example", "type": "string", "required": true, "options": {}, "validation": "email" }'

Adds a field to a form. Requires the forms:update scope, an Idempotency-Key header, and an If-Match header carrying the current Form validator. Field validation accepts only a reviewed validation preset, never raw regex.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
form
required
string

The form ID.

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
If-Match
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required

Must match the regex /^[a-z][a-z0-9_]{0,63}$/.

string
label

Must not be greater than 255 characters.

string
nullable
type
required
string
Allowed values: string number date boolean array file
required
required
boolean
options
One of:
object
key
additional properties
any
validation
string
nullable
Allowed values: email url tel ipv4 ipv6 uuid slug hex_color alpha_numeric integer

Responses

Section titled “Responses”

201

Section titled “201”

Field created

Media typeapplication/json
object
data
object
id
string
name
string
label
string
type
string
required
boolean
options
string
nullable
validation
object
kind
string
preset
string
position
integer
created_at
string
updated_at
string
request_id
string
Example
{
  "data": {
    "id": "REQUEST_ID",
    "name": "email",
    "label": "Email",
    "type": "string",
    "required": true,
    "options": null,
    "validation": {
      "kind": "preset",
      "preset": "email"
    },
    "position": 4,
    "created_at": "2026-08-31T10:00:00.000Z",
    "updated_at": "2026-08-31T10:00:00.000Z"
  },
  "request_id": "REQUEST_ID"
}

400

Section titled “400”

Missing idempotency key

Media typeapplication/json
object
error
object
code
string
message
string
details
object
request_id
string
Example
{
  "error": {
    "code": "idempotency_key_required",
    "message": "The Idempotency-Key header is required.",
    "details": {}
  },
  "request_id": "REQUEST_ID"
}

412

Section titled “412”

Stale ETag

Media typeapplication/json
object
error
object
code
string
message
string
details
object
request_id
string
Example
{
  "error": {
    "code": "precondition_failed",
    "message": "The Form revision does not match the If-Match ETag.",
    "details": {}
  },
  "request_id": "REQUEST_ID"
}

422

Section titled “422”

Validation failed

Media typeapplication/json
object
error
object
code
string
message
string
details
object
name
Array<string>
request_id
string
Example
{
  "error": {
    "code": "validation_failed",
    "message": "The request validation failed.",
    "details": {
      "name": [
        "The name field is required."
      ]
    }
  },
  "request_id": "REQUEST_ID"
}

428

Section titled “428”

Missing If-Match

Media typeapplication/json
object
error
object
code
string
message
string
details
object
request_id
string
Example
{
  "error": {
    "code": "precondition_required",
    "message": "A current If-Match Form validator is required.",
    "details": {}
  },
  "request_id": "REQUEST_ID"
}