Add a field to a form
/forms/{form_id}/fieldsAdds a field to the form and returns it with a Location. type is required; without order the field goes last. Put requiredness in validator, such as required|string. page_id must be a page of this form and option_preset_id a live preset, else 422 exists. conditions may target only fields of this form. To add fields that point at each other, send them together to POST /forms. dry_run shows the result without saving it. Emits form_field.created; no email. DELETE /forms/{form_id}/fields/{id} undoes it.
Path parameters
The form's id, a uuid. An unknown id, or a hidden form, returns 404.
Query parameters
Validate and run the call without committing it, returning what the real call would return with
meta.dry_runset.
Headers
Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.
Request body
application/json, required · FormFieldCreate
The field type, such as TEXT, BIGTEXT, INTEGER, EMAIL, DATE, DROPDOWN, CHECKBOX, CURRENCY, OPTION_SELECT, FILE_UPLOAD or SIGNATURE.
The question shown to the person filling in the form.
The field's short name.
Help text shown under the question.
A key that stays stable across edits, unique within the form.
Validation rules separated by a pipe, such as required|string.
Placeholder text.
The profile value that pre-fills this field.
Whether the answer is written back to the profile.
The field's position within the form.
A page of this form to place the field on.
A live option preset a dropdown field takes its options from.
The options of a dropdown or similar field. A list for most types; an object for a DOCUSIGN field.
- One of:
Whether all conditions (AND) or any one (OR) must hold. AND unless set.
AND,OR Display conditions. Every controlling field must be a field of this form.
{
"type": "TEXT",
"label": "Spouse name",
"reference": "spouse_name",
"validator": "required|string",
"order": 2,
"conditions": [
{
"against_field_reference": "marital_status",
"operator": "=",
"value": "married"
}
]
}Responses
{
"data": {
"id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"label": "string",
"name": "string",
"description": "string",
"type": "string",
"reference": "string",
"validator": "string",
"placeholder": "string",
"pre_population_key": "string",
"backfill": true,
"order": 1,
"page_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"option_preset_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"options": [
null
],
"required": true,
"conditions": [
{
"against_field_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"against_field_reference": "string",
"operator": "string",
"value": "string"
}
],
"condition_logic": "AND"
}
}Authorization failed. error.code is one of org_disabled,
ip_blocked, missing_scope, scope_disabled, user_disabled.
The request conflicts with existing state (error.code = conflict),
e.g. a compliance flow with the requested name already exists.
The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per
problem, or a code documented on the operation.
Examples
curl -X POST https://your-org-domain/kong/core/api/v2/forms/{form_id}/fields\
-H "Authorization: Bearer $HELM_API_KEY"\
-H "Content-Type: application/json"\
-d '{
"type": "TEXT",
"label": "Spouse name",
"reference": "spouse_name",
"validator": "required|string",
"order": 2,
"conditions": [
{
"against_field_reference": "marital_status",
"operator": "=",
"value": "married"
}
]
}'